feat: add MCP tool call result callback

## Summary
- Refresh runtime handling around session and tool-call flows.
- Adjust model configuration metadata used by runtime integrations.
- Add focused coverage for the updated behavior.

## Validation
- .venv/bin/python -m pytest tests/model_settings/test_serialization.py
tests/models/test_trace_config.py
tests/mcp/test_streamable_http_client_factory.py
tests/test_run_context_approvals.py
tests/test_run_state.py::TestRunState::test_trace_api_key_serialization_is_opt_in
tests/realtime/test_session.py
- .venv/bin/ruff check <touched files>
- .venv/bin/ruff format --check <touched files>
- git diff --check

.agents/skills/examples-auto-run/SKILL.md

@@ -8,6 +8,8 @@ description: Run python examples in auto mode with logging, rerun helpers, and b
 ## What it does
 
 - Runs `uv run examples/run_examples.py` with:
+  - Optional dependency extras enabled by default:
+    `litellm`, `any-llm`, `sqlalchemy`, `redis`, `blaxel`, `modal`, `runloop`, and `temporal`.
   - `EXAMPLES_INTERACTIVE_MODE=auto` (auto-input/auto-approve).
   - Per-example logs under `.tmp/examples-start-logs/`.
   - Main summary log path passed via `--main-log` (also under `.tmp/examples-start-logs/`).
@@ -44,6 +46,16 @@ description: Run python examples in auto mode with logging, rerun helpers, and b
 .agents/skills/examples-auto-run/scripts/run.sh rerun
 ```
 
+## Codex execution environment
+
+- When Codex invokes `start` or `rerun`, run the command outside the Codex sandbox by default
+  (`sandbox_permissions=require_escalated`). Many examples start nested sandboxes, browsers, npm
+  helpers, or cloud/local service processes; running from inside the Codex sandbox can produce
+  environment-only failures such as `sandbox-exec: sandbox_apply: Operation not permitted`,
+  Playwright cache permission errors, or npm cache permission errors.
+- Use sandboxed execution only when the user explicitly asks for it or when running a narrow dry-run
+  / log inspection command that does not execute examples.
+
 ## Defaults (overridable via env)
 
 - `EXAMPLES_INTERACTIVE_MODE=auto`
@@ -51,6 +63,7 @@ description: Run python examples in auto mode with logging, rerun helpers, and b
 - `EXAMPLES_INCLUDE_SERVER=0`
 - `EXAMPLES_INCLUDE_AUDIO=0`
 - `EXAMPLES_INCLUDE_EXTERNAL=0`
+- `EXAMPLES_UV_EXTRAS="litellm any-llm sqlalchemy redis blaxel modal runloop temporal"` (set to an empty string to disable extras)
 - Auto-approvals in auto mode: `APPLY_PATCH_AUTO_APPROVE=1`, `SHELL_AUTO_APPROVE=1`, `AUTO_APPROVE_MCP=1`
 
 ## Log locations
@@ -62,7 +75,7 @@ description: Run python examples in auto mode with logging, rerun helpers, and b
 
 ## Notes
 
-- The runner delegates to `uv run examples/run_examples.py`, which already writes per-example logs and supports `--collect`, `--rerun-file`, and `--print-auto-skip`.
+- The runner delegates to `uv run --extra ... examples/run_examples.py`, which already writes per-example logs and supports `--collect`, `--rerun-file`, and `--print-auto-skip`.
 - `start` uses `--write-rerun` so failures are captured automatically.
 - If `.tmp/examples-rerun.txt` exists and is non-empty, invoking the skill with no args runs `rerun` by default.
 

.agents/skills/examples-auto-run/scripts/run.sh

@@ -5,6 +5,23 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
 PID_FILE="$ROOT/.tmp/examples-auto-run.pid"
 LOG_DIR="$ROOT/.tmp/examples-start-logs"
 RERUN_FILE="$ROOT/.tmp/examples-rerun.txt"
+DEFAULT_UV_EXTRAS="litellm any-llm sqlalchemy redis blaxel modal runloop temporal"
+
+build_uv_prefix() {
+  UV_RUN=(uv run)
+  local extras_value
+  if [[ -n "${EXAMPLES_UV_EXTRAS+x}" ]]; then
+    extras_value="$EXAMPLES_UV_EXTRAS"
+  else
+    extras_value="$DEFAULT_UV_EXTRAS"
+  fi
+
+  local extra
+  for extra in $extras_value; do
+    UV_RUN+=(--extra "$extra")
+  done
+  export EXAMPLES_UV_EXTRAS="$extras_value"
+}
 
 ensure_dirs() {
   mkdir -p "$LOG_DIR" "$ROOT/.tmp"
@@ -28,8 +45,9 @@ cmd_start() {
   main_log="$LOG_DIR/main_${ts}.log"
   stdout_log="$LOG_DIR/stdout_${ts}.log"
 
+  build_uv_prefix
   local run_cmd=(
-    uv run examples/run_examples.py
+    "${UV_RUN[@]}" examples/run_examples.py
     --auto-mode
     --write-rerun
     --main-log "$main_log"
@@ -152,7 +170,8 @@ collect_rerun() {
     exit 1
   fi
   cd "$ROOT"
-  uv run examples/run_examples.py --collect "$log_file" --output "$RERUN_FILE"
+  build_uv_prefix
+  "${UV_RUN[@]}" examples/run_examples.py --collect "$log_file" --output "$RERUN_FILE"
 }
 
 cmd_rerun() {
@@ -171,8 +190,9 @@ cmd_rerun() {
   export APPLY_PATCH_AUTO_APPROVE="${APPLY_PATCH_AUTO_APPROVE:-1}"
   export SHELL_AUTO_APPROVE="${SHELL_AUTO_APPROVE:-1}"
   export AUTO_APPROVE_MCP="${AUTO_APPROVE_MCP:-1}"
+  build_uv_prefix
   set +e
-  uv run examples/run_examples.py --auto-mode --rerun-file "$file" --write-rerun --main-log "$main_log" --logs-dir "$LOG_DIR" 2>&1 | tee "$stdout_log"
+  "${UV_RUN[@]}" examples/run_examples.py --auto-mode --rerun-file "$file" --write-rerun --main-log "$main_log" --logs-dir "$LOG_DIR" 2>&1 | tee "$stdout_log"
   local run_status=${PIPESTATUS[0]}
   set -e
   return "$run_status"
@@ -194,6 +214,7 @@ Commands:
 Environment overrides:
   EXAMPLES_INTERACTIVE_MODE (default auto)
   EXAMPLES_INCLUDE_SERVER/INTERACTIVE/AUDIO/EXTERNAL (defaults: 0/1/0/0)
+  EXAMPLES_UV_EXTRAS (default: litellm any-llm sqlalchemy redis blaxel modal runloop; set empty to disable)
   APPLY_PATCH_AUTO_APPROVE, SHELL_AUTO_APPROVE, AUTO_APPROVE_MCP (default 1 in auto mode)
 EOF
 }

.agents/skills/implementation-strategy/SKILL.md

@@ -38,6 +38,15 @@ Use this skill before editing code when the task changes runtime behavior or any
 - If review feedback claims a change is breaking, verify it against the latest release tag and actual external impact before accepting the feedback.
 - If a change truly crosses the latest released contract boundary, call that out explicitly in the ExecPlan, release notes context, and user-facing summary.
 
+## SDK-specific decision rules
+
+- When unsupported OpenAI API or provider-adapter behavior already has a released default path, avoid turning it into a default hard error unless the latest release boundary justifies that break. Prefer an opt-in strict mode such as `strict_feature_validation=True`, while keeping the default path compatible through warning, ignoring unsupported data, or a clearly non-empty placeholder.
+- For OpenAI API feature gaps, evaluate streaming and non-streaming paths together. Custom tool calls, multi-choice Chat Completions chunks, non-text tool outputs, and similar provider payload differences must not be strict in one path and permissive or malformed in the other.
+- When a change creates new public SDK behavior, do not expose it only through hard-coded module globals. Prefer an explicit public configuration object or parameter, preserve the existing default behavior when compatibility-sensitive, and make opt-in SDK defaults explicit.
+- Append new optional fields or constructor parameters to public dataclasses and constructors. Do not insert them before existing public fields unless you also provide a compatibility layer and regression coverage for the old positional call shape.
+- Treat threshold and quota values as part of the API design when they affect runtime behavior. Distinguish OpenAI platform quota-derived values from defensive SDK defaults; if the value is not anchored in a documented platform limit, avoid making it an unconditional default-on behavior.
+- Define `None` semantics deliberately for public configuration. For example, use separate meanings for "feature disabled or no SDK limit", "use SDK default limits", and "disable only this specific limit" rather than relying on implicit truthiness checks.
+
 ## When to stop and confirm
 
 - The change would alter behavior shipped in the latest release tag.

.github/codex/prompts/pr-labels.md

@@ -1,73 +0,0 @@
-# PR auto-labeling
-
-You are Codex running in CI to propose labels for a pull request in the openai-agents-python repository.
-
-Inputs:
-- PR context: .tmp/pr-labels/pr-context.json
-- PR diff: .tmp/pr-labels/changes.diff
-- Changed files: .tmp/pr-labels/changed-files.txt
-
-Task:
-- Inspect the PR context, diff, and changed files.
-- Output JSON with a single top-level key: "labels" (array of strings).
-- Only use labels from the allowed list.
-- Prefer false negatives over false positives. If you are unsure, leave the label out.
-- Return the smallest accurate set of labels for the PR's primary intent and primary surface area.
-
-Allowed labels:
-- documentation
-- project
-- bug
-- enhancement
-- dependencies
-- feature:chat-completions
-- feature:core
-- feature:extensions
-- feature:mcp
-- feature:realtime
-- feature:sandboxes
-- feature:sessions
-- feature:tracing
-- feature:voice
-
-Important guidance:
-- `documentation`, `project`, and `dependencies` are also derived deterministically elsewhere in the workflow. You may include them when the evidence is explicit, but do not stretch to infer them from weak signals.
-- Use direct evidence from changed implementation files and the dominant intent of the diff. Do not add labels based only on tests, examples, comments, docstrings, imports, type plumbing, or shared helpers.
-- Cross-cutting features often touch many adapters and support layers. Only add a `feature:*` label when that area is itself a primary user-facing surface of the PR, not when it receives incidental compatibility or parity updates.
-- Mentions of a feature area in helper names, comments, tests, or trace metadata are not enough by themselves.
-- Prefer the most general accurate feature label over a larger set of narrower labels. For broad runtime work, this usually means `feature:core`.
-- A secondary `feature:*` label needs two things: a non-test implementation/docs change in that area, and evidence that the area is a user-facing outcome of the PR rather than support work for another feature.
-
-Label rules:
-- documentation: Documentation changes (docs/), or src/ changes that only modify comments/docstrings without behavior changes. If only comments/docstrings change in src/, do not add bug/enhancement.
-- project: Any change to pyproject.toml.
-- dependencies: Dependencies are added/removed/updated (pyproject.toml dependency sections or uv.lock changes).
-- bug: The PR's primary intent is to correct existing incorrect behavior. Use only with strong evidence such as the title/body/tests clearly describing a fix, regression, crash, incorrect output, or restore/preserve behavior. Do not add `bug` for incidental hardening that accompanies a new feature.
-- enhancement: The PR's primary intent is to add or expand functionality. Prefer `enhancement` for feature work even if the diff also contains some fixes or guardrails needed to support that feature.
-- bug vs enhancement: Prefer exactly one of these. Include both only when the PR clearly contains two separate substantial changes and both are first-order outcomes.
-- feature:chat-completions: Chat Completions support or conversion is a primary deliverable of the PR. Do not add it for a small compatibility guard or parity update in `chatcmpl_converter.py`.
-- feature:core: Core agent loop, tool calls, run pipeline, or other central runtime behavior is a primary surface of the PR. For cross-cutting runtime changes, this is usually the single best feature label.
-- feature:extensions: `src/agents/extensions/` surfaces are a primary deliverable of the PR, including extension models/providers such as Any-LLM and LiteLLM. Changes under `src/agents/extensions/sandbox/` can warrant this label alongside `feature:sandboxes`.
-- feature:mcp: MCP-specific behavior or APIs are a primary deliverable of the PR. Do not add it for incidental hosted/deferred tool plumbing touched by broader runtime work.
-- feature:realtime: Realtime-specific behavior, API shape, or session semantics are a primary deliverable of the PR. Do not add it for small parity updates in realtime adapters.
-- feature:sandboxes: Sandbox runtime or sandbox extension behavior is a primary deliverable of the PR, including changes under `src/agents/sandbox/` and `src/agents/extensions/sandbox/`. Prefer this over `feature:core` for sandbox-focused work; for `src/agents/extensions/sandbox/`, `feature:extensions` may also be appropriate.
-- feature:sessions: Session or memory behavior is a primary deliverable of the PR. Do not add it for persistence updates that merely support a broader feature.
-- feature:tracing: Tracing is a primary deliverable of the PR. Do not add it for trace naming or metadata changes that accompany another feature.
-- feature:voice: Voice pipeline behavior is a primary deliverable of the PR.
-
-Decision process:
-1. Determine the PR's primary intent in one sentence from the PR title/body and dominant runtime diff.
-2. Start with zero labels.
-3. Add `bug` or `enhancement` conservatively.
-4. Add only the minimum `feature:*` labels needed to describe the primary surface area.
-5. Treat extra `feature:*` labels as guilty until proven necessary. Keep them only when the PR would feel mislabeled without them.
-6. Re-check every label. Drop any label that is supported only by secondary edits, parity work, or touched files outside the PR's main focus.
-
-Examples:
-- If a new cross-cutting runtime feature touches Chat Completions, Realtime, Sessions, MCP, and tracing support code for parity, prefer `["enhancement","feature:core"]` over labeling every touched area.
-- If a PR mainly adds a Responses/core capability and touches realtime or sessions files only to keep shared serialization, replay, or adapters in sync, do not add `feature:realtime` or `feature:sessions`.
-- If a PR mainly fixes realtime transport behavior and also updates tests/docs, prefer `["bug","feature:realtime"]`.
-
-Output:
-- JSON only (no code fences, no extra text).
-- Example: {"labels":["enhancement","feature:core"]}

.github/codex/prompts/release-review.md

@@ -1,23 +0,0 @@
-# Release readiness review
-
-You are Codex running in CI. Produce a release readiness report for this repository.
-
-Steps:
-1. Determine the latest release tag (use local tags only):
-   - `git tag -l 'v*' --sort=-v:refname | head -n1`
-2. Set TARGET to the current commit SHA: `git rev-parse HEAD`.
-3. Collect diff context for BASE_TAG...TARGET:
-   - `git diff --stat BASE_TAG...TARGET`
-   - `git diff --dirstat=files,0 BASE_TAG...TARGET`
-   - `git diff --name-status BASE_TAG...TARGET`
-   - `git log --oneline --reverse BASE_TAG..TARGET`
-4. Review `.agents/skills/final-release-review/references/review-checklist.md` and analyze the diff.
-
-Output:
-- Write the report in the exact format used by `$final-release-review` (see `.agents/skills/final-release-review/SKILL.md`).
-- Use the compare URL: `https://github.com/${GITHUB_REPOSITORY}/compare/BASE_TAG...TARGET`.
-- Include clear ship/block call and risk levels.
-- If no risks are found, include "No material risks identified".
-
-Constraints:
-- Output only the report (no code fences, no extra commentary).

.github/codex/schemas/pr-labels.json

@@ -1,29 +0,0 @@
-{
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["labels"],
-  "properties": {
-    "labels": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [
-          "documentation",
-          "project",
-          "bug",
-          "enhancement",
-          "dependencies",
-          "feature:chat-completions",
-          "feature:core",
-          "feature:extensions",
-          "feature:mcp",
-          "feature:realtime",
-          "feature:sandboxes",
-          "feature:sessions",
-          "feature:tracing",
-          "feature:voice"
-        ]
-      }
-    }
-  }
-}

.github/scripts/pr_labels.py

@@ -1,442 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import pathlib
-import subprocess
-import sys
-from collections.abc import Sequence
-from dataclasses import dataclass
-from typing import Any, Final
-
-ALLOWED_LABELS: Final[set[str]] = {
-    "documentation",
-    "project",
-    "bug",
-    "enhancement",
-    "dependencies",
-    "feature:chat-completions",
-    "feature:core",
-    "feature:extensions",
-    "feature:mcp",
-    "feature:realtime",
-    "feature:sandboxes",
-    "feature:sessions",
-    "feature:tracing",
-    "feature:voice",
-}
-
-DETERMINISTIC_LABELS: Final[set[str]] = {
-    "documentation",
-    "project",
-    "dependencies",
-}
-
-MODEL_ONLY_LABELS: Final[set[str]] = {
-    "bug",
-    "enhancement",
-}
-
-FEATURE_LABELS: Final[set[str]] = ALLOWED_LABELS - DETERMINISTIC_LABELS - MODEL_ONLY_LABELS
-
-SOURCE_FEATURE_PREFIXES: Final[dict[str, tuple[str, ...]]] = {
-    "feature:realtime": ("src/agents/realtime/",),
-    "feature:sandboxes": ("src/agents/sandbox/", "src/agents/extensions/sandbox/"),
-    "feature:voice": ("src/agents/voice/",),
-    "feature:mcp": ("src/agents/mcp/",),
-    "feature:tracing": ("src/agents/tracing/",),
-    "feature:sessions": ("src/agents/memory/",),
-}
-
-CORE_EXCLUDED_PREFIXES: Final[tuple[str, ...]] = (
-    "src/agents/realtime/",
-    "src/agents/voice/",
-    "src/agents/mcp/",
-    "src/agents/tracing/",
-    "src/agents/memory/",
-    "src/agents/extensions/",
-    "src/agents/models/",
-)
-
-PR_CONTEXT_DEFAULT_PATH = ".tmp/pr-labels/pr-context.json"
-
-
-@dataclass(frozen=True)
-class PRContext:
-    title: str = ""
-    body: str = ""
-
-
-def read_file_at(commit: str | None, path: str) -> str | None:
-    if not commit:
-        return None
-    try:
-        return subprocess.check_output(["git", "show", f"{commit}:{path}"], text=True)
-    except subprocess.CalledProcessError:
-        return None
-
-
-def dependency_lines_for_pyproject(text: str) -> set[int]:
-    dependency_lines: set[int] = set()
-    current_section: str | None = None
-    in_project_dependencies = False
-
-    for line_number, raw_line in enumerate(text.splitlines(), start=1):
-        stripped = raw_line.strip()
-        if stripped.startswith("[") and stripped.endswith("]"):
-            if stripped.startswith("[[") and stripped.endswith("]]"):
-                current_section = stripped[2:-2].strip()
-            else:
-                current_section = stripped[1:-1].strip()
-            in_project_dependencies = False
-            if current_section in ("project.optional-dependencies", "dependency-groups"):
-                dependency_lines.add(line_number)
-            continue
-
-        if current_section in ("project.optional-dependencies", "dependency-groups"):
-            dependency_lines.add(line_number)
-            continue
-
-        if current_section != "project":
-            continue
-
-        if in_project_dependencies:
-            dependency_lines.add(line_number)
-            if "]" in stripped:
-                in_project_dependencies = False
-            continue
-
-        if stripped.startswith("dependencies") and "=" in stripped:
-            dependency_lines.add(line_number)
-            if "[" in stripped and "]" not in stripped:
-                in_project_dependencies = True
-
-    return dependency_lines
-
-
-def pyproject_dependency_changed(
-    diff_text: str,
-    *,
-    base_sha: str | None,
-    head_sha: str | None,
-) -> bool:
-    import re
-
-    base_text = read_file_at(base_sha, "pyproject.toml")
-    head_text = read_file_at(head_sha, "pyproject.toml")
-    if base_text is None and head_text is None:
-        return False
-
-    base_dependency_lines = dependency_lines_for_pyproject(base_text) if base_text else set()
-    head_dependency_lines = dependency_lines_for_pyproject(head_text) if head_text else set()
-
-    in_pyproject = False
-    base_line: int | None = None
-    head_line: int | None = None
-    hunk_re = re.compile(r"@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@")
-
-    for line in diff_text.splitlines():
-        if line.startswith("+++ b/"):
-            current_file = line[len("+++ b/") :].strip()
-            in_pyproject = current_file == "pyproject.toml"
-            base_line = None
-            head_line = None
-            continue
-
-        if not in_pyproject:
-            continue
-
-        if line.startswith("@@ "):
-            match = hunk_re.match(line)
-            if not match:
-                continue
-            base_line = int(match.group(1))
-            head_line = int(match.group(2))
-            continue
-
-        if base_line is None or head_line is None:
-            continue
-
-        if line.startswith(" "):
-            base_line += 1
-            head_line += 1
-            continue
-
-        if line.startswith("-"):
-            if base_line in base_dependency_lines:
-                return True
-            base_line += 1
-            continue
-
-        if line.startswith("+"):
-            if head_line in head_dependency_lines:
-                return True
-            head_line += 1
-            continue
-
-    return False
-
-
-def infer_specific_feature_labels(changed_files: Sequence[str]) -> set[str]:
-    source_files = [path for path in changed_files if path.startswith("src/")]
-    labels: set[str] = set()
-
-    for label, prefixes in SOURCE_FEATURE_PREFIXES.items():
-        if any(path.startswith(prefix) for path in source_files for prefix in prefixes):
-            labels.add(label)
-
-    if any(path.startswith("src/agents/extensions/") for path in source_files):
-        labels.add("feature:extensions")
-
-    if any(
-        path.startswith(("src/agents/models/", "src/agents/extensions/models/"))
-        and ("chatcmpl" in path or "chatcompletions" in path)
-        for path in source_files
-    ):
-        labels.add("feature:chat-completions")
-
-    return labels
-
-
-def infer_feature_labels(changed_files: Sequence[str]) -> set[str]:
-    source_files = [path for path in changed_files if path.startswith("src/")]
-    specific_labels = infer_specific_feature_labels(source_files)
-    core_touched = any(
-        path.startswith("src/agents/") and not path.startswith(CORE_EXCLUDED_PREFIXES)
-        for path in source_files
-    )
-
-    if core_touched and len(specific_labels) != 1:
-        return {"feature:core"}
-    return specific_labels
-
-
-def infer_fallback_labels(changed_files: Sequence[str]) -> set[str]:
-    return infer_feature_labels(changed_files)
-
-
-def load_json(path: pathlib.Path) -> Any:
-    return json.loads(path.read_text())
-
-
-def load_pr_context(path: pathlib.Path) -> PRContext:
-    if not path.exists():
-        return PRContext()
-
-    try:
-        payload = load_json(path)
-    except json.JSONDecodeError:
-        return PRContext()
-
-    if not isinstance(payload, dict):
-        return PRContext()
-
-    title = payload.get("title", "")
-    body = payload.get("body", "")
-    if not isinstance(title, str):
-        title = ""
-    if not isinstance(body, str):
-        body = ""
-
-    return PRContext(title=title, body=body)
-
-
-def load_codex_labels(path: pathlib.Path) -> tuple[list[str], bool]:
-    if not path.exists():
-        return [], False
-
-    raw = path.read_text().strip()
-    if not raw:
-        return [], False
-
-    try:
-        payload = load_json(path)
-    except json.JSONDecodeError:
-        return [], False
-
-    if not isinstance(payload, dict):
-        return [], False
-
-    labels = payload.get("labels")
-    if not isinstance(labels, list):
-        return [], False
-
-    if not all(isinstance(label, str) for label in labels):
-        return [], False
-
-    return list(labels), True
-
-
-def fetch_existing_labels(pr_number: str) -> set[str]:
-    result = subprocess.check_output(
-        ["gh", "pr", "view", pr_number, "--json", "labels", "--jq", ".labels[].name"],
-        text=True,
-    ).strip()
-    return {label for label in result.splitlines() if label}
-
-
-def infer_title_intent_labels(pr_context: PRContext) -> set[str]:
-    normalized_title = pr_context.title.strip().lower()
-
-    bug_prefixes = ("fix:", "fix(", "bug:", "bugfix:", "hotfix:", "regression:")
-    enhancement_prefixes = ("feat:", "feat(", "feature:", "enhancement:")
-
-    if normalized_title.startswith(bug_prefixes):
-        return {"bug"}
-    if normalized_title.startswith(enhancement_prefixes):
-        return {"enhancement"}
-    return set()
-
-
-def compute_desired_labels(
-    *,
-    pr_context: PRContext,
-    changed_files: Sequence[str],
-    diff_text: str,
-    codex_ran: bool,
-    codex_output_valid: bool,
-    codex_labels: Sequence[str],
-    base_sha: str | None,
-    head_sha: str | None,
-) -> set[str]:
-    desired: set[str] = set()
-    codex_label_set = {label for label in codex_labels if label in ALLOWED_LABELS}
-    codex_feature_labels = codex_label_set & FEATURE_LABELS
-    codex_model_only_labels = codex_label_set & MODEL_ONLY_LABELS
-    fallback_feature_labels = infer_fallback_labels(changed_files)
-    title_intent_labels = infer_title_intent_labels(pr_context)
-
-    if "pyproject.toml" in changed_files:
-        desired.add("project")
-
-    if any(path.startswith("docs/") for path in changed_files):
-        desired.add("documentation")
-
-    dependencies_allowed = "uv.lock" in changed_files
-    if "pyproject.toml" in changed_files and pyproject_dependency_changed(
-        diff_text, base_sha=base_sha, head_sha=head_sha
-    ):
-        dependencies_allowed = True
-    if dependencies_allowed:
-        desired.add("dependencies")
-
-    if codex_ran and codex_output_valid and codex_feature_labels:
-        desired.update(codex_feature_labels)
-    else:
-        desired.update(fallback_feature_labels)
-
-    if title_intent_labels:
-        desired.update(title_intent_labels)
-    elif codex_ran and codex_output_valid:
-        desired.update(codex_model_only_labels)
-
-    if any(path.startswith("src/agents/extensions/sandbox/") for path in changed_files):
-        desired.update({"feature:extensions", "feature:sandboxes"})
-
-    return desired
-
-
-def compute_managed_labels(
-    *,
-    pr_context: PRContext,
-    codex_ran: bool,
-    codex_output_valid: bool,
-    codex_labels: Sequence[str],
-) -> set[str]:
-    managed = DETERMINISTIC_LABELS | FEATURE_LABELS
-    title_intent_labels = infer_title_intent_labels(pr_context)
-    codex_label_set = {label for label in codex_labels if label in MODEL_ONLY_LABELS}
-    if title_intent_labels or (codex_ran and codex_output_valid and codex_label_set):
-        managed |= MODEL_ONLY_LABELS
-    return managed
-
-
-def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--pr-number", default=os.environ.get("PR_NUMBER", ""))
-    parser.add_argument("--base-sha", default=os.environ.get("PR_BASE_SHA", ""))
-    parser.add_argument("--head-sha", default=os.environ.get("PR_HEAD_SHA", ""))
-    parser.add_argument(
-        "--codex-output-path",
-        default=os.environ.get("CODEX_OUTPUT_PATH", ".tmp/codex/outputs/pr-labels.json"),
-    )
-    parser.add_argument("--codex-conclusion", default=os.environ.get("CODEX_CONCLUSION", ""))
-    parser.add_argument(
-        "--pr-context-path",
-        default=os.environ.get("PR_CONTEXT_PATH", PR_CONTEXT_DEFAULT_PATH),
-    )
-    parser.add_argument(
-        "--changed-files-path",
-        default=os.environ.get("CHANGED_FILES_PATH", ".tmp/pr-labels/changed-files.txt"),
-    )
-    parser.add_argument(
-        "--changes-diff-path",
-        default=os.environ.get("CHANGES_DIFF_PATH", ".tmp/pr-labels/changes.diff"),
-    )
-    return parser.parse_args(argv)
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    args = parse_args(argv)
-    if not args.pr_number:
-        raise SystemExit("Missing PR number.")
-
-    changed_files_path = pathlib.Path(args.changed_files_path)
-    changes_diff_path = pathlib.Path(args.changes_diff_path)
-    codex_output_path = pathlib.Path(args.codex_output_path)
-    pr_context_path = pathlib.Path(args.pr_context_path)
-    codex_conclusion = args.codex_conclusion.strip().lower()
-    codex_ran = bool(codex_conclusion) and codex_conclusion != "skipped"
-    pr_context = load_pr_context(pr_context_path)
-
-    changed_files = []
-    if changed_files_path.exists():
-        changed_files = [
-            line.strip() for line in changed_files_path.read_text().splitlines() if line.strip()
-        ]
-
-    diff_text = changes_diff_path.read_text() if changes_diff_path.exists() else ""
-    codex_labels, codex_output_valid = load_codex_labels(codex_output_path)
-    if codex_ran and not codex_output_valid:
-        print(
-            "Codex output missing or invalid; using fallback feature labels and preserving "
-            "model-only labels."
-        )
-    desired = compute_desired_labels(
-        pr_context=pr_context,
-        changed_files=changed_files,
-        diff_text=diff_text,
-        codex_ran=codex_ran,
-        codex_output_valid=codex_output_valid,
-        codex_labels=codex_labels,
-        base_sha=args.base_sha or None,
-        head_sha=args.head_sha or None,
-    )
-
-    existing = fetch_existing_labels(args.pr_number)
-    managed_labels = compute_managed_labels(
-        pr_context=pr_context,
-        codex_ran=codex_ran,
-        codex_output_valid=codex_output_valid,
-        codex_labels=codex_labels,
-    )
-    to_add = sorted(desired - existing)
-    to_remove = sorted((existing & managed_labels) - desired)
-
-    if not to_add and not to_remove:
-        print("Labels already up to date.")
-        return 0
-
-    cmd = ["gh", "pr", "edit", args.pr_number]
-    if to_add:
-        cmd += ["--add-label", ",".join(to_add)]
-    if to_remove:
-        cmd += ["--remove-label", ",".join(to_remove)]
-    subprocess.check_call(cmd)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/workflows/docs.yml

@@ -36,9 +36,9 @@ jobs:
           fi
       - name: Setup uv
         if: steps.docs-only.outputs.skip != 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Install dependencies
         if: steps.docs-only.outputs.skip != 'true'

.github/workflows/pr-labels.yml

@@ -1,204 +0,0 @@
-name: Auto label PRs
-
-on:
-  pull_request_target:
-    types:
-      - opened
-      - reopened
-      - synchronize
-      - ready_for_review
-  workflow_dispatch:
-    inputs:
-      pr_number:
-        description: "PR number to label."
-        required: true
-        type: number
-
-permissions:
-  contents: read
-  issues: write
-  pull-requests: write
-
-jobs:
-  label:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Ensure main workflow
-        if: ${{ github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main' }}
-        run: |
-          echo "This workflow must be dispatched from main."
-          exit 1
-
-      - name: Resolve PR context
-        id: pr
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
-        env:
-          MANUAL_PR_NUMBER: ${{ inputs.pr_number || '' }}
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const isManual = context.eventName === 'workflow_dispatch';
-            let pr;
-            if (isManual) {
-              const prNumber = Number(process.env.MANUAL_PR_NUMBER);
-              if (!prNumber) {
-                core.setFailed('workflow_dispatch requires pr_number input.');
-                return;
-              }
-              const { data } = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: prNumber,
-              });
-              pr = data;
-            } else {
-              pr = context.payload.pull_request;
-            }
-            if (!pr) {
-              core.setFailed('Missing pull request context.');
-              return;
-            }
-            const headRepo = pr.head.repo.full_name;
-            const repoFullName = `${context.repo.owner}/${context.repo.repo}`;
-            core.setOutput('pr_number', pr.number);
-            core.setOutput('base_sha', pr.base.sha);
-            core.setOutput('head_sha', pr.head.sha);
-            core.setOutput('head_repo', headRepo);
-            core.setOutput('is_fork', headRepo !== repoFullName);
-            core.setOutput('title', pr.title || '');
-            core.setOutput('body', pr.body || '');
-
-      - name: Checkout base
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-        with:
-          fetch-depth: 0
-          ref: ${{ steps.pr.outputs.base_sha }}
-      - name: Fetch PR head
-        env:
-          PR_HEAD_REPO: ${{ steps.pr.outputs.head_repo }}
-          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-        run: |
-          set -euo pipefail
-          git fetch --no-tags --prune --recurse-submodules=no \
-            "https://github.com/${PR_HEAD_REPO}.git" \
-            "${PR_HEAD_SHA}"
-      - name: Collect PR diff
-        id: diff
-        env:
-          PR_BASE_SHA: ${{ steps.pr.outputs.base_sha }}
-          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          PR_TITLE: ${{ steps.pr.outputs.title }}
-          PR_BODY: ${{ steps.pr.outputs.body }}
-        run: |
-          set -euo pipefail
-          mkdir -p .tmp/pr-labels
-          diff_base_sha="$(git merge-base "$PR_BASE_SHA" "$PR_HEAD_SHA")"
-          echo "diff_base_sha=${diff_base_sha}" >> "$GITHUB_OUTPUT"
-          git diff --name-only "$diff_base_sha" "$PR_HEAD_SHA" > .tmp/pr-labels/changed-files.txt
-          git diff "$diff_base_sha" "$PR_HEAD_SHA" > .tmp/pr-labels/changes.diff
-          python - <<'PY'
-          import json
-          import os
-          import pathlib
-
-          pathlib.Path(".tmp/pr-labels/pr-context.json").write_text(
-              json.dumps(
-                  {
-                      "title": os.environ.get("PR_TITLE", ""),
-                      "body": os.environ.get("PR_BODY", ""),
-                  },
-                  ensure_ascii=False,
-                  indent=2,
-              )
-              + "\n"
-          )
-          PY
-      - name: Prepare Codex output
-        id: codex-output
-        run: |
-          set -euo pipefail
-          output_dir=".tmp/codex/outputs"
-          output_file="${output_dir}/pr-labels.json"
-          mkdir -p "$output_dir"
-          echo "output_file=${output_file}" >> "$GITHUB_OUTPUT"
-      - name: Run Codex labeling
-        id: run_codex
-        if: ${{ (github.event_name == 'workflow_dispatch' || steps.pr.outputs.is_fork != 'true') && github.actor != 'dependabot[bot]' }}
-        uses: openai/codex-action@e0fdf01220eb9a88167c4898839d273e3f2609d1
-        with:
-          openai-api-key: ${{ secrets.PROD_OPENAI_API_KEY }}
-          prompt-file: .github/codex/prompts/pr-labels.md
-          output-file: ${{ steps.codex-output.outputs.output_file }}
-          output-schema-file: .github/codex/schemas/pr-labels.json
-          # Keep the legacy Linux sandbox path until the default bubblewrap path
-          # works reliably on GitHub-hosted Ubuntu runners.
-          codex-args: '["--enable","use_legacy_landlock"]'
-          safety-strategy: drop-sudo
-          sandbox: read-only
-      - name: Apply labels
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
-          PR_BASE_SHA: ${{ steps.diff.outputs.diff_base_sha }}
-          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          CODEX_OUTPUT_PATH: ${{ steps.codex-output.outputs.output_file }}
-          CODEX_CONCLUSION: ${{ steps.run_codex.conclusion }}
-        run: |
-          python .github/scripts/pr_labels.py
-
-      - name: Comment on manual run failure
-        if: ${{ github.event_name == 'workflow_dispatch' && always() }}
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3
-        env:
-          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
-          JOB_STATUS: ${{ job.status }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          CODEX_CONCLUSION: ${{ steps.run_codex.conclusion }}
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          script: |
-            const marker = '<!-- pr-labels-manual-run -->';
-            const jobStatus = process.env.JOB_STATUS;
-            if (jobStatus === 'success') {
-              return;
-            }
-            const prNumber = Number(process.env.PR_NUMBER);
-            if (!prNumber) {
-              core.setFailed('Missing PR number for manual run comment.');
-              return;
-            }
-            const body = [
-              marker,
-              'Manual PR labeling failed.',
-              `Job status: ${jobStatus}.`,
-              `Run: ${process.env.RUN_URL}.`,
-              `Codex labeling: ${process.env.CODEX_CONCLUSION}.`,
-            ].join('\n');
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber,
-              per_page: 100,
-            });
-            const existing = comments.find(
-              (comment) =>
-                comment.user?.login === 'github-actions[bot]' &&
-                comment.body?.includes(marker),
-            );
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              });
-              core.info(`Updated existing comment ${existing.id}`);
-              return;
-            }
-            const { data: created } = await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber,
-              body,
-            });
-            core.info(`Created comment ${created.id}`);

.github/workflows/publish.yml

@@ -23,9 +23,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
       - name: Setup uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Install dependencies
         run: make sync

.github/workflows/release-pr-update.yml

@@ -1,109 +0,0 @@
-name: Update release PR on main updates
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency:
-  group: release-pr-update
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  update-release-pr:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-        with:
-          fetch-depth: 0
-      - name: Fetch tags
-        run: git fetch origin --tags --prune
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-      - name: Find release PR
-        id: find
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          base_branch="main"
-          prs_json="$(gh pr list \
-            --base "$base_branch" \
-            --state open \
-            --search "head:release/v" \
-            --limit 200 \
-            --json number,headRefName,isCrossRepository,headRepositoryOwner)"
-          count="$(echo "$prs_json" | jq '[.[] | select(.isCrossRepository == false) | select(.headRefName|startswith("release/v"))] | length')"
-          if [ "$count" -eq 0 ]; then
-            echo "found=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          if [ "$count" -gt 1 ]; then
-            echo "Multiple release PRs found; expected a single release PR." >&2
-            exit 1
-          fi
-          number="$(echo "$prs_json" | jq -r '.[] | select(.isCrossRepository == false) | select(.headRefName|startswith("release/v")) | .number')"
-          branch="$(echo "$prs_json" | jq -r '.[] | select(.isCrossRepository == false) | select(.headRefName|startswith("release/v")) | .headRefName')"
-          echo "found=true" >> "$GITHUB_OUTPUT"
-          echo "number=$number" >> "$GITHUB_OUTPUT"
-          echo "branch=$branch" >> "$GITHUB_OUTPUT"
-      - name: Rebase release branch
-        if: steps.find.outputs.found == 'true'
-        env:
-          RELEASE_BRANCH: ${{ steps.find.outputs.branch }}
-        run: |
-          set -euo pipefail
-          git fetch origin main "$RELEASE_BRANCH"
-          git checkout -B "$RELEASE_BRANCH" "origin/$RELEASE_BRANCH"
-          git rebase origin/main
-      - name: Prepare Codex output
-        if: steps.find.outputs.found == 'true'
-        id: codex-output
-        run: |
-          set -euo pipefail
-          output_dir=".tmp/codex/outputs"
-          output_file="${output_dir}/release-review.md"
-          mkdir -p "$output_dir"
-          echo "output_file=${output_file}" >> "$GITHUB_OUTPUT"
-      - name: Run Codex release review
-        if: steps.find.outputs.found == 'true'
-        uses: openai/codex-action@e0fdf01220eb9a88167c4898839d273e3f2609d1
-        with:
-          openai-api-key: ${{ secrets.PROD_OPENAI_API_KEY }}
-          prompt-file: .github/codex/prompts/release-review.md
-          output-file: ${{ steps.codex-output.outputs.output_file }}
-          # Keep the legacy Linux sandbox path until the default bubblewrap path
-          # works reliably on GitHub-hosted Ubuntu runners.
-          codex-args: '["--enable","use_legacy_landlock"]'
-          safety-strategy: drop-sudo
-          sandbox: read-only
-      - name: Update PR body and push
-        if: steps.find.outputs.found == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ steps.find.outputs.number }}
-          RELEASE_BRANCH: ${{ steps.find.outputs.branch }}
-          RELEASE_REVIEW_PATH: ${{ steps.codex-output.outputs.output_file }}
-        run: |
-          set -euo pipefail
-          git push --force-with-lease origin "$RELEASE_BRANCH"
-          gh pr edit "$PR_NUMBER" --body-file "$RELEASE_REVIEW_PATH"
-          version="${RELEASE_BRANCH#release/v}"
-          milestone_name="$(python .github/scripts/select-release-milestone.py --version "$version")"
-          if [ -n "$milestone_name" ]; then
-            if ! gh pr edit "$PR_NUMBER" --add-label "project" --milestone "$milestone_name"; then
-              echo "PR label/milestone update failed; continuing without changes." >&2
-            fi
-          else
-            if ! gh pr edit "$PR_NUMBER" --add-label "project"; then
-              echo "PR label update failed; continuing without changes." >&2
-            fi
-          fi

.github/workflows/release-pr.yml

@@ -21,9 +21,9 @@ jobs:
           fetch-depth: 0
           ref: main
       - name: Setup uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Fetch tags
         run: git fetch origin --tags --prune
@@ -93,36 +93,11 @@ jobs:
           fi
           git commit -m "Bump version to ${RELEASE_VERSION}"
           git push --set-upstream origin "$branch"
-      - name: Prepare Codex output
-        id: codex-output
-        run: |
-          set -euo pipefail
-          output_dir=".tmp/codex/outputs"
-          output_file="${output_dir}/release-review.md"
-          mkdir -p "$output_dir"
-          echo "output_file=${output_file}" >> "$GITHUB_OUTPUT"
-      - name: Run Codex release review
-        uses: openai/codex-action@e0fdf01220eb9a88167c4898839d273e3f2609d1
-        with:
-          openai-api-key: ${{ secrets.PROD_OPENAI_API_KEY }}
-          prompt-file: .github/codex/prompts/release-review.md
-          output-file: ${{ steps.codex-output.outputs.output_file }}
-          # Keep the legacy Linux sandbox path until the default bubblewrap path
-          # works reliably on GitHub-hosted Ubuntu runners.
-          codex-args: '["--enable","use_legacy_landlock"]'
-          safety-strategy: drop-sudo
-          sandbox: read-only
       - name: Build PR body
         env:
-          RELEASE_REVIEW_PATH: ${{ steps.codex-output.outputs.output_file }}
+          RELEASE_VERSION: ${{ inputs.version }}
         run: |
-          python - <<'PY'
-          import os
-          import pathlib
-
-          report = pathlib.Path(os.environ["RELEASE_REVIEW_PATH"]).read_text()
-          pathlib.Path("pr-body.md").write_text(report)
-          PY
+          printf 'Release PR for %s.\n\nThe release readiness report will be prepared manually.\n' "$RELEASE_VERSION" > pr-body.md
       - name: Create or update PR
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-tag.yml

@@ -14,6 +14,7 @@ jobs:
   tag-release:
     if: >-
       github.event.pull_request.merged == true &&
+      github.event.pull_request.head.repo.full_name == github.repository &&
       startsWith(github.event.pull_request.head.ref, 'release/v')
     runs-on: ubuntu-latest
     steps:

.github/workflows/tests.yml

@@ -24,9 +24,9 @@ jobs:
         run: ./.github/scripts/detect-changes.sh code "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
       - name: Setup uv
         if: steps.changes.outputs.run == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Install dependencies
         if: steps.changes.outputs.run == 'true'
@@ -51,9 +51,9 @@ jobs:
         run: ./.github/scripts/detect-changes.sh code "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
       - name: Setup uv
         if: steps.changes.outputs.run == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Install dependencies
         if: steps.changes.outputs.run == 'true'
@@ -86,9 +86,9 @@ jobs:
         run: ./.github/scripts/detect-changes.sh code "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
       - name: Setup uv
         if: steps.changes.outputs.run == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -120,9 +120,9 @@ jobs:
         run: ./.github/scripts/detect-changes.sh code "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
       - name: Setup uv
         if: steps.changes.outputs.run == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
           python-version: "3.13"
       - name: Install dependencies
@@ -147,9 +147,9 @@ jobs:
         run: ./.github/scripts/detect-changes.sh docs "${{ github.event.pull_request.base.sha || github.event.before }}" "${{ github.sha }}"
       - name: Setup uv
         if: steps.changes.outputs.run == 'true'
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.14
         with:
-          version: "0.11.7"
+          version: "0.11.14"
           enable-cache: true
       - name: Install dependencies
         if: steps.changes.outputs.run == 'true'

.github/workflows/update-docs.yml

@@ -1,95 +0,0 @@
-name: "Update Translated Docs"
-
-# This GitHub Actions job automates the process of updating all translated document pages. Please note the following:
-# 1. The translation results may vary each time; some differences in detail are expected.
-# 2. When you add a new page to the left-hand menu, **make sure to manually update mkdocs.yml** to include the new item.
-# 3. If you switch to a different LLM (for example, from o3 to a newer model), be sure to conduct thorough testing before making the switch.
-
-# To add more languages, you will update the following:
-# 1.  Add '!docs/{lang}/**' to `on.push.paths` in this file
-# 2. Update mkdocs.yml to have the new language
-# 3. Update docs/scripts/translate_docs.py to have the new language
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'docs/**'
-      - mkdocs.yml
-      - '!docs/ja/**'
-      - '!docs/ko/**'
-      - '!docs/zh/**'
-  workflow_dispatch:
-    inputs:
-      translate_mode:
-        description: "Translation mode"
-        type: choice
-        options:
-          - only-changes
-          - full
-        default: only-changes
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  update-docs:
-    if: "!contains(github.event.head_commit.message, 'Update all translated document pages')"
-    name: Build and Push Translated Docs
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    env:
-      PROD_OPENAI_API_KEY: ${{ secrets.PROD_OPENAI_API_KEY }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-        with:
-          fetch-depth: 0
-      - name: Setup uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # setup-uv v8.1.0; uv 0.11.7
-        with:
-          version: "0.11.7"
-          enable-cache: true
-      - name: Install dependencies
-        run: make sync
-      - name: Build translated docs
-        run: |
-          mode="${{ inputs.translate_mode || 'only-changes' }}"
-          uv run docs/scripts/translate_docs.py --mode "$mode"
-          uv run mkdocs build
-
-      - name: Commit changes
-        id: commit
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add docs/
-          if git diff --cached --quiet; then
-            echo "No changes to commit"
-            echo "committed=false" >> "$GITHUB_OUTPUT"
-          else
-            git commit -m "Update all translated document pages"
-            echo "committed=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Rebase translated docs on latest main
-        if: steps.commit.outputs.committed == 'true'
-        run: |
-          git fetch origin main
-          git rebase origin/main
-
-      - name: Create Pull Request
-        if: steps.commit.outputs.committed == 'true'
-        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1
-        with:
-          commit-message: "Update translated document pages"
-          title: "docs: update translated document pages"
-          body: |
-            Automated update of translated documentation.
-
-            Triggered by commit: [${{ github.event.head_commit.id }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.event.head_commit.id }}).
-            Message: `${{ github.event.head_commit.message }}`
-          branch: update-translated-docs-${{ github.run_id }}
-          delete-branch: true

.gitignore

@@ -143,6 +143,10 @@ cython_debug/
 # Ruff stuff:
 .ruff_cache/
 
+# Example runtime state
+examples/sandbox/extensions/daytona/usaspending_text2sql/.audit_log.jsonl
+examples/sandbox/extensions/daytona/usaspending_text2sql/.session_state.json
+
 # PyPI configuration file
 .pypirc
 .aider*
@@ -154,3 +158,4 @@ tmp/
 
 # execplans
 plans/
+.vercel

AGENTS.md

@@ -55,6 +55,15 @@ Treat the parameter and dataclass field order of exported runtime APIs as a comp
 - If reordering is unavoidable, add an explicit compatibility layer and regression tests that exercise the old positional call pattern.
 - Prefer keyword arguments at call sites to reduce accidental breakage, but do not rely on this to justify breaking positional compatibility for public APIs.
 
+### Platform, Docs, and Security Review
+
+- Documentation is published to the live site, so coordinate SDK behavior changes and docs carefully. If docs describe behavior that is not released yet, either delay the docs change until the SDK release is available or split it into a follow-up PR.
+- Treat runnable docs snippets as API compatibility checks. Before adding OpenAI API, provider, Responses, Realtime, WebSocket, or SDK constructor examples, verify the shown arguments and call shape against the actual implementation.
+- Do not let untrusted sandbox manifests opt themselves out of host filesystem or base-directory boundaries. Escape hatches for local source materialization must be controlled by trusted application code at the call site, not by serialized manifest data.
+- When documenting sandbox or security grants, verify the actual implementation path enforces the grant or boundary. Do not claim a grant applies to `LocalDir`, `LocalFile`, archive extraction, or other materialization paths unless those paths actually consult it.
+- When redacting OpenAI tool, MCP, model, or provider payloads, consider traceback display, exception chaining, `__context__`, logs, and telemetry. Suppressing display with `raise ... from None` is not enough if the original exception object still carries sensitive input data.
+- For OpenAI platform or SDK-specific docs changes, prefer `$openai-knowledge` for authoritative platform behavior and inspect the local code path for SDK behavior. Do not rely on generic API assumptions when documenting Responses, Chat Completions, Realtime, tools, MCP, or provider adapters.
+
 ## Project Structure Guide
 
 ### Overview

README.md

@@ -17,7 +17,7 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 1. [**Human in the loop**](https://openai.github.io/openai-agents-python/human_in_the_loop/): Built-in mechanisms for involving humans across agent runs
 1. [**Sessions**](https://openai.github.io/openai-agents-python/sessions/): Automatic conversation history management across agent runs
 1. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
-1. [**Realtime Agents**](https://openai.github.io/openai-agents-python/realtime/quickstart/): Build powerful voice agents with `gpt-realtime-1.5` and full agent features
+1. [**Realtime Agents**](https://openai.github.io/openai-agents-python/realtime/quickstart/): Build powerful voice agents with `gpt-realtime-2` and full agent features
 
 Explore the [examples](https://github.com/openai/openai-agents-python/tree/main/examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.
 

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+For a more in-depth look at our security policy, please check out our [Coordinated Vulnerability Disclosure Policy](https://openai.com/security/disclosure/#:~:text=Disclosure%20Policy,-Security%20is%20essential&text=OpenAI%27s%20coordinated%20vulnerability%20disclosure%20policy,expect%20from%20us%20in%20return.).
+
+Our PGP key can located [at this address.](https://cdn.openai.com/security.txt)

docs/agents.md

@@ -28,7 +28,7 @@ The most common properties of an agent are:
 | Property | Required | Description |
 | --- | --- | --- |
 | `name` | yes | Human-readable agent name. |
-| `instructions` | yes | System prompt or dynamic instructions callback. See [Dynamic instructions](#dynamic-instructions). |
+| `instructions` | no | System prompt or dynamic instructions callback. Strongly recommended. See [Dynamic instructions](#dynamic-instructions). |
 | `prompt` | no | OpenAI Responses API prompt configuration. Accepts a static prompt object or a function. See [Prompt templates](#prompt-templates). |
 | `handoff_description` | no | Short description exposed when this agent is offered as a handoff target. |
 | `handoffs` | no | Delegate the conversation to specialist agents. See [handoffs](handoffs.md). |

docs/index.md

@@ -27,7 +27,7 @@ Here are the main features of the SDK:
 -   **Sessions**: A persistent memory layer for maintaining working context within an agent loop.
 -   **Human in the loop**: Built-in mechanisms for involving humans across agent runs.
 -   **Tracing**: Built-in tracing for visualizing, debugging, and monitoring workflows, with support for the OpenAI suite of evaluation, fine-tuning, and distillation tools.
--   **Realtime Agents**: Build powerful voice agents with `gpt-realtime-1.5`, automatic interruption detection, context management, guardrails, and more.
+-   **Realtime Agents**: Build powerful voice agents with `gpt-realtime-2`, automatic interruption detection, context management, guardrails, and more.
 
 ## Agents SDK or Responses API?
 
@@ -93,5 +93,5 @@ Use this table when you know the job you want to do, but not which page explains
 | Keep memory across turns | [Running agents](running_agents.md#choose-a-memory-strategy) and [Sessions](sessions/index.md) |
 | Use OpenAI models, websocket transport, or non-OpenAI providers | [Models](models/index.md) |
 | Review outputs, run items, interruptions, and resume state | [Results](results.md) |
-| Build a low-latency voice agent with `gpt-realtime-1.5` | [Realtime agents quickstart](realtime/quickstart.md) and [Realtime transport](realtime/transport.md) |
+| Build a low-latency voice agent with `gpt-realtime-2` | [Realtime agents quickstart](realtime/quickstart.md) and [Realtime transport](realtime/transport.md) |
 | Build a speech-to-text / agent / text-to-speech pipeline | [Voice pipeline quickstart](voice/quickstart.md) |

docs/ja/agents.md

@@ -4,49 +4,49 @@ search:
 ---
 # エージェント
 
-エージェントは、アプリにおける中核的な構成要素です。エージェントは、 instructions、tools、およびハンドオフ、ガードレール、structured outputs などの任意のランタイム動作で設定された大規模言語モデル (LLM) です。
+エージェントは、アプリにおける中核的な構成要素です。エージェントとは、instructions、ツール、およびハンドオフ、ガードレール、structured outputs などの任意のランタイム動作で設定された大規模言語モデル (LLM) です。
 
-単一のプレーンな `Agent` を定義またはカスタマイズしたい場合は、このページを使用してください。複数のエージェントをどのように協調させるかを決める場合は、[エージェントオーケストレーション](multi_agent.md)をお読みください。エージェントを、マニフェストで定義されたファイルとサンドボックスネイティブな機能を持つ分離ワークスペース内で実行する必要がある場合は、[サンドボックスエージェントの概念](sandbox/guide.md)をお読みください。
+単一のシンプルな `Agent` を定義またはカスタマイズしたい場合は、このページを使用してください。複数のエージェントをどのように連携させるかを検討している場合は、[エージェントオーケストレーション](multi_agent.md) を読んでください。エージェントを、マニフェストで定義されたファイルとサンドボックスネイティブ機能を備えた分離ワークスペース内で実行する必要がある場合は、[Sandbox エージェントの概念](sandbox/guide.md) を読んでください。
 
-SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、ここでの違いはオーケストレーションです。`Agent` と `Runner` により、SDK がターン、ツール、ガードレール、ハンドオフ、セッションを管理できます。このループを自分で制御したい場合は、代わりに Responses API を直接使用してください。
+SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、ここでの違いはオーケストレーションです。`Agent` と `Runner` により、SDK がターン、ツール、ガードレール、ハンドオフ、セッションを管理できます。そのループを自分で管理したい場合は、代わりに Responses API を直接使用してください。
 
 ## 次のガイドの選択
 
-このページは、エージェント定義のハブとして使用してください。次に行う必要がある判断に合った隣接ガイドへ移動してください。
+このページをエージェント定義のハブとして使用してください。次に行う判断に合ったガイドへ進んでください。
 
 | したいこと | 次に読むもの |
 | --- | --- |
 | モデルまたはプロバイダー設定を選択する | [モデル](models/index.md) |
 | エージェントに機能を追加する | [ツール](tools.md) |
-| 実際のリポジトリ、ドキュメントバンドル、または分離ワークスペースに対してエージェントを実行する | [サンドボックスエージェントのクイックスタート](sandbox_agents.md) |
-| マネージャー形式のオーケストレーションとハンドオフのどちらにするかを決める | [エージェントオーケストレーション](multi_agent.md) |
+| 実際のリポジトリ、ドキュメントバンドル、または分離ワークスペースに対してエージェントを実行する | [Sandbox エージェントのクイックスタート](sandbox_agents.md) |
+| マネージャースタイルのオーケストレーションとハンドオフのどちらにするかを決める | [エージェントオーケストレーション](multi_agent.md) |
 | ハンドオフ動作を設定する | [ハンドオフ](handoffs.md) |
-| ターンの実行、イベントのストリーミング、または会話状態の管理を行う | [エージェントの実行](running_agents.md) |
+| ターンを実行し、イベントをストリーミングし、会話状態を管理する | [エージェント実行](running_agents.md) |
 | 最終出力、実行アイテム、または再開可能な状態を確認する | [結果](results.md) |
 | ローカル依存関係とランタイム状態を共有する | [コンテキスト管理](context.md) |
 
 ## 基本設定
 
-エージェントの最も一般的なプロパティは次のとおりです。
+エージェントで最も一般的なプロパティは次のとおりです。
 
 | プロパティ | 必須 | 説明 |
 | --- | --- | --- |
-| `name` | はい | 人間が読めるエージェント名。 |
-| `instructions` | はい | システムプロンプトまたは動的 instructions コールバック。[動的 instructions](#dynamic-instructions)を参照してください。 |
-| `prompt` | いいえ | OpenAI Responses API のプロンプト設定。静的プロンプトオブジェクトまたは関数を受け付けます。[プロンプトテンプレート](#prompt-templates)を参照してください。 |
+| `name` | はい | 人間が読みやすいエージェント名。 |
+| `instructions` | いいえ | システムプロンプトまたは動的 instructions コールバック。強く推奨します。[動的 instructions](#dynamic-instructions) を参照してください。 |
+| `prompt` | いいえ | OpenAI Responses API のプロンプト設定。静的なプロンプトオブジェクトまたは関数を受け付けます。[プロンプトテンプレート](#prompt-templates) を参照してください。 |
 | `handoff_description` | いいえ | このエージェントがハンドオフ先として提示されるときに公開される短い説明。 |
-| `handoffs` | いいえ | 会話を専門エージェントに委任します。[ハンドオフ](handoffs.md)を参照してください。 |
-| `model` | いいえ | 使用する LLM。[モデル](models/index.md)を参照してください。 |
+| `handoffs` | いいえ | 会話を専門エージェントに委任します。[ハンドオフ](handoffs.md) を参照してください。 |
+| `model` | いいえ | 使用する LLM。[モデル](models/index.md) を参照してください。 |
 | `model_settings` | いいえ | `temperature`、`top_p`、`tool_choice` などのモデル調整パラメーター。 |
-| `tools` | いいえ | エージェントが呼び出せるツール。[ツール](tools.md)を参照してください。 |
-| `mcp_servers` | いいえ | エージェント用の MCP バックのツール。[MCP ガイド](mcp.md)を参照してください。 |
-| `mcp_config` | いいえ | 厳密なスキーマ変換や MCP 失敗時の整形など、MCP ツールの準備方法を微調整します。[MCP ガイド](mcp.md#agent-level-mcp-configuration)を参照してください。 |
-| `input_guardrails` | いいえ | このエージェントチェーンの最初のユーザー入力で実行されるガードレール。[ガードレール](guardrails.md)を参照してください。 |
-| `output_guardrails` | いいえ | このエージェントの最終出力で実行されるガードレール。[ガードレール](guardrails.md)を参照してください。 |
-| `output_type` | いいえ | プレーンテキストの代わりとなる structured outputs 型。[出力型](#output-types)を参照してください。 |
-| `hooks` | いいえ | エージェントスコープのライフサイクルコールバック。[ライフサイクルイベント (hooks)](#lifecycle-events-hooks)を参照してください。 |
-| `tool_use_behavior` | いいえ | ツール結果をモデルに戻してループさせるか、実行を終了するかを制御します。[ツール使用動作](#tool-use-behavior)を参照してください。 |
-| `reset_tool_choice` | いいえ | ツール使用ループを避けるため、ツール呼び出し後に `tool_choice` をリセットします (デフォルト: `True`)。[ツール使用の強制](#forcing-tool-use)を参照してください。 |
+| `tools` | いいえ | エージェントが呼び出せるツール。[ツール](tools.md) を参照してください。 |
+| `mcp_servers` | いいえ | エージェント向けの MCP ベースのツール。[MCP ガイド](mcp.md) を参照してください。 |
+| `mcp_config` | いいえ | 厳格なスキーマ変換や MCP 失敗時の形式設定など、MCP ツールの準備方法を微調整します。[MCP ガイド](mcp.md#agent-level-mcp-configuration) を参照してください。 |
+| `input_guardrails` | いいえ | このエージェントチェーンの最初のユーザー入力に対して実行されるガードレール。[ガードレール](guardrails.md) を参照してください。 |
+| `output_guardrails` | いいえ | このエージェントの最終出力に対して実行されるガードレール。[ガードレール](guardrails.md) を参照してください。 |
+| `output_type` | いいえ | プレーンテキストの代わりとなる構造化出力型。[出力型](#output-types) を参照してください。 |
+| `hooks` | いいえ | エージェントスコープのライフサイクルコールバック。[ライフサイクルイベント (フック)](#lifecycle-events-hooks) を参照してください。 |
+| `tool_use_behavior` | いいえ | ツールの結果をモデルに戻してループさせるか、実行を終了するかを制御します。[ツール使用の動作](#tool-use-behavior) を参照してください。 |
+| `reset_tool_choice` | いいえ | ツール呼び出し後に `tool_choice` をリセットします (デフォルト: `True`)。これによりツール使用ループを避けます。[ツール使用の強制](#forcing-tool-use) を参照してください。 |
 
 ```python
 from agents import Agent, ModelSettings, function_tool
@@ -64,13 +64,13 @@ agent = Agent(
 )
 ```
 
-このセクションのすべては `Agent` に適用されます。`SandboxAgent` は同じ考え方を基にしており、ワークスペーススコープの実行のために `default_manifest`、`base_instructions`、`capabilities`、`run_as` を追加します。[サンドボックスエージェントの概念](sandbox/guide.md)を参照してください。
+このセクションの内容はすべて `Agent` に適用されます。`SandboxAgent` は同じ考え方を基盤とし、それに `default_manifest`、`base_instructions`、`capabilities`、`run_as` を加えて、ワークスペーススコープの実行に対応します。[Sandbox エージェントの概念](sandbox/guide.md) を参照してください。
 
 ## プロンプトテンプレート
 
-`prompt` を設定することで、OpenAI プラットフォームで作成したプロンプトテンプレートを参照できます。これは Responses API を使用する OpenAI モデルで機能します。
+`prompt` を設定することで、OpenAI プラットフォームで作成したプロンプトテンプレートを参照できます。これは Responses API を使用する OpenAI モデルで動作します。
 
-使用するには、次を行ってください。
+使用するには、次の手順を行ってください。
 
 1. https://platform.openai.com/playground/prompts に移動します
 2. 新しいプロンプト変数 `poem_style` を作成します。
@@ -80,7 +80,7 @@ agent = Agent(
     Write a poem in {{poem_style}}
     ```
 
-4. `--prompt-id` フラグを指定して例を実行します。
+4. この例を `--prompt-id` フラグ付きで実行します。
 
 ```python
 from agents import Agent
@@ -127,9 +127,9 @@ result = await Runner.run(
 
 ## コンテキスト
 
-エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入ツールです。これは、作成して `Runner.run()` に渡すオブジェクトであり、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行のための依存関係と状態をまとめて保持するものとして機能します。任意の Python オブジェクトをコンテキストとして提供できます。
+エージェントは `context` 型に対してジェネリックです。コンテキストは依存性注入のためのツールです。自分で作成して `Runner.run()` に渡すオブジェクトであり、すべてのエージェント、ツール、ハンドオフなどに渡され、エージェント実行の依存関係や状態をまとめて保持します。コンテキストには任意の Python オブジェクトを指定できます。
 
-完全な `RunContextWrapper` のインターフェース、共有使用量トラッキング、ネストされた `tool_input`、およびシリアライズ時の注意点については、[コンテキストガイド](context.md)をお読みください。
+完全な `RunContextWrapper` インターフェイス、共有された使用量追跡、ネストした `tool_input`、およびシリアライズ上の注意点については、[コンテキストガイド](context.md) を読んでください。
 
 ```python
 @dataclass
@@ -148,7 +148,7 @@ agent = Agent[UserContext](
 
 ## 出力型
 
-デフォルトでは、エージェントはプレーンテキスト (つまり `str`) の出力を生成します。エージェントに特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用することですが、Pydantic の [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型をサポートしています。dataclasses、lists、TypedDict などです。
+デフォルトでは、エージェントはプレーンテキスト (すなわち `str`) の出力を生成します。エージェントに特定の型の出力を生成させたい場合は、`output_type` パラメーターを使用できます。一般的な選択肢は [Pydantic](https://docs.pydantic.dev/) オブジェクトを使用することですが、Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) でラップできる任意の型にも対応しています。dataclasses、lists、TypedDict などです。
 
 ```python
 from pydantic import BaseModel
@@ -169,20 +169,20 @@ agent = Agent(
 
 !!! note
 
-    `output_type` を渡すと、通常のプレーンテキスト応答の代わりに [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するようモデルに指示します。
+    `output_type` を渡すと、モデルに通常のプレーンテキスト応答ではなく [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用するよう指示することになります。
 
 ## マルチエージェントシステムの設計パターン
 
-マルチエージェントシステムを設計する方法は多数ありますが、一般的には広く適用できる 2 つのパターンがよく見られます。
+マルチエージェントシステムを設計する方法は数多くありますが、幅広く適用できるパターンとして、よく見られるものが 2 つあります。
 
-1. マネージャー (agents as tools): 中央のマネージャー / オーケストレーターが、ツールとして公開された専門サブエージェントを呼び出し、会話の制御を保持します。
-2. ハンドオフ: 対等なエージェントが、会話を引き継ぐ専門エージェントへ制御を渡します。これは分散型です。
+1. マネージャー (agents as tools): 中央のマネージャー/オーケストレーターが、専門化されたサブエージェントをツールとして呼び出し、会話の制御を維持します。
+2. ハンドオフ: 対等なエージェントが、会話を引き継ぐ専門エージェントへ制御をハンドオフします。これは分散型です。
 
-詳細については、[エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)を参照してください。
+詳細は、[エージェント構築の実践ガイド](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf) を参照してください。
 
 ### マネージャー (agents as tools)
 
-`customer_facing_agent` はすべてのユーザー操作を処理し、ツールとして公開された専門サブエージェントを呼び出します。詳細は [ツール](tools.md#agents-as-tools) ドキュメントをお読みください。
+`customer_facing_agent` はユーザーとのやり取りをすべて処理し、ツールとして公開された専門サブエージェントを呼び出します。詳しくは [ツール](tools.md#agents-as-tools) ドキュメントを読んでください。
 
 ```python
 from agents import Agent
@@ -211,7 +211,7 @@ customer_facing_agent = Agent(
 
 ### ハンドオフ
 
-ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントは会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに優れたモジュール型の専門エージェントを実現できます。詳細は [ハンドオフ](handoffs.md) ドキュメントをお読みください。
+ハンドオフは、エージェントが委任できるサブエージェントです。ハンドオフが発生すると、委任先のエージェントが会話履歴を受け取り、会話を引き継ぎます。このパターンにより、単一タスクに優れた、モジュール化された専門エージェントを実現できます。詳しくは [ハンドオフ](handoffs.md) ドキュメントを読んでください。
 
 ```python
 from agents import Agent
@@ -232,7 +232,7 @@ triage_agent = Agent(
 
 ## 動的 instructions
 
-ほとんどの場合、エージェントを作成するときに instructions を指定できます。ただし、関数を介して動的 instructions を指定することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数の両方が受け付けられます。
+ほとんどの場合、エージェントを作成するときに instructions を指定できます。ただし、関数を通じて動的な instructions を提供することもできます。この関数はエージェントとコンテキストを受け取り、プロンプトを返す必要があります。通常の関数と `async` 関数のどちらも受け付けます。
 
 ```python
 def dynamic_instructions(
@@ -247,29 +247,29 @@ agent = Agent[UserContext](
 )
 ```
 
-## ライフサイクルイベント (hooks)
+## ライフサイクルイベント (フック)
 
-場合によっては、エージェントのライフサイクルを観察したいことがあります。たとえば、特定のイベントが発生したときに、イベントのログ記録、データの事前取得、使用量の記録を行いたい場合があります。
+場合によっては、エージェントのライフサイクルを監視したいことがあります。たとえば、特定のイベントが発生したときに、イベントをログに記録したり、データを事前取得したり、使用量を記録したりできます。
 
-フックには 2 つのスコープがあります。
+フックのスコープは 2 つあります。
 
--   [`RunHooks`][agents.lifecycle.RunHooks] は、他のエージェントへのハンドオフを含む `Runner.run(...)` 呼び出し全体を観察します。
--   [`AgentHooks`][agents.lifecycle.AgentHooks] は `agent.hooks` を介して特定のエージェントインスタンスにアタッチされます。
+-   [`RunHooks`][agents.lifecycle.RunHooks] は、他のエージェントへのハンドオフを含む `Runner.run(...)` 呼び出し全体を監視します。
+-   [`AgentHooks`][agents.lifecycle.AgentHooks] は、`agent.hooks` を通じて特定のエージェントインスタンスにアタッチされます。
 
-コールバックコンテキストも、イベントによって変わります。
+コールバックのコンテキストもイベントに応じて変わります。
 
--   エージェント開始 / 終了フックは [`AgentHookContext`][agents.run_context.AgentHookContext] を受け取ります。これは元のコンテキストをラップし、共有実行使用量状態を保持します。
+-   エージェントの開始/終了フックは [`AgentHookContext`][agents.run_context.AgentHookContext] を受け取ります。これは元のコンテキストをラップし、共有された実行使用量状態を保持します。
 -   LLM、ツール、ハンドオフのフックは [`RunContextWrapper`][agents.run_context.RunContextWrapper] を受け取ります。
 
 典型的なフックのタイミングは次のとおりです。
 
--   `on_agent_start` / `on_agent_end`: 特定のエージェントが最終出力の生成を開始または完了したとき。
--   `on_llm_start` / `on_llm_end`: 各モデル呼び出しの直前直後。
+-   `on_agent_start` / `on_agent_end`: 特定のエージェントが最終出力の生成を開始または終了するとき。
+-   `on_llm_start` / `on_llm_end`: 各モデル呼び出しの直前/直後。
 -   `on_tool_start` / `on_tool_end`: 各ローカルツール呼び出しの前後。
-    関数ツールでは、フックの `context` は通常 `ToolContext` であるため、`tool_call_id` などのツール呼び出しメタデータを確認できます。
--   `on_handoff`: 制御が 1 つのエージェントから別のエージェントへ移るとき。
+    関数ツールの場合、フックの `context` は通常 `ToolContext` なので、`tool_call_id` などのツール呼び出しメタデータを確認できます。
+-   `on_handoff`: 制御があるエージェントから別のエージェントへ移るとき。
 
-ワークフロー全体に対して 1 つのオブザーバーが必要な場合は `RunHooks` を使用し、1 つのエージェントにカスタム副作用が必要な場合は `AgentHooks` を使用してください。
+ワークフロー全体に対して単一のオブザーバーが必要な場合は `RunHooks` を使用し、1 つのエージェントにカスタム副作用が必要な場合は `AgentHooks` を使用します。
 
 ```python
 from agents import Agent, RunHooks, Runner
@@ -291,15 +291,15 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
 print(result.final_output)
 ```
 
-完全なコールバックインターフェースについては、[Lifecycle API リファレンス](ref/lifecycle.md)を参照してください。
+完全なコールバック API については、[ライフサイクル API リファレンス](ref/lifecycle.md) を参照してください。
 
 ## ガードレール
 
-ガードレールを使用すると、エージェントの実行と並行してユーザー入力に対するチェック / 検証を実行し、生成後のエージェント出力に対しても実行できます。たとえば、ユーザー入力とエージェント出力の関連性をスクリーニングできます。詳細は [ガードレール](guardrails.md) ドキュメントをお読みください。
+ガードレールを使うと、エージェントの実行と並行してユーザー入力に対するチェック/検証を実行し、エージェントの出力が生成された後にその出力に対するチェック/検証を実行できます。たとえば、ユーザー入力とエージェント出力について関連性をスクリーニングできます。詳しくは [ガードレール](guardrails.md) ドキュメントを読んでください。
 
-## エージェントのクローン / コピー
+## エージェントのクローン/コピー
 
-エージェントの `clone()` メソッドを使用すると、Agent を複製し、必要に応じて任意のプロパティを変更できます。
+エージェントの `clone()` メソッドを使用すると、エージェントを複製し、必要に応じて任意のプロパティを変更できます。
 
 ```python
 pirate_agent = Agent(
@@ -319,11 +319,11 @@ robot_agent = pirate_agent.clone(
 ツールのリストを指定しても、LLM が必ずツールを使用するとは限りません。[`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] を設定することで、ツール使用を強制できます。有効な値は次のとおりです。
 
 1. `auto`: LLM がツールを使用するかどうかを判断できるようにします。
-2. `required`: LLM にツールの使用を必須にします (ただし、どのツールを使うかは賢く判断できます)。
-3. `none`: LLM にツールを使用しないことを必須にします。
-4. 特定の文字列 (例: `my_tool`) を設定すると、LLM にその特定のツールの使用を必須にします。
+2. `required`: LLM にツールの使用を要求します (ただし、どのツールを使うかは賢く判断できます)。
+3. `none`: LLM にツールを使用 _しない_ ことを要求します。
+4. `my_tool` などの特定の文字列を設定すると、LLM にその特定のツールを使用することを要求します。
 
-OpenAI Responses のツール検索を使用している場合、名前付きツール選択にはより多くの制限があります。`tool_choice` で bare namespace 名や deferred-only ツールを対象にすることはできず、`tool_choice="tool_search"` は [`ToolSearchTool`][agents.tool.ToolSearchTool] を対象にしません。このような場合は、`auto` または `required` を優先してください。Responses 固有の制約については、[ホスト型ツール検索](tools.md#hosted-tool-search)を参照してください。
+OpenAI Responses のツール検索を使用している場合、名前付きツール選択にはより多くの制限があります。`tool_choice` で名前空間名だけや deferred-only ツールをターゲットにすることはできず、`tool_choice="tool_search"` は [`ToolSearchTool`][agents.tool.ToolSearchTool] をターゲットにしません。このような場合は、`auto` または `required` を優先してください。Responses 固有の制約については、[ホスト型ツール検索](tools.md#hosted-tool-search) を参照してください。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -341,12 +341,12 @@ agent = Agent(
 )
 ```
 
-## ツール使用動作
+## ツール使用の動作
 
-`Agent` 設定の `tool_use_behavior` パラメーターは、ツール出力の処理方法を制御します。
+`Agent` 設定の `tool_use_behavior` パラメーターは、ツール出力の扱い方を制御します。
 
 - `"run_llm_again"`: デフォルトです。ツールが実行され、LLM がその結果を処理して最終応答を生成します。
-- `"stop_on_first_tool"`: 最初のツール呼び出しの出力が、それ以上の LLM 処理なしで最終応答として使用されます。
+- `"stop_on_first_tool"`: 最初のツール呼び出しの出力が、追加の LLM 処理なしで最終応答として使用されます。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -388,7 +388,7 @@ agent = Agent(
 )
 ```
 
-- `ToolsToFinalOutputFunction`: ツール結果を処理し、LLM で停止するか継続するかを決定するカスタム関数。
+- `ToolsToFinalOutputFunction`: ツールの結果を処理し、停止するか、LLM による処理を続行するかを決定するカスタム関数です。
 
 ```python
 from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -426,4 +426,4 @@ agent = Agent(
 
 !!! note
 
-    無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが起きる理由は、ツール結果が LLM に送信され、その後 `tool_choice` によって LLM がさらに別のツール呼び出しを生成し、これが際限なく続くためです。
+    無限ループを防ぐため、フレームワークはツール呼び出し後に `tool_choice` を自動的に "auto" にリセットします。この動作は [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] で設定できます。無限ループが発生するのは、ツールの結果が LLM に送信され、その後 `tool_choice` のために LLM が別のツール呼び出しを生成し、これが際限なく繰り返されるためです。

docs/ja/config.md

@@ -4,21 +4,21 @@ search:
 ---
 # 設定
 
-このページでは、通常はアプリケーション起動時に 1 度だけ設定する SDK 全体のデフォルト（デフォルトの OpenAI キーまたはクライアント、デフォルトの OpenAI API 形式、トレーシングエクスポートのデフォルト、ログ動作など）を扱います。
+このページでは、デフォルトの OpenAI キーまたはクライアント、デフォルトの OpenAI API の形式、トレーシングエクスポートのデフォルト、ログ記録の動作など、アプリケーション起動時に通常一度だけ設定する SDK 全体のデフォルトについて説明します。
 
-これらのデフォルトは sandbox ベースのワークフローにも適用されますが、sandbox ワークスペース、sandbox クライアント、セッション再利用は別途設定します。
+これらのデフォルトはサンドボックスベースのワークフローにも適用されますが、サンドボックスワークスペース、サンドボックスクライアント、セッション再利用は別途設定します。
 
-代わりに特定のエージェントや実行を設定する必要がある場合は、次から始めてください:
+代わりに特定のエージェントまたは実行を設定する必要がある場合は、まず次を参照してください:
 
--   通常の `Agent` における instructions、ツール、出力タイプ、ハンドオフ、ガードレールについては [Agents](agents.md)。
--   `RunConfig`、セッション、会話状態オプションについては [エージェントの実行](running_agents.md)。
--   `SandboxRunConfig`、マニフェスト、機能、sandbox クライアント固有のワークスペース設定については [Sandbox エージェント](sandbox/guide.md)。
--   モデル選択とプロバイダー設定については [Models](models/index.md)。
--   実行ごとのトレーシングメタデータとカスタムトレースプロセッサーについては [トレーシング](tracing.md)。
+-   [エージェント](agents.md): 通常の `Agent` における instructions、tools、出力型、ハンドオフ、ガードレールについて。
+-   [エージェントの実行](running_agents.md): `RunConfig`、セッション、会話状態のオプションについて。
+-   [サンドボックスエージェント](sandbox/guide.md): `SandboxRunConfig`、マニフェスト、機能、サンドボックスクライアント固有のワークスペース設定について。
+-   [モデル](models/index.md): モデル選択とプロバイダー設定について。
+-   [トレーシング](tracing.md): 実行ごとのトレーシングメタデータとカスタムトレースプロセッサーについて。
 
 ## API キーとクライアント
 
-デフォルトでは、SDK は LLM リクエストとトレーシングに `OPENAI_API_KEY` 環境変数を使用します。キーは SDK が最初に OpenAI クライアントを作成する際（遅延初期化）に解決されるため、最初のモデル呼び出し前に環境変数を設定してください。アプリ起動前にその環境変数を設定できない場合は、キーを設定するために [set_default_openai_key()][agents.set_default_openai_key] 関数を使用できます。
+デフォルトでは、SDK は LLM リクエストとトレーシングに `OPENAI_API_KEY` 環境変数を使用します。このキーは、SDK が最初に OpenAI クライアントを作成するときに解決されます（遅延初期化）。そのため、最初のモデル呼び出しの前に環境変数を設定してください。アプリの起動前にその環境変数を設定できない場合は、[set_default_openai_key()][agents.set_default_openai_key] 関数を使用してキーを設定できます。
 
 ```python
 from agents import set_default_openai_key
@@ -26,7 +26,7 @@ from agents import set_default_openai_key
 set_default_openai_key("sk-...")
 ```
 
-または、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数の API キーまたは上記で設定したデフォルトキーを使用して `AsyncOpenAI` インスタンスを作成します。これは [set_default_openai_client()][agents.set_default_openai_client] 関数で変更できます。
+また、使用する OpenAI クライアントを設定することもできます。デフォルトでは、SDK は環境変数の API キー、または上記で設定したデフォルトキーを使用して、`AsyncOpenAI` インスタンスを作成します。これは [set_default_openai_client()][agents.set_default_openai_client] 関数を使用して変更できます。
 
 ```python
 from openai import AsyncOpenAI
@@ -36,14 +36,14 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
 set_default_openai_client(custom_client)
 ```
 
-環境変数ベースのエンドポイント設定を使いたい場合、デフォルトの OpenAI プロバイダーは `OPENAI_BASE_URL` も読み取ります。Responses websocket トランスポートを有効にすると、websocket `/responses` エンドポイント用に `OPENAI_WEBSOCKET_BASE_URL` も読み取ります。
+環境変数ベースのエンドポイント設定を使用したい場合、デフォルトの OpenAI プロバイダーは `OPENAI_BASE_URL` も読み取ります。Responses websocket トランスポートを有効にすると、websocket の `/responses` エンドポイント用に `OPENAI_WEBSOCKET_BASE_URL` も読み取ります。
 
 ```bash
 export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1"
 export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1"
 ```
 
-最後に、使用する OpenAI API をカスタマイズすることもできます。デフォルトでは OpenAI Responses API を使用します。これは [set_default_openai_api()][agents.set_default_openai_api] 関数を使って Chat Completions API を使うように上書きできます。
+最後に、使用する OpenAI API もカスタマイズできます。デフォルトでは OpenAI Responses API を使用します。[set_default_openai_api()][agents.set_default_openai_api] 関数を使用すると、これを Chat Completions API に上書きできます。
 
 ```python
 from agents import set_default_openai_api
@@ -53,7 +53,7 @@ set_default_openai_api("chat_completions")
 
 ## トレーシング
 
-トレーシングはデフォルトで有効です。デフォルトでは、上のセクションのモデルリクエストと同じ OpenAI API キー（つまり環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーは [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数で明示的に設定できます。
+トレーシングはデフォルトで有効です。デフォルトでは、上のセクションで説明したモデルリクエストと同じ OpenAI API キー（つまり、環境変数または設定したデフォルトキー）を使用します。トレーシングに使用する API キーは、[`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 関数を使用して個別に設定できます。
 
 ```python
 from agents import set_tracing_export_api_key
@@ -61,7 +61,7 @@ from agents import set_tracing_export_api_key
 set_tracing_export_api_key("sk-...")
 ```
 
-モデル通信があるキーまたはクライアントを使い、トレーシングは別の OpenAI キーを使う必要がある場合、デフォルトキーまたはクライアント設定時に `use_for_tracing=False` を渡してから、トレーシングを個別に設定してください。カスタムクライアントを使わない場合は [`set_default_openai_key()`][agents.set_default_openai_key] でも同じパターンが使えます。
+モデルのトラフィックにはあるキーまたはクライアントを使用し、トレーシングには別の OpenAI キーを使用したい場合は、デフォルトキーまたはクライアントを設定するときに `use_for_tracing=False` を渡してから、トレーシングを別途設定します。カスタムクライアントを使用していない場合は、[`set_default_openai_key()`][agents.set_default_openai_key] でも同じパターンを使用できます。
 
 ```python
 from openai import AsyncOpenAI
@@ -76,7 +76,7 @@ set_default_openai_client(custom_client, use_for_tracing=False)
 set_tracing_export_api_key("sk-tracing")
 ```
 
-デフォルトのエクスポーター使用時に、トレースを特定の組織またはプロジェクトに紐付ける必要がある場合は、アプリ起動前に以下の環境変数を設定してください:
+デフォルトのエクスポーターを使用する際に、トレースを特定の組織またはプロジェクトに関連付ける必要がある場合は、アプリの起動前にこれらの環境変数を設定してください:
 
 ```bash
 export OPENAI_ORG_ID="org_..."
@@ -103,7 +103,7 @@ from agents import set_tracing_disabled
 set_tracing_disabled(True)
 ```
 
-トレーシングを有効のまま、トレースペイロードから機密性の高い可能性がある入出力を除外したい場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を `False` に設定してください:
+トレーシングは有効のまま、機密性がある可能性のある入力/出力をトレースペイロードから除外したい場合は、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を `False` に設定します:
 
 ```python
 from agents import Runner, RunConfig
@@ -115,19 +115,19 @@ await Runner.run(
 )
 ```
 
-アプリ起動前にこの環境変数を設定すれば、コードなしでデフォルトを変更することもできます:
+アプリの起動前にこの環境変数を設定することで、コードを変更せずにデフォルトを変更することもできます:
 
 ```bash
 export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0
 ```
 
-トレーシング制御の全体については、[トレーシングガイド](tracing.md) を参照してください。
+トレーシング制御の詳細は、[トレーシングガイド](tracing.md) を参照してください。
 
 ## デバッグログ
 
-SDK は 2 つの Python ロガー（`openai.agents` と `openai.agents.tracing`）を定義しており、デフォルトではハンドラーをアタッチしません。ログはアプリケーションの Python ログ設定に従います。
+SDK は 2 つの Python ロガー（`openai.agents` と `openai.agents.tracing`）を定義しますが、デフォルトではハンドラーをアタッチしません。ログはアプリケーションの Python ロギング設定に従います。
 
-詳細ログを有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
+詳細なログ出力を有効にするには、[`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 関数を使用します。
 
 ```python
 from agents import enable_verbose_stdout_logging
@@ -135,7 +135,7 @@ from agents import enable_verbose_stdout_logging
 enable_verbose_stdout_logging()
 ```
 
-または、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python logging guide](https://docs.python.org/3/howto/logging.html) を参照してください。
+または、ハンドラー、フィルター、フォーマッターなどを追加してログをカスタマイズできます。詳細は [Python ロギングガイド](https://docs.python.org/3/howto/logging.html) で確認できます。
 
 ```python
 import logging
@@ -156,16 +156,16 @@ logger.addHandler(logging.StreamHandler())
 
 ### ログ内の機密データ
 
-特定のログには機密データ（たとえばユーザーデータ）が含まれる場合があります。
+一部のログには機密データ（たとえば、ユーザーデータ）が含まれる場合があります。
 
-デフォルトでは、SDK は LLM の入出力やツールの入出力を **ログに記録しません**。これらの保護は次によって制御されます:
+デフォルトでは、SDK は LLM の入力/出力やツールの入力/出力を **ログに記録しません** 。これらの保護は次で制御されます:
 
 ```bash
 OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
 OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
 ```
 
-デバッグのために一時的にこれらのデータを含める必要がある場合は、アプリ起動前にいずれかの変数を `0`（または `false`）に設定してください:
+デバッグのためにこのデータを一時的に含める必要がある場合は、アプリの起動前にいずれかの変数を `0`（または `false`）に設定します:
 
 ```bash
 export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0

docs/ja/context.md

@@ -4,49 +4,49 @@ search:
 ---
 # コンテキスト管理
 
-コンテキストは多義的な用語です。主に、重要になるコンテキストには 2 つの分類があります。
+コンテキストは多義的な用語です。考慮すべきコンテキストには、主に 2 つの種類があります:
 
-1. コード内でローカルに利用可能なコンテキスト: これは、関数ツールの実行時、`on_handoff` のようなコールバック時、ライフサイクルフック時などに必要になる可能性があるデータや依存関係です。
-2. LLM が利用可能なコンテキスト: これは、LLM がレスポンスを生成するときに参照するデータです。
+1. コードからローカルに利用できるコンテキスト: これは、ツール関数の実行時、`on_handoff` のようなコールバック内、ライフサイクルフック内などで必要になる可能性のあるデータや依存関係です。
+2. LLM が利用できるコンテキスト: これは、LLM が応答を生成するときに参照するデータです。
 
 ## ローカルコンテキスト
 
-これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラスと、その内部の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。動作は次のとおりです。
+これは [`RunContextWrapper`][agents.run_context.RunContextWrapper] クラス、およびその中の [`context`][agents.run_context.RunContextWrapper.context] プロパティで表現されます。仕組みは次のとおりです:
 
-1. 任意の Python オブジェクトを作成します。一般的なパターンは、dataclass または Pydantic オブジェクトを使うことです。
-2. そのオブジェクトを各種 run メソッドに渡します（例: `Runner.run(..., context=whatever)`）。
-3. すべてのツール呼び出し、ライフサイクルフックなどには `RunContextWrapper[T]` のラッパーオブジェクトが渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` でアクセスできます。
+1. 任意の Python オブジェクトを作成します。一般的なパターンは dataclass や Pydantic オブジェクトを使用することです。
+2. そのオブジェクトを各種実行メソッドに渡します (例: `Runner.run(..., context=whatever)`)。
+3. すべてのツール呼び出し、ライフサイクルフックなどには、ラッパーオブジェクト `RunContextWrapper[T]` が渡されます。ここで `T` はコンテキストオブジェクトの型を表し、`wrapper.context` を通じてアクセスできます。
 
-ランタイム固有の一部コールバックでは、SDK が `RunContextWrapper[T]` のより特化したサブクラスを渡す場合があります。たとえば、関数ツールのライフサイクルフックは通常 `ToolContext` を受け取り、`tool_call_id`、`tool_name`、`tool_arguments` などのツール呼び出しメタデータにもアクセスできます。
+一部のランタイム固有のコールバックでは、SDK はより特殊化された `RunContextWrapper[T]` のサブクラスを渡す場合があります。たとえば、関数ツールのライフサイクルフックは通常 `ToolContext` を受け取り、これは `tool_call_id`、`tool_name`、`tool_arguments` などのツール呼び出しメタデータも公開します。
 
-認識しておくべき **最も重要** な点: 特定のエージェント実行におけるすべてのエージェント、関数ツール、ライフサイクルなどは、同じコンテキストの _型_ を使用する必要があります。
+認識すべき **最も重要な** 点は、あるエージェント実行におけるすべてのエージェント、ツール関数、ライフサイクルなどが、同じ _型_ のコンテキストを使用しなければならないということです。
 
-コンテキストは次のような用途で使用できます。
+コンテキストは、たとえば次の用途に使用できます:
 
--   実行のためのコンテキストデータ（例: ユーザー名 / uid や、ユーザーに関するその他の情報）
--   依存関係（例: logger オブジェクト、データ取得処理など）
+-   実行時のコンテキストデータ (例: ユーザー名 / uid や、ユーザーに関するその他の情報)
+-   依存関係 (例: ロガーオブジェクト、データ取得器など)
 -   ヘルパー関数
 
-!!! danger "注意"
+!!! danger "注記"
 
-    コンテキストオブジェクトは LLM に **送信されません**。これは純粋にローカルオブジェクトであり、読み取り、書き込み、メソッド呼び出しが可能です。
+    コンテキストオブジェクトは LLM に **送信されません**。これは完全にローカルなオブジェクトであり、読み取り、書き込み、メソッドの呼び出しができます。
 
-1 回の実行内では、派生ラッパーは同じ基盤のアプリコンテキスト、承認状態、使用量トラッキングを共有します。ネストした [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行では別の `tool_input` が付与される場合がありますが、デフォルトではアプリ状態の分離コピーは取得しません。
+1 回の実行内では、派生したラッパーは同じ基盤となるアプリコンテキスト、承認状態、使用状況の追跡を共有します。ネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] の実行では異なる `tool_input` を付加する場合がありますが、デフォルトではアプリ状態の分離コピーは取得しません。
 
 ### `RunContextWrapper` の公開内容
 
-[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、アプリで定義したコンテキストオブジェクトのラッパーです。実際には、主に次を使用します。
+[`RunContextWrapper`][agents.run_context.RunContextWrapper] は、アプリで定義したコンテキストオブジェクトを包むラッパーです。実際には、ほとんどの場合、次のものを使用します:
 
--   独自の可変アプリ状態および依存関係には [`wrapper.context`][agents.run_context.RunContextWrapper.context]。
--   現在の実行全体の集計されたリクエストおよびトークン使用量には [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]。
--   現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] 内で実行されているときの構造化入力には [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]。
--   承認状態をプログラムで更新する必要がある場合は [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]。
+-   [`wrapper.context`][agents.run_context.RunContextWrapper.context]: 独自の可変なアプリ状態と依存関係に使用します。
+-   [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]: 現在の実行全体で集計されたリクエストおよびトークン使用量に使用します。
+-   [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]: 現在の実行が [`Agent.as_tool()`][agents.agent.Agent.as_tool] の内部で実行されている場合の構造化入力に使用します。
+-   [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]: 承認状態をプログラムで更新する必要がある場合に使用します。
 
 アプリで定義したオブジェクトは `wrapper.context` のみです。その他のフィールドは SDK が管理するランタイムメタデータです。
 
-後で human-in-the-loop や永続ジョブワークフロー向けに [`RunState`][agents.run_state.RunState] をシリアライズする場合、そのランタイムメタデータは状態とともに保存されます。シリアライズした状態を永続化または送信する予定がある場合は、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] にシークレットを入れないでください。
+後で human-in-the-loop や耐久ジョブワークフローのために [`RunState`][agents.run_state.RunState] をシリアライズする場合、そのランタイムメタデータは状態とともに保存されます。シリアライズされた状態を永続化または送信する予定がある場合、[`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] にシークレットを入れないでください。
 
-会話状態は別の関心事項です。ターンをどのように引き継ぐかに応じて、`result.to_input_list()`、`session`、`conversation_id`、または `previous_response_id` を使用してください。この判断については [results](results.md)、[running agents](running_agents.md)、[sessions](sessions/index.md) を参照してください。
+会話状態は別の関心事です。ターンをどのように引き継ぐかに応じて、`result.to_input_list()`、`session`、`conversation_id`、または `previous_response_id` を使用してください。その判断については、[実行結果](results.md)、[エージェントの実行](running_agents.md)、[セッション](sessions/index.md) を参照してください。
 
 ```python
 import asyncio
@@ -85,18 +85,18 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-1. これはコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。
-2. これはツールです。`RunContextWrapper[UserInfo]` を受け取ることがわかります。ツール実装はコンテキストから読み取ります。
-3. 型チェッカーがエラーを検出できるように、エージェントをジェネリック `UserInfo` で指定します（たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合）。
+1. これがコンテキストオブジェクトです。ここでは dataclass を使用していますが、任意の型を使用できます。
+2. これはツールです。`RunContextWrapper[UserInfo]` を受け取っていることがわかります。ツール実装はコンテキストから読み取ります。
+3. 型チェッカーがエラーを検出できるように、エージェントにジェネリック `UserInfo` を指定します (たとえば、異なるコンテキスト型を受け取るツールを渡そうとした場合)。
 4. コンテキストは `run` 関数に渡されます。
 5. エージェントは正しくツールを呼び出し、年齢を取得します。
 
 ---
 
-### 高度な使用法: `ToolContext`
+### 高度な内容: `ToolContext`
 
-場合によっては、実行中のツールに関する追加メタデータ（名前、呼び出し ID、生の引数文字列など）にアクセスしたいことがあります。  
-このために、`RunContextWrapper` を拡張する [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。
+場合によっては、実行中のツールに関する追加メタデータ (名前、呼び出し ID、生の引数文字列など) にアクセスしたいことがあります。  
+この場合、`RunContextWrapper` を拡張する [`ToolContext`][agents.tool_context.ToolContext] クラスを使用できます。
 
 ```python
 from typing import Annotated
@@ -125,24 +125,24 @@ agent = Agent(
 ```
 
 `ToolContext` は `RunContextWrapper` と同じ `.context` プロパティを提供し、  
-さらに現在のツール呼び出しに固有の追加フィールドも提供します。
+現在のツール呼び出しに固有の追加フィールドも提供します:
 
-- `tool_name` – 呼び出されるツールの名前  
-- `tool_call_id` – このツール呼び出しの一意識別子  
-- `tool_arguments` – ツールに渡される生の引数文字列  
-- `tool_namespace` – ツールが `tool_namespace()` または他の名前空間付きサーフェスを通じて読み込まれた場合の、ツール呼び出しの Responses 名前空間  
-- `qualified_tool_name` – 名前空間が利用可能な場合に、その名前空間で修飾されたツール名  
+- `tool_name` – 呼び出されているツールの名前  
+- `tool_call_id` – このツール呼び出しの一意の識別子  
+- `tool_arguments` – ツールに渡された生の引数文字列  
+- `tool_namespace` – ツールが `tool_namespace()` または別の名前空間付きサーフェスを通じて読み込まれた場合の、ツール呼び出しに対する Responses 名前空間  
+- `qualified_tool_name` – 名前空間が利用できる場合に、その名前空間で修飾されたツール名  
 
-実行中にツールレベルのメタデータが必要な場合は `ToolContext` を使用してください。  
-エージェントとツール間の一般的なコンテキスト共有には、`RunContextWrapper` で十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストした `Agent.as_tool()` 実行が構造化入力を提供した場合は `.tool_input` も公開できます。
+実行中にツールレベルのメタデータが必要な場合は、`ToolContext` を使用してください。  
+エージェントとツール間で一般的なコンテキスト共有を行うには、`RunContextWrapper` のままで十分です。`ToolContext` は `RunContextWrapper` を拡張しているため、ネストされた `Agent.as_tool()` 実行が構造化入力を提供した場合には `.tool_input` も公開できます。
 
 ---
 
 ## エージェント / LLM コンテキスト
 
-LLM が呼び出されると、参照できるデータは会話履歴にあるもの **のみ** です。つまり、新しいデータを LLM で利用可能にしたい場合は、その履歴で利用できる形にする必要があります。方法はいくつかあります。
+LLM が呼び出されるとき、その LLM が参照できる **唯一の** データは会話履歴に含まれるものです。つまり、新しいデータを LLM に利用可能にしたい場合は、その履歴内で利用可能になるような方法で行う必要があります。これにはいくつかの方法があります:
 
-1. エージェントの `instructions` に追加します。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的文字列にもできますし、コンテキストを受け取って文字列を返す動的関数にもできます。これは、常に有用な情報（たとえばユーザー名や現在日付）に対する一般的な手法です。
-2. `Runner.run` 関数を呼び出す際の `input` に追加します。これは `instructions` の手法に似ていますが、[chain of command](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) でより下位のメッセージを持てます。
-3. 関数ツールを介して公開します。これは _オンデマンド_ のコンテキストに有用です。LLM がデータを必要とするタイミングを判断し、そのデータを取得するためにツールを呼び出せます。
-4. retrieval または Web 検索を使用します。これらは、ファイルやデータベース（retrieval）、または Web（Web 検索）から関連データを取得できる特別なツールです。これは、レスポンスを関連するコンテキストデータに「グラウンディング」するのに有用です。
+1. エージェントの `instructions` に追加できます。これは「システムプロンプト」または「開発者メッセージ」とも呼ばれます。システムプロンプトは静的文字列にも、コンテキストを受け取って文字列を出力する動的関数にもできます。これは、常に役立つ情報 (たとえば、ユーザーの名前や現在の日付) に対する一般的な手法です。
+2. `Runner.run` 関数を呼び出すときに `input` に追加します。これは `instructions` の手法に似ていますが、[指揮系統](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command) においてより下位のメッセージにできます。
+3. 関数ツールを介して公開します。これは _オンデマンド_ のコンテキストに便利です。LLM がデータを必要とするタイミングを判断し、そのデータを取得するためにツールを呼び出せます。
+4. リトリーバルまたは Web 検索を使用します。これらは、ファイルやデータベースから関連データを取得する (リトリーバル)、または Web から取得する (Web 検索) ことができる特殊なツールです。これは、関連するコンテキストデータに基づいて応答を「グラウンディング」するのに便利です。

docs/ja/examples.md

@@ -4,139 +4,139 @@ search:
 ---
 # コード例
 
-[repo](https://github.com/openai/openai-agents-python/tree/main/examples) の examples セクションで、 SDK のさまざまなサンプル実装を確認できます。これらのコード例は、異なるパターンと機能を示す複数のカテゴリーに整理されています。
+SDK のさまざまなサンプル実装は、[リポジトリ](https://github.com/openai/openai-agents-python/tree/main/examples)の examples セクションで確認できます。これらのコード例は、さまざまなパターンや機能を示す複数のカテゴリーに整理されています。
 
 ## カテゴリー
 
 -   **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
-    このカテゴリーのコード例では、次のような一般的なエージェント設計パターンを示します。
+    このカテゴリーのコード例は、次のような一般的なエージェント設計パターンを示します。
 
     -   決定論的ワークフロー
     -   Agents as tools
     -   ストリーミングイベントを伴う Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`)
     -   構造化入力パラメーターを伴う Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`)
-    -   並列エージェント実行
+    -   エージェントの並列実行
     -   条件付きツール使用
-    -   異なる挙動でツール使用を強制する (`examples/agent_patterns/forcing_tool_use.py`)
-    -   入力 / 出力ガードレール
-    -   審査者としての LLM
+    -   異なる動作でツール使用を強制 (`examples/agent_patterns/forcing_tool_use.py`)
+    -   入出力ガードレール
+    -   ジャッジとしての LLM
     -   ルーティング
     -   ストリーミングガードレール
-    -   ツール承認と状態シリアライズを伴う Human-in-the-loop (`examples/agent_patterns/human_in_the_loop.py`)
-    -   ストリーミングを伴う Human-in-the-loop (`examples/agent_patterns/human_in_the_loop_stream.py`)
-    -   承認フロー向けのカスタム拒否メッセージ (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`)
+    -   ツール承認と状態シリアライズを伴う人間参加型 (`examples/agent_patterns/human_in_the_loop.py`)
+    -   ストリーミングを伴う人間参加型 (`examples/agent_patterns/human_in_the_loop_stream.py`)
+    -   承認フロー用のカスタム拒否メッセージ (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`)
 
 -   **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
-    これらのコード例では、次のような SDK の基本機能を紹介します。
+    これらのコード例では、SDK の基本的な機能を紹介します。たとえば、次のようなものです。
 
-    -   Hello world のコード例 (デフォルトモデル、 GPT-5、 open-weight モデル)
+    -   Hello world の例 (デフォルトモデル、GPT-5、オープンウェイトモデル)
     -   エージェントライフサイクル管理
-    -   Run hooks と agent hooks のライフサイクル例 (`examples/basic/lifecycle_example.py`)
+    -   実行フックとエージェントフックのライフサイクル例 (`examples/basic/lifecycle_example.py`)
     -   動的システムプロンプト
     -   基本的なツール使用 (`examples/basic/tools.py`)
-    -   ツール入力 / 出力ガードレール (`examples/basic/tool_guardrails.py`)
+    -   ツール入出力ガードレール (`examples/basic/tool_guardrails.py`)
     -   画像ツール出力 (`examples/basic/image_tool_output.py`)
-    -   ストリーミング出力 (テキスト、項目、関数呼び出し引数)
-    -   複数ターンで共有セッションヘルパーを使用する Responses websocket transport (`examples/basic/stream_ws.py`)
+    -   ストリーミング出力 (テキスト、アイテム、関数呼び出し引数)
+    -   ターン間で共有セッションヘルパーを使用する Responses WebSocket トランスポート (`examples/basic/stream_ws.py`)
     -   プロンプトテンプレート
     -   ファイル処理 (ローカルとリモート、画像と PDF)
-    -   使用状況追跡
-    -   Runner 管理の再試行設定 (`examples/basic/retry.py`)
-    -   サードパーティアダプター経由の Runner 管理再試行 (`examples/basic/retry_litellm.py`)
-    -   非 strict な出力型
-    -   以前の response ID の使用
+    -   使用状況の追跡
+    -   Runner 管理のリトライ設定 (`examples/basic/retry.py`)
+    -   サードパーティアダプターを介した Runner 管理のリトライ (`examples/basic/retry_litellm.py`)
+    -   非厳密な出力型
+    -   以前のレスポンス ID の使用
 
 -   **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
-    航空会社向けのカスタマーサービスシステムのコード例です。
+    航空会社向けのカスタマーサービスシステムの例です。
 
 -   **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
-    金融データ分析のためのエージェントとツールを用いた、構造化された調査ワークフローを示す金融リサーチエージェントです。
+    金融データ分析向けのエージェントとツールを使った、構造化されたリサーチワークフローを示す金融リサーチエージェントです。
 
 -   **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
-    メッセージフィルタリングを含む、エージェントのハンドオフの実践的なコード例です。
+    メッセージフィルタリングを伴うエージェントのハンドオフの実用的なコード例です。以下を含みます:
 
-    -   メッセージフィルター例 (`examples/handoffs/message_filter.py`)
+    -   メッセージフィルターの例 (`examples/handoffs/message_filter.py`)
     -   ストリーミングを伴うメッセージフィルター (`examples/handoffs/message_filter_streaming.py`)
 
 -   **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
-    OpenAI Responses API で hosted MCP (Model Context Protocol) を使用する方法を示すコード例です。以下を含みます。
+    OpenAI Responses API でホスト型 MCP (Model Context Protocol) を使用する方法を示すコード例です。以下を含みます:
 
-    -   承認なしのシンプルな hosted MCP (`examples/hosted_mcp/simple.py`)
+    -   承認なしのシンプルなホスト型 MCP (`examples/hosted_mcp/simple.py`)
     -   Google Calendar などの MCP コネクター (`examples/hosted_mcp/connectors.py`)
-    -   割り込みベース承認を伴う Human-in-the-loop (`examples/hosted_mcp/human_in_the_loop.py`)
-    -   MCP ツール呼び出しの on-approval コールバック (`examples/hosted_mcp/on_approval.py`)
+    -   中断ベースの承認を伴う人間参加型 (`examples/hosted_mcp/human_in_the_loop.py`)
+    -   MCP ツール呼び出しの承認時コールバック (`examples/hosted_mcp/on_approval.py`)
 
 -   **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
-    以下を含め、 MCP (Model Context Protocol) でエージェントを構築する方法を学べます。
+    MCP (Model Context Protocol) でエージェントを構築する方法を学びます。以下を含みます:
 
-    -   Filesystem のコード例
-    -   Git のコード例
-    -   MCP prompt server のコード例
-    -   SSE (Server-Sent Events) のコード例
+    -   ファイルシステムの例
+    -   Git の例
+    -   MCP プロンプトサーバーの例
+    -   SSE (Server-Sent Events) の例
     -   SSE リモートサーバー接続 (`examples/mcp/sse_remote_example`)
-    -   Streamable HTTP のコード例
+    -   Streamable HTTP の例
     -   Streamable HTTP リモート接続 (`examples/mcp/streamable_http_remote_example`)
-    -   Streamable HTTP 向けカスタム HTTP client factory (`examples/mcp/streamablehttp_custom_client_example`)
-    -   `MCPUtil.get_all_function_tools` による全 MCP ツールの事前取得 (`examples/mcp/get_all_mcp_tools_example`)
+    -   Streamable HTTP 用のカスタム HTTP クライアントファクトリー (`examples/mcp/streamablehttp_custom_client_example`)
+    -   `MCPUtil.get_all_function_tools` によるすべての MCP ツールの事前取得 (`examples/mcp/get_all_mcp_tools_example`)
     -   FastAPI を使用した MCPServerManager (`examples/mcp/manager_example`)
     -   MCP ツールフィルタリング (`examples/mcp/tool_filter_example`)
 
 -   **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
-    エージェント向けのさまざまなメモリ実装のコード例です。以下を含みます。
+    エージェント向けのさまざまなメモリ実装のコード例です。以下を含みます:
 
     -   SQLite セッションストレージ
     -   高度な SQLite セッションストレージ
     -   Redis セッションストレージ
     -   SQLAlchemy セッションストレージ
-    -   Dapr state store セッションストレージ
+    -   Dapr 状態ストアセッションストレージ
     -   暗号化セッションストレージ
     -   OpenAI Conversations セッションストレージ
-    -   Responses compaction セッションストレージ
-    -   `ModelSettings(store=False)` を使用したステートレスな Responses compaction (`examples/memory/compaction_session_stateless_example.py`)
-    -   ファイルベースのセッションストレージ (`examples/memory/file_session.py`)
-    -   Human-in-the-loop を伴うファイルベースセッション (`examples/memory/file_hitl_example.py`)
-    -   Human-in-the-loop を伴う SQLite インメモリセッション (`examples/memory/memory_session_hitl_example.py`)
-    -   Human-in-the-loop を伴う OpenAI Conversations セッション (`examples/memory/openai_session_hitl_example.py`)
+    -   Responses 圧縮セッションストレージ
+    -   `ModelSettings(store=False)` を使用したステートレスな Responses 圧縮 (`examples/memory/compaction_session_stateless_example.py`)
+    -   ファイルバック型セッションストレージ (`examples/memory/file_session.py`)
+    -   人間参加型を伴うファイルバック型セッション (`examples/memory/file_hitl_example.py`)
+    -   人間参加型を伴う SQLite インメモリセッション (`examples/memory/memory_session_hitl_example.py`)
+    -   人間参加型を伴う OpenAI Conversations セッション (`examples/memory/openai_session_hitl_example.py`)
     -   セッションをまたぐ HITL 承認 / 拒否シナリオ (`examples/memory/hitl_session_scenario.py`)
 
 -   **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
-    カスタムプロバイダーやサードパーティアダプターを含め、 SDK で非 OpenAI モデルを使用する方法を確認できます。
+    カスタムプロバイダーやサードパーティアダプターを含め、SDK で OpenAI 以外のモデルを使用する方法を確認できます。
 
 -   **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
-    SDK を使用してリアルタイム体験を構築する方法を示すコード例です。以下を含みます。
+    SDK を使用してリアルタイム体験を構築する方法を示すコード例です。以下を含みます:
 
-    -   構造化されたテキストおよび画像メッセージによる Web アプリケーションパターン
+    -   構造化テキストと画像メッセージを扱う Web アプリケーションパターン
     -   コマンドライン音声ループと再生処理
     -   WebSocket 経由の Twilio Media Streams 統合
-    -   Realtime Calls API attach フローを使用した Twilio SIP 統合
+    -   Realtime Calls API の attach フローを使用した Twilio SIP 統合
 
 -   **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
-    reasoning content の扱い方を示すコード例です。以下を含みます。
+    推論コンテンツの扱い方を示すコード例です。以下を含みます:
 
-    -   Runner API、ストリーミング、非ストリーミングでの reasoning content (`examples/reasoning_content/runner_example.py`)
-    -   OpenRouter 経由で OSS モデルを使用した reasoning content (`examples/reasoning_content/gpt_oss_stream.py`)
-    -   基本的な reasoning content のコード例 (`examples/reasoning_content/main.py`)
+    -   Runner API での推論コンテンツ、ストリーミングと非ストリーミング (`examples/reasoning_content/runner_example.py`)
+    -   OpenRouter 経由の OSS モデルでの推論コンテンツ (`examples/reasoning_content/gpt_oss_stream.py`)
+    -   基本的な推論コンテンツの例 (`examples/reasoning_content/main.py`)
 
 -   **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
-    複雑なマルチエージェント調査ワークフローを示す、シンプルなディープリサーチクローンです。
+    複雑なマルチエージェントリサーチワークフローを示す、シンプルなディープリサーチのクローンです。
 
 -   **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
-    以下のような OpenAI がホストするツールと実験的な Codex ツール機能の実装方法を学べます。
+    OpenAI がホストするツールや、次のような実験的な Codex ツール群の実装方法を学びます:
 
-    -   Web 検索 とフィルター付き Web 検索
+    -   Web 検索およびフィルター付き Web 検索
     -   ファイル検索
     -   Code interpreter
     -   ファイル編集と承認を伴う apply patch ツール (`examples/tools/apply_patch.py`)
-    -   承認コールバックを伴う shell ツール実行 (`examples/tools/shell.py`)
-    -   Human-in-the-loop 割り込みベース承認を伴う shell ツール (`examples/tools/shell_human_in_the_loop.py`)
-    -   インラインスキルを伴う hosted container shell (`examples/tools/container_shell_inline_skill.py`)
-    -   スキル参照を伴う hosted container shell (`examples/tools/container_shell_skill_reference.py`)
-    -   ローカルスキルを伴う local shell (`examples/tools/local_shell_skill.py`)
-    -   名前空間と遅延ツールを伴うツール検索 (`examples/tools/tool_search.py`)
+    -   承認コールバックを伴うシェルツール実行 (`examples/tools/shell.py`)
+    -   人間参加型の中断ベース承認を伴うシェルツール (`examples/tools/shell_human_in_the_loop.py`)
+    -   インラインスキルを使用するホスト型コンテナーシェル (`examples/tools/container_shell_inline_skill.py`)
+    -   スキル参照を使用するホスト型コンテナーシェル (`examples/tools/container_shell_skill_reference.py`)
+    -   ローカルスキルを使用するローカルシェル (`examples/tools/local_shell_skill.py`)
+    -   名前空間と遅延ツールを使用するツール検索 (`examples/tools/tool_search.py`)
     -   コンピュータ操作
     -   画像生成
     -   実験的な Codex ツールワークフロー (`examples/tools/codex.py`)
     -   実験的な Codex 同一スレッドワークフロー (`examples/tools/codex_same_thread.py`)
 
 -   **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
-    ストリーミング音声のコード例を含む、 TTS および STT モデルを使用した音声エージェントのコード例を確認できます。
+    OpenAI の TTS および STT モデルを使用する音声エージェントの例をご覧ください。ストリーミング音声の例も含まれます。

docs/ja/guardrails.md

@@ -4,74 +4,74 @@ search:
 ---
 # ガードレール
 
-ガードレールを使うと、ユーザー入力とエージェント出力のチェックや検証を行えます。たとえば、顧客リクエスト対応のために非常に高性能（したがって低速 / 高コスト）なモデルを使うエージェントがあるとします。悪意のあるユーザーに、そのモデルで数学の宿題を手伝わせたくはありません。そのため、高速 / 低コストなモデルでガードレールを実行できます。ガードレールが悪意のある利用を検知した場合、すぐにエラーを発生させて高コストなモデルの実行を防げます。これにより時間とコストを節約できます（ **blocking guardrails** を使う場合。並列ガードレールでは、ガードレール完了前に高コストなモデルがすでに実行を開始している可能性があります。詳細は下記の「実行モード」を参照してください）。
+ガードレールを使用すると、ユーザー入力とエージェント出力のチェックと検証を行えます。例えば、顧客リクエストの支援に非常に賢い（そのため遅く高コストな）モデルを使用するエージェントがあるとします。悪意あるユーザーが、そのモデルに数学の宿題を手伝わせることは望ましくありません。そのため、高速/低コストなモデルでガードレールを実行できます。ガードレールが悪用を検出した場合、ただちにエラーを発生させ、高コストなモデルの実行を防ぐことができ、時間とコストを節約できます（ **ブロッキングガードレールを使用している場合です。並列ガードレールでは、ガードレールが完了する前に高コストなモデルの実行がすでに開始している可能性があります。詳細は以下の「実行モード」を参照してください** ）。
 
 ガードレールには 2 種類あります。
 
-1. Input ガードレールは最初のユーザー入力で実行されます
-2. Output ガードレールは最終的なエージェント出力で実行されます
+1. 入力ガードレールは最初のユーザー入力に対して実行されます
+2. 出力ガードレールは最終的なエージェント出力に対して実行されます
 
-## ワークフロー境界
+## ワークフローの境界
 
-ガードレールはエージェントとツールにアタッチされますが、ワークフロー内の同じタイミングで実行されるわけではありません。
+ガードレールはエージェントやツールに付与されますが、ワークフロー内の同じ時点ですべてが実行されるわけではありません。
 
--   **Input ガードレール** はチェーン内の最初のエージェントに対してのみ実行されます。
--   **Output ガードレール** は最終出力を生成するエージェントに対してのみ実行されます。
--   **ツールガードレール** はカスタム関数ツールの呼び出しごとに実行され、Input ガードレールは実行前、Output ガードレールは実行後に実行されます。
+-   **入力ガードレール** は、チェーン内の最初のエージェントに対してのみ実行されます。
+-   **出力ガードレール** は、最終出力を生成するエージェントに対してのみ実行されます。
+-   **ツールガードレール** は、すべてのカスタム関数ツール呼び出しで実行されます。入力ガードレールは実行前に、出力ガードレールは実行後に実行されます。
 
-manager、ハンドオフ、または委譲された specialist を含むワークフローで、カスタム関数ツール呼び出しごとにチェックが必要な場合は、エージェントレベルの Input / Output ガードレールのみに頼るのではなく、ツールガードレールを使用してください。
+マネージャー、ハンドオフ、または委任先のスペシャリストを含むワークフローで、各カスタム関数ツール呼び出しの周囲にチェックが必要な場合は、エージェントレベルの入力/出力ガードレールだけに頼るのではなく、ツールガードレールを使用してください。
 
-## Input ガードレール
+## 入力ガードレール
 
-Input ガードレールは 3 ステップで実行されます。
+入力ガードレールは 3 ステップで実行されます。
 
 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。
 2. 次に、ガードレール関数が実行されて [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます
-3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへの適切な応答や例外処理を行えます。
+3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true であるかどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへ適切に応答したり、例外を処理したりできます。
 
 !!! Note
 
-    Input ガードレールはユーザー入力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最初* のエージェントである場合にのみ実行されます。`guardrails` プロパティが `Runner.run` に渡されるのではなくエージェント側にある理由は何か、と疑問に思うかもしれません。これは、ガードレールが実際の Agent に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。
+    入力ガードレールはユーザー入力に対して実行されることを意図しているため、エージェントのガードレールは、そのエージェントが *最初の* エージェントである場合にのみ実行されます。なぜ `guardrails` プロパティが `Runner.run` に渡されるのではなく、エージェント上にあるのか疑問に思うかもしれません。これは、ガードレールが実際のエージェントに関連することが多いためです。エージェントごとに異なるガードレールを実行することになるため、コードを同じ場所に配置すると読みやすさの面で有用です。
 
 ### 実行モード
 
-Input ガードレールは 2 つの実行モードをサポートしています。
+入力ガードレールは 2 つの実行モードをサポートします。
 
-- **並列実行**（デフォルト、`run_in_parallel=True`）: ガードレールはエージェント実行と同時に並行して実行されます。両方が同時に開始されるため、レイテンシの面で最も有利です。ただし、ガードレールが失敗した場合、キャンセルされる前にエージェントがすでにトークンを消費し、ツールを実行している可能性があります。
+- **並列実行** （デフォルト、 `run_in_parallel=True` ）: ガードレールはエージェントの実行と同時に実行されます。両方が同時に開始するため、レイテンシーの面で最良です。ただし、ガードレールが失敗した場合、キャンセルされる前にエージェントがすでにトークンを消費し、ツールを実行している可能性があります。
 
-- **ブロッキング実行**（`run_in_parallel=False`）: ガードレールはエージェント開始 *前* に実行され、完了します。ガードレールの tripwire がトリガーされた場合、エージェントは実行されないため、トークン消費とツール実行を防げます。これはコスト最適化に理想的で、ツール呼び出しによる潜在的な副作用を避けたい場合にも適しています。
+- **ブロッキング実行** （ `run_in_parallel=False` ）: ガードレールはエージェントの開始 *前に* 実行され、完了します。ガードレールのトリップワイヤーがトリガーされた場合、エージェントは一切実行されないため、トークン消費とツール実行を防げます。これは、コスト最適化や、ツール呼び出しによる潜在的な副作用を避けたい場合に最適です。
 
-## Output ガードレール
+## 出力ガードレール
 
-Output ガードレールは 3 ステップで実行されます。
+出力ガードレールは 3 ステップで実行されます。
 
-1. まず、ガードレールはエージェントが生成した出力を受け取ります。
+1. まず、ガードレールはエージェントによって生成された出力を受け取ります。
 2. 次に、ガードレール関数が実行されて [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます
-3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合は [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへの適切な応答や例外処理を行えます。
+3. 最後に、[`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true であるかどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が発生するため、ユーザーへ適切に応答したり、例外を処理したりできます。
 
 !!! Note
 
-    Output ガードレールは最終的なエージェント出力に対して実行することを想定しているため、エージェントのガードレールはそのエージェントが *最後* のエージェントである場合にのみ実行されます。Input ガードレールと同様に、これはガードレールが実際の Agent に関連することが多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するためです。
+    出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、エージェントのガードレールは、そのエージェントが *最後の* エージェントである場合にのみ実行されます。入力ガードレールと同様に、これはガードレールが実際のエージェントに関連することが多いためです。エージェントごとに異なるガードレールを実行することになるため、コードを同じ場所に配置すると読みやすさの面で有用です。
 
-    Output ガードレールは常にエージェント完了後に実行されるため、`run_in_parallel` パラメーターはサポートしていません。
+    出力ガードレールは常にエージェントの完了後に実行されるため、 `run_in_parallel` パラメーターはサポートしていません。
 
 ## ツールガードレール
 
-ツールガードレールは **function tools** をラップし、実行の前後でツール呼び出しを検証またはブロックできます。設定はツール自体に対して行い、そのツールが呼び出されるたびに実行されます。
+ツールガードレールは **関数ツール** をラップし、実行前後にツール呼び出しを検証またはブロックできるようにします。ツール自体に設定され、そのツールが呼び出されるたびに実行されます。
 
-- Input ツールガードレールはツール実行前に実行され、呼び出しをスキップする、メッセージで出力を置き換える、または tripwire を発生させることができます。
-- Output ツールガードレールはツール実行後に実行され、出力を置き換えるか、tripwire を発生させることができます。
-- ツールガードレールは [`function_tool`][agents.tool.function_tool] で作成された関数ツールにのみ適用されます。ハンドオフは通常の関数ツールパイプラインではなく SDK のハンドオフパイプラインを通るため、ツールガードレールはハンドオフ呼び出し自体には適用されません。Hosted ツール（`WebSearchTool`、`FileSearchTool`、`HostedMCPTool`、`CodeInterpreterTool`、`ImageGenerationTool`）および組み込み実行ツール（`ComputerTool`、`ShellTool`、`ApplyPatchTool`、`LocalShellTool`）もこのガードレールパイプラインを使用せず、[`Agent.as_tool()`][agents.agent.Agent.as_tool] でも現在はツールガードレールオプションを直接公開していません。
+- 入力ツールガードレールはツールの実行前に実行され、呼び出しのスキップ、出力のメッセージへの置き換え、またはトリップワイヤーの発生を行えます。
+- 出力ツールガードレールはツールの実行後に実行され、出力の置き換え、またはトリップワイヤーの発生を行えます。
+- ツールガードレールは、[`function_tool`][agents.tool.function_tool] で作成された関数ツールにのみ適用されます。ハンドオフは通常の関数ツールパイプラインではなく SDK のハンドオフパイプラインを通るため、ツールガードレールはハンドオフ呼び出し自体には適用されません。ホスト型ツール（ `WebSearchTool` 、 `FileSearchTool` 、 `HostedMCPTool` 、 `CodeInterpreterTool` 、 `ImageGenerationTool` ）や組み込み実行ツール（ `ComputerTool` 、 `ShellTool` 、 `ApplyPatchTool` 、 `LocalShellTool` ）もこのガードレールパイプラインを使用しません。また、[`Agent.as_tool()`][agents.agent.Agent.as_tool] は現在、ツールガードレールのオプションを直接公開していません。
 
 詳細は以下のコードスニペットを参照してください。
 
 ## トリップワイヤー
 
-入力または出力がガードレールに失敗した場合、Guardrail は tripwire でこれを通知できます。tripwire がトリガーされたガードレールを検知すると、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、Agent の実行を停止します。
+入力または出力がガードレールの検査に合格しない場合、ガードレールはトリップワイヤーでこれを通知できます。トリップワイヤーがトリガーされたガードレールを検出すると、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を発生させ、エージェント実行を停止します。
 
-## ガードレール実装
+## ガードレールの実装
 
-入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。この例では、内部で Agent を実行してこれを実現します。
+入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。この例では、内部でエージェントを実行することでこれを行います。
 
 ```python
 from pydantic import BaseModel
@@ -124,12 +124,12 @@ async def main():
         print("Math homework guardrail tripped")
 ```
 
-1. このエージェントをガードレール関数内で使用します。
-2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。
-3. ガードレール結果には追加情報を含められます。
+1. このエージェントをガードレール関数で使用します。
+2. これは、エージェントの入力/コンテキストを受け取り、実行結果を返すガードレール関数です。
+3. ガードレールの実行結果に追加情報を含めることができます。
 4. これはワークフローを定義する実際のエージェントです。
 
-Output ガードレールも同様です。
+出力ガードレールも同様です。
 
 ```python
 from pydantic import BaseModel
@@ -184,10 +184,10 @@ async def main():
 
 1. これは実際のエージェントの出力型です。
 2. これはガードレールの出力型です。
-3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。
+3. これは、エージェントの出力を受け取り、実行結果を返すガードレール関数です。
 4. これはワークフローを定義する実際のエージェントです。
 
-最後に、ツールガードレールの例を示します。
+最後に、ツールガードレールのコード例を示します。
 
 ```python
 import json

docs/ja/handoffs.md

@@ -4,21 +4,21 @@ search:
 ---
 # ハンドオフ
 
-ハンドオフを使うと、あるエージェントが別のエージェントにタスクを委譲できます。これは、異なるエージェントがそれぞれ異なる領域を専門にしているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、 FAQ などのタスクをそれぞれ専任で処理するエージェントを用意できます。
+ハンドオフにより、エージェントはタスクを別のエージェントに委任できます。これは、異なるエージェントが別々の領域に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリには、注文状況、返金、FAQ などのタスクをそれぞれ専門的に扱うエージェントがあるかもしれません。
 
-ハンドオフは LLM に対してツールとして表現されます。したがって、`Refund Agent` という名前のエージェントへのハンドオフがある場合、そのツール名は `transfer_to_refund_agent` になります。
+ハンドオフは LLM に対してツールとして表現されます。そのため、`Refund Agent` という名前のエージェントへのハンドオフがある場合、そのツールは `transfer_to_refund_agent` と呼ばれます。
 
 ## ハンドオフの作成
 
-すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、`Agent` を直接渡すことも、ハンドオフをカスタマイズする `Handoff` オブジェクトを渡すこともできます。
+すべてのエージェントには [`handoffs`][agents.agent.Agent.handoffs] パラメーターがあり、これは `Agent` を直接受け取ることも、ハンドオフをカスタマイズする `Handoff` オブジェクトを受け取ることもできます。
 
-プレーンな `Agent` インスタンスを渡す場合、[`handoff_description`][agents.agent.Agent.handoff_description]（設定されている場合）がデフォルトのツール説明に追記されます。これを使うと、完全な `handoff()` オブジェクトを書かなくても、どのときにそのハンドオフをモデルが選ぶべきかを示せます。
+単純な `Agent` インスタンスを渡した場合、それらの [`handoff_description`][agents.agent.Agent.handoff_description]（設定されている場合）が既定のツール説明に追加されます。完全な `handoff()` オブジェクトを書かずに、モデルがそのハンドオフを選ぶべきタイミングを示すために使用してください。
 
-Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使ってハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加えて、任意のオーバーライドや input filter を指定できます。
+Agents SDK が提供する [`handoff()`][agents.handoffs.handoff] 関数を使用して、ハンドオフを作成できます。この関数では、ハンドオフ先のエージェントに加え、省略可能なオーバーライドや入力フィルターを指定できます。
 
 ### 基本的な使い方
 
-シンプルなハンドオフは次のように作成できます。
+簡単なハンドオフは次のように作成できます。
 
 ```python
 from agents import Agent, handoff
@@ -30,22 +30,22 @@ refund_agent = Agent(name="Refund agent")
 triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
 ```
 
-1. エージェントを直接（`billing_agent` のように）使うことも、`handoff()` 関数を使うこともできます。
+1. エージェントを（`billing_agent` のように）直接使用することも、`handoff()` 関数を使用することもできます。
 
 ### `handoff()` 関数によるハンドオフのカスタマイズ
 
-[`handoff()`][agents.handoffs.handoff] 関数を使うと、さまざまなカスタマイズができます。
+[`handoff()`][agents.handoffs.handoff] 関数では、さまざまな要素をカスタマイズできます。
 
--   `agent`: ハンドオフ先のエージェントです。
--   `tool_name_override`: デフォルトでは `Handoff.default_tool_name()` 関数が使われ、`transfer_to_<agent_name>` に解決されます。これをオーバーライドできます。
--   `tool_description_override`: `Handoff.default_tool_description()` のデフォルトツール説明をオーバーライドします。
--   `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフ呼び出しが分かった時点でデータ取得を開始する、といった用途に有用です。この関数はエージェントコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御されます。
--   `input_type`: ハンドオフのツール呼び出し引数のスキーマです。設定すると、パース済みペイロードが `on_handoff` に渡されます。
+-   `agent`: 処理のハンドオフ先となるエージェントです。
+-   `tool_name_override`: 既定では `Handoff.default_tool_name()` 関数が使用され、これは `transfer_to_<agent_name>` に解決されます。これを上書きできます。
+-   `tool_description_override`: `Handoff.default_tool_description()` の既定のツール説明を上書きします。
+-   `on_handoff`: ハンドオフが呼び出されたときに実行されるコールバック関数です。ハンドオフが呼び出されることが分かった時点でデータ取得を開始する、といった用途に便利です。この関数はエージェントコンテキストを受け取り、任意で LLM が生成した入力も受け取れます。入力データは `input_type` パラメーターで制御されます。
+-   `input_type`: ハンドオフのツール呼び出し引数のスキーマです。設定されている場合、解析済みのペイロードが `on_handoff` に渡されます。
 -   `input_filter`: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記を参照してください。
--   `is_enabled`: ハンドオフを有効にするかどうかです。boolean または boolean を返す関数を指定でき、実行時に動的に有効 / 無効を切り替えられます。
--   `nest_handoff_history`: RunConfig レベルの `nest_handoff_history` 設定を呼び出し単位で上書きする任意設定です。`None` の場合、アクティブな実行設定で定義された値が代わりに使われます。
+-   `is_enabled`: ハンドオフが有効かどうかです。これはブール値、またはブール値を返す関数にできます。これにより、実行時にハンドオフを動的に有効化または無効化できます。
+-   `nest_handoff_history`: RunConfig レベルの `nest_handoff_history` 設定に対する、呼び出しごとの任意のオーバーライドです。`None` の場合、アクティブな実行設定で定義された値が代わりに使用されます。
 
-[`handoff()`][agents.handoffs.handoff] ヘルパーは、常に渡された特定の `agent` に制御を移します。遷移先候補が複数ある場合は、遷移先ごとにハンドオフを 1 つずつ登録し、モデルにその中から選ばせてください。独自のハンドオフコードが呼び出し時に返すエージェントを決定する必要がある場合にのみ、カスタム [`Handoff`][agents.handoffs.Handoff] を使用してください。
+[`handoff()`][agents.handoffs.handoff] ヘルパーは、常に渡された特定の `agent` に制御を移します。複数の宛先候補がある場合は、宛先ごとに 1 つのハンドオフを登録し、モデルにそれらの中から選ばせてください。独自のハンドオフコードが、呼び出し時にどのエージェントを返すかを決定する必要がある場合にのみ、カスタム [`Handoff`][agents.handoffs.Handoff] を使用してください。
 
 ```python
 from agents import Agent, handoff, RunContextWrapper
@@ -65,7 +65,7 @@ handoff_obj = handoff(
 
 ## ハンドオフ入力
 
-状況によっては、ハンドオフを呼び出すときに LLM にデータを渡してほしいことがあります。たとえば「Escalation agent」へのハンドオフを考えてみてください。ログに記録できるよう、理由を渡してほしい場合があります。
+状況によっては、ハンドオフを呼び出す際に LLM に何らかのデータを提供させたい場合があります。たとえば、「エスカレーションエージェント」へのハンドオフを想像してください。理由を提供させて、それをログに記録したい場合があります。
 
 ```python
 from pydantic import BaseModel
@@ -87,42 +87,42 @@ handoff_obj = handoff(
 )
 ```
 
-`input_type` は、ハンドオフツール呼び出し自体の引数を記述します。SDK はそのスキーマをハンドオフツールの `parameters` としてモデルに公開し、返された JSON をローカルで検証して、パース済みの値を `on_handoff` に渡します。
+`input_type` は、ハンドオフツール呼び出し自体の引数を記述します。SDK はそのスキーマをハンドオフツールの `parameters` としてモデルに公開し、返された JSON をローカルで検証して、解析済みの値を `on_handoff` に渡します。
 
-これは次のエージェントのメイン入力を置き換えるものではなく、遷移先を変更するものでもありません。[`handoff()`][agents.handoffs.handoff] ヘルパーは、引き続きラップした特定のエージェントへハンドオフします。また、受信側エージェントは、[`input_filter`][agents.handoffs.Handoff.input_filter] やネストされたハンドオフ履歴設定で変更しない限り、会話履歴を引き続き参照します。
+これは次のエージェントのメイン入力を置き換えるものではなく、別の宛先を選ぶものでもありません。[`handoff()`][agents.handoffs.handoff] ヘルパーは引き続き、ラップした特定のエージェントに転送し、受信側エージェントは [`input_filter`][agents.handoffs.Handoff.input_filter] またはネストされたハンドオフ履歴設定で変更しない限り、会話履歴を参照します。
 
-`input_type` は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] とも別物です。`input_type` は、ハンドオフ時にモデルが決定するメタデータに使い、ローカルですでに持っているアプリケーション状態や依存関係には使わないでください。
+`input_type` は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] とも別です。`input_type` は、ハンドオフ時にモデルが決定するメタデータに使用し、アプリケーション状態やローカルにすでにある依存関係には使用しないでください。
 
-### `input_type` を使うタイミング
+### `input_type` の使用場面
 
-ハンドオフに `reason`、`language`、`priority`、`summary` のような、モデル生成の小さなメタデータが必要な場合に `input_type` を使ってください。たとえば、トリアージエージェントは `{ "reason": "duplicate_charge", "priority": "high" }` を付けて返金エージェントへハンドオフでき、`on_handoff` は返金エージェントに制御が移る前にそのメタデータをログ化または永続化できます。
+`input_type` は、ハンドオフで `reason`、`language`、`priority`、`summary` など、モデルが生成する小さなメタデータが必要な場合に使用します。たとえば、トリアージエージェントは `{ "reason": "duplicate_charge", "priority": "high" }` を付けて返金エージェントにハンドオフでき、`on_handoff` は返金エージェントが引き継ぐ前にそのメタデータをログに記録したり永続化したりできます。
 
-目的が異なる場合は、別の仕組みを選んでください。
+目的が異なる場合は、別の仕組みを選択してください。
 
--   既存のアプリケーション状態と依存関係は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] に入れてください。[context ガイド](context.md)を参照してください。
--   受信側エージェントが見る履歴を変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]、または [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] を使ってください。
--   複数の専門エージェントが候補にある場合は、遷移先ごとにハンドオフを 1 つずつ登録してください。`input_type` は選ばれたハンドオフにメタデータを追加できますが、遷移先の振り分けはしません。
--   会話を転送せずにネストされた専門エージェント向けの構造化入力が欲しい場合は、[`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool] を優先してください。[tools](tools.md#structured-input-for-tool-agents)を参照してください。
+-   既存のアプリケーション状態と依存関係は [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context] に入れてください。[コンテキストガイド](context.md) を参照してください。
+-   受信側エージェントが参照する履歴を変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter]、[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]、または [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] を使用してください。
+-   複数の専門エージェント候補がある場合は、宛先ごとに 1 つのハンドオフを登録してください。`input_type` は選択されたハンドオフにメタデータを追加できますが、宛先間の振り分けは行いません。
+-   会話を転送せずにネストされた専門エージェントへ構造化入力を渡したい場合は、[`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool] を優先してください。[ツール](tools.md#structured-input-for-tool-agents)を参照してください。
 
-## input filter
+## 入力フィルター
 
-ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を参照できる状態になります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。input filter は、既存入力を [`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で受け取り、新しい `HandoffInputData` を返す関数です。
+ハンドオフが発生すると、新しいエージェントが会話を引き継いだかのように、以前の会話履歴全体を参照できるようになります。これを変更したい場合は、[`input_filter`][agents.handoffs.Handoff.input_filter] を設定できます。入力フィルターは、[`HandoffInputData`][agents.handoffs.HandoffInputData] 経由で既存の入力を受け取り、新しい `HandoffInputData` を返す必要がある関数です。
 
 [`HandoffInputData`][agents.handoffs.HandoffInputData] には次が含まれます。
 
--   `input_history`: `Runner.run(...)` 開始前の入力履歴。
--   `pre_handoff_items`: ハンドオフが呼び出されたエージェントターンより前に生成されたアイテム。
--   `new_items`: 現在のターン中に生成されたアイテム（ハンドオフ呼び出しとハンドオフ出力アイテムを含む）。
--   `input_items`: `new_items` の代わりに次のエージェントへ渡す任意のアイテム。これにより、セッション履歴用に `new_items` を保ったまま、モデル入力をフィルタリングできます。
--   `run_context`: ハンドオフ呼び出し時点でアクティブな [`RunContextWrapper`][agents.run_context.RunContextWrapper]。
+-   `input_history`: `Runner.run(...)` が開始される前の入力履歴です。
+-   `pre_handoff_items`: ハンドオフが呼び出されたエージェントターンの前に生成された項目です。
+-   `new_items`: 現在のターン中に生成された項目です。ハンドオフ呼び出しとハンドオフ出力項目を含みます。
+-   `input_items`: `new_items` の代わりに次のエージェントへ転送する任意の項目です。`new_items` をセッション履歴用にそのまま保持しながら、モデル入力をフィルタリングできます。
+-   `run_context`: ハンドオフが呼び出された時点でアクティブな [`RunContextWrapper`][agents.run_context.RunContextWrapper] です。
 
-ネストされたハンドオフは opt-in のベータとして提供されており、安定化のためデフォルトでは無効です。[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を有効にすると、runner はそれまでの transcript を 1 つの assistant 要約メッセージに折りたたみ、同一 run 中に複数のハンドオフが起きると新しいターンが追記され続ける `<CONVERSATION HISTORY>` ブロックに包みます。完全な `input_filter` を書かずに生成メッセージを置き換えたい場合は、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] で独自のマッピング関数を渡せます。この opt-in は、ハンドオフ側と run 側のいずれも明示的な `input_filter` を指定していない場合にのみ適用されるため、すでにペイロードをカスタマイズしている既存コード（このリポジトリのコード例を含む）は変更なしで現在の挙動を維持します。[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡すことで、単一ハンドオフのネスト挙動を上書きできます（これは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を設定します）。生成要約のラッパーテキストだけを変更したい場合は、エージェント実行前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。
+ネストされたハンドオフはオプトインのベータとして利用可能で、安定化中のため既定では無効です。[`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] を有効にすると、ランナーはそれまでのトランスクリプトを単一の assistant 要約メッセージにまとめ、それを `<CONVERSATION HISTORY>` ブロックでラップします。このブロックには、同じ実行中に複数のハンドオフが発生した場合、新しいターンが追加され続けます。完全な `input_filter` を書かずに生成されたメッセージを置き換えるには、[`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] 経由で独自のマッピング関数を提供できます。このオプトインは、ハンドオフと実行のどちらも明示的な `input_filter` を提供していない場合にのみ適用されるため、すでにペイロードをカスタマイズしている既存のコード（このリポジトリのコード例を含む）は、変更なしで現在の動作を維持します。単一のハンドオフについてネスト動作を上書きするには、[`handoff(...)`][agents.handoffs.handoff] に `nest_handoff_history=True` または `False` を渡します。これにより [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] が設定されます。生成された要約のラッパーテキストを変更するだけでよい場合は、エージェントを実行する前に [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（および必要に応じて [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出してください。
 
-ハンドオフ側とアクティブな [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] の両方でフィルターが定義されている場合、その特定ハンドオフではハンドオフ単位の [`input_filter`][agents.handoffs.Handoff.input_filter] が優先されます。
+ハンドオフとアクティブな [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] の両方でフィルターが定義されている場合、その特定のハンドオフでは、ハンドオフごとの [`input_filter`][agents.handoffs.Handoff.input_filter] が優先されます。
 
 !!! note
 
-    ハンドオフは単一の run 内に留まります。入力ガードレールは依然としてチェーン内の最初のエージェントにのみ適用され、出力ガードレールは最終出力を生成するエージェントにのみ適用されます。ワークフロー内の各カスタム function-tool 呼び出しごとにチェックが必要な場合は、ツールガードレールを使用してください。
+    ハンドオフは単一の実行内に留まります。入力ガードレールは引き続きチェーン内の最初のエージェントにのみ適用され、出力ガードレールは最終出力を生成するエージェントにのみ適用されます。ワークフロー内の各カスタム関数ツール呼び出しの周辺でチェックが必要な場合は、ツールガードレールを使用してください。
 
 一般的なパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、[`agents.extensions.handoff_filters`][] に実装されています。
 
@@ -138,11 +138,11 @@ handoff_obj = handoff(
 )
 ```
 
-1. これにより、`FAQ agent` が呼び出されたときに履歴からすべてのツールが自動的に削除されます。
+1. これにより、`FAQ agent` が呼び出されたときに、履歴からすべてのツールが自動的に削除されます。
 
 ## 推奨プロンプト
 
-LLM がハンドオフを適切に理解できるように、エージェントにハンドオフ情報を含めることを推奨します。[`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に推奨プレフィックスがあり、または [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動追加できます。
+LLM がハンドオフを適切に理解できるように、エージェントにハンドオフに関する情報を含めることをおすすめします。推奨プレフィックスは [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][] に用意されています。または、[`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] を呼び出して、推奨データをプロンプトに自動的に追加できます。
 
 ```python
 from agents import Agent

docs/ja/human_in_the_loop.md

@@ -2,19 +2,19 @@
 search:
   exclude: true
 ---
-# Human-in-the-loop
+# ヒューマンインザループ
 
-human-in-the-loop ( HITL ) フローを使用すると、機密性の高いツール呼び出しを人が承認または拒否するまで、エージェント実行を一時停止できます。ツールは承認が必要なタイミングを宣言し、実行結果は保留中の承認を中断として表示し、`RunState` によって判断後に実行をシリアライズおよび再開できます。
+human-in-the-loop (HITL) フローを使用すると、機密性の高いツール呼び出しが人によって承認または拒否されるまで、エージェントの実行を一時停止できます。ツールは承認が必要なタイミングを宣言し、実行結果は保留中の承認を中断として表面化し、`RunState` によって判断後の実行をシリアライズして再開できます。
 
-この承認サーフェスは実行全体に適用され、現在のトップレベルエージェントに限定されません。同じパターンは、ツールが現在のエージェントに属する場合、ハンドオフで到達したエージェントに属する場合、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に属する場合にも適用されます。ネストされた `Agent.as_tool()` の場合でも、中断は外側の実行に表示されるため、外側の `RunState` で承認または拒否し、元のトップレベル実行を再開します。
+この承認が表面化する範囲は実行全体であり、現在のトップレベルエージェントに限定されません。同じパターンは、ツールが現在のエージェントに属する場合、ハンドオフで到達したエージェントに属する場合、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に属する場合にも適用されます。ネストされた `Agent.as_tool()` の場合でも、中断は外側の実行に表面化するため、外側の `RunState` で承認または拒否し、元のトップレベル実行を再開します。
 
-`Agent.as_tool()` では、承認は 2 つの異なるレイヤーで発生する可能性があります。エージェントツール自体が `Agent.as_tool(..., needs_approval=...)` によって承認を要求でき、さらにネストされたエージェント内のツールがネスト実行開始後に独自の承認を発生させることもできます。どちらも同じ外側実行の中断フローで処理されます。
+`Agent.as_tool()` では、承認は 2 つの異なる層で発生することがあります。エージェントツール自体が `Agent.as_tool(..., needs_approval=...)` によって承認を必要とする場合があり、ネストされたエージェント内のツールが、ネストされた実行の開始後に独自の承認を要求する場合もあります。どちらも同じ外側の実行の中断フローで処理されます。
 
-このページでは、`interruptions` を介した手動承認フローに焦点を当てます。アプリがコードで判断できる場合、一部のツールタイプはプログラムによる承認コールバックもサポートしており、実行を一時停止せずに継続できます。
+このページでは、`interruptions` による手動承認フローに焦点を当てます。アプリがコード内で判断できる場合、一部のツールタイプはプログラムによる承認コールバックもサポートしているため、一時停止せずに実行を継続できます。
 
-## 承認が必要なツールのマーキング
+## 承認が必要なツールのマーク付け
 
-`needs_approval` を `True` に設定すると常に承認が必要になり、呼び出しごとに判断する非同期関数を渡すこともできます。呼び出し可能オブジェクトは、実行コンテキスト、解析済みツールパラメーター、ツール呼び出し ID を受け取ります。
+常に承認を必須にするには `needs_approval` を `True` に設定し、呼び出しごとに判断するには async 関数を指定します。この呼び出し可能オブジェクトは、実行コンテキスト、解析済みのツールパラメーター、ツール呼び出し ID を受け取ります。
 
 ```python
 from agents import Agent, Runner, function_tool
@@ -41,28 +41,28 @@ agent = Agent(
 )
 ```
 
-`needs_approval` は [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool]、[`ApplyPatchTool`][agents.tool.ApplyPatchTool] で利用できます。ローカル MCP サーバーも、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の `require_approval` を通じて承認をサポートします。ホスト型 MCP サーバーは、[`HostedMCPTool`][agents.tool.HostedMCPTool] の `tool_config={"require_approval": "always"}` と、任意の `on_approval_request` コールバックを介して承認をサポートします。 shell および apply_patch ツールは、割り込みを表示せずに自動承認または自動拒否したい場合に `on_approval` コールバックを受け付けます。
+`needs_approval` は [`function_tool`][agents.tool.function_tool]、[`Agent.as_tool`][agents.agent.Agent.as_tool]、[`ShellTool`][agents.tool.ShellTool]、[`ApplyPatchTool`][agents.tool.ApplyPatchTool] で利用できます。ローカル MCP サーバーも、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio]、[`MCPServerSse`][agents.mcp.server.MCPServerSse]、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] の `require_approval` によって承認をサポートします。ホスト型 MCP サーバーは、`tool_config={"require_approval": "always"}` と任意の `on_approval_request` コールバックを指定した [`HostedMCPTool`][agents.tool.HostedMCPTool] によって承認をサポートします。シェルツールと apply_patch ツールは、中断を表面化させずに自動承認または自動拒否したい場合に、`on_approval` コールバックを受け付けます。
 
 ## 承認フローの仕組み
 
-1. モデルがツール呼び出しを出力すると、ランナーはその承認ルール (`needs_approval`、`require_approval`、またはホスト型 MCP の同等機能) を評価します。
-2. そのツール呼び出しに対する承認判断がすでに [`RunContextWrapper`][agents.run_context.RunContextWrapper] に保存されている場合、ランナーは確認なしで続行します。呼び出し単位の承認は特定の呼び出し ID にスコープされます。実行の残り期間における同ツールへの今後の呼び出しにも同じ判断を保持するには、`always_approve=True` または `always_reject=True` を渡します。
-3. それ以外の場合、実行は一時停止し、`RunResult.interruptions` (または `RunResultStreaming.interruptions`) に `agent.name`、`tool_name`、`arguments` などの詳細を含む [`ToolApprovalItem`][agents.items.ToolApprovalItem] エントリーが入ります。これには、ハンドオフ後またはネストされた `Agent.as_tool()` 実行内で発生した承認も含まれます。
-4. `result.to_state()` で結果を `RunState` に変換し、`state.approve(...)` または `state.reject(...)` を呼び出した後、`Runner.run(agent, state)` または `Runner.run_streamed(agent, state)` で再開します。ここで `agent` は、その実行の元のトップレベルエージェントです。
-5. 再開された実行は中断地点から継続し、新たな承認が必要であればこのフローに再度入ります。
+1. モデルがツール呼び出しを生成すると、ランナーはその承認ルール（`needs_approval`、`require_approval`、またはホスト型 MCP の同等設定）を評価します。
+2. そのツール呼び出しに対する承認判断がすでに [`RunContextWrapper`][agents.run_context.RunContextWrapper] に保存されている場合、ランナーはプロンプトを表示せずに続行します。呼び出しごとの承認は特定の呼び出し ID にスコープされます。実行の残りの期間におけるそのツールへの今後の呼び出しにも同じ判断を保持するには、`always_approve=True` または `always_reject=True` を渡します。
+3. それ以外の場合、実行は一時停止し、`RunResult.interruptions`（または `RunResultStreaming.interruptions`）に、`agent.name`、`tool_name`、`arguments` などの詳細を含む [`ToolApprovalItem`][agents.items.ToolApprovalItem] エントリが含まれます。これには、ハンドオフ後、またはネストされた `Agent.as_tool()` 実行内で要求された承認も含まれます。
+4. `result.to_state()` で実行結果を `RunState` に変換し、`state.approve(...)` または `state.reject(...)` を呼び出してから、`Runner.run(agent, state)` または `Runner.run_streamed(agent, state)` で再開します。ここで `agent` は、その実行の元のトップレベルエージェントです。
+5. 再開された実行は中断した箇所から続行し、新しい承認が必要になった場合はこのフローに再び入ります。
 
-`always_approve=True` または `always_reject=True` で作成された固定判断は実行状態に保存されるため、同じ一時停止済み実行を後で再開する際に `state.to_string()` / `RunState.from_string(...)` および `state.to_json()` / `RunState.from_json(...)` をまたいで保持されます。
+`always_approve=True` または `always_reject=True` で作成された固定的な判断は実行状態に保存されるため、後で同じ一時停止中の実行を再開する際に、`state.to_string()` / `RunState.from_string(...)` や `state.to_json()` / `RunState.from_json(...)` を経ても保持されます。
 
-同じパスで保留中の承認をすべて解決する必要はありません。`interruptions` には、通常の関数ツール、ホスト型 MCP 承認、ネストされた `Agent.as_tool()` 承認が混在する可能性があります。一部の項目のみ承認または拒否して再実行した場合、解決済みの呼び出しは継続し、未解決のものは `interruptions` に残って実行を再び一時停止します。
+同じパスで保留中の承認をすべて解決する必要はありません。`interruptions` には、通常の関数ツール、ホスト型 MCP 承認、ネストされた `Agent.as_tool()` 承認が混在する場合があります。一部の項目だけを承認または拒否してから再実行すると、解決済みの呼び出しは続行できますが、未解決のものは `interruptions` に残り、実行を再び一時停止します。
 
-## 拒否メッセージのカスタマイズ
+## カスタム拒否メッセージ
 
-デフォルトでは、拒否されたツール呼び出しは SDK の標準拒否テキストを実行に返します。このメッセージは 2 つのレイヤーでカスタマイズできます。
+デフォルトでは、拒否されたツール呼び出しは SDK の標準拒否テキストを実行内に返します。このメッセージは 2 つの層でカスタマイズできます。
 
--   実行全体のフォールバック: [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter] を設定し、実行全体の承認拒否に対するモデル可視のデフォルトメッセージを制御します。
--   呼び出し単位の上書き: 特定の拒否ツール呼び出しだけ別メッセージを表示したい場合、`state.reject(...)` に `rejection_message=...` を渡します。
+-   実行全体のフォールバック: 実行全体にわたる承認拒否について、モデルから見えるデフォルトメッセージを制御するには、[`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter] を設定します。
+-   呼び出しごとの上書き: 特定の拒否されたツール呼び出しで別のメッセージを表面化させたい場合は、`state.reject(...)` に `rejection_message=...` を渡します。
 
-両方が指定された場合、呼び出し単位の `rejection_message` が実行全体フォーマッターより優先されます。
+両方が指定された場合は、呼び出しごとの `rejection_message` が実行全体のフォーマッターより優先されます。
 
 ```python
 from agents import RunConfig, ToolErrorFormatterArgs
@@ -83,27 +83,27 @@ state.reject(
 )
 ```
 
-両レイヤーを組み合わせて示す完全な例は [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py) を参照してください。
+両方の層を組み合わせて示す完全な例については、[`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py) を参照してください。
 
 ## 自動承認判断
 
-手動 `interruptions` は最も汎用的なパターンですが、唯一ではありません。
+手動の `interruptions` は最も一般的なパターンですが、それだけではありません。
 
--   ローカル [`ShellTool`][agents.tool.ShellTool] と [`ApplyPatchTool`][agents.tool.ApplyPatchTool] は `on_approval` を使用してコード内で即時に承認または拒否できます。
--   [`HostedMCPTool`][agents.tool.HostedMCPTool] は、同種のプログラムによる判断のために `tool_config={"require_approval": "always"}` と `on_approval_request` を併用できます。
+-   ローカルの [`ShellTool`][agents.tool.ShellTool] と [`ApplyPatchTool`][agents.tool.ApplyPatchTool] は、`on_approval` を使用してコード内で即座に承認または拒否できます。
+-   [`HostedMCPTool`][agents.tool.HostedMCPTool] は、`tool_config={"require_approval": "always"}` と `on_approval_request` を組み合わせて使用することで、同じ種類のプログラムによる判断を行えます。
 -   通常の [`function_tool`][agents.tool.function_tool] ツールと [`Agent.as_tool()`][agents.agent.Agent.as_tool] は、このページの手動中断フローを使用します。
 
-これらのコールバックが判断を返すと、実行は人の応答を待って一時停止せずに継続します。 Realtime および音声セッション API については、[Realtime ガイド](realtime/guide.md) の承認フローを参照してください。
+これらのコールバックが判断を返すと、実行は人間の応答を待って一時停止せずに続行します。Realtime と音声セッション API については、[Realtime ガイド](realtime/guide.md)の承認フローを参照してください。
 
 ## ストリーミングとセッション
 
-同じ中断フローはストリーミング実行でも機能します。ストリーミング実行が一時停止したら、イテレーターが終了するまで [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events] を消費し、[`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] を確認して解決し、再開後の出力もストリーミングを継続したい場合は [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] で再開します。このパターンのストリーミング版は [ストリーミング](streaming.md) を参照してください。
+同じ中断フローはストリーミング実行でも機能します。ストリーミング実行が一時停止した後は、イテレーターが終了するまで [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events] を消費し続け、[`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] を確認し、それらを解決して、再開後の出力もストリーミングし続けたい場合は [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed] で再開します。このパターンのストリーミング版については、[ストリーミング](streaming.md)を参照してください。
 
-セッションも使用している場合は、`RunState` から再開する際に同じセッションインスタンスを渡し続けるか、同じバックエンドストアを指す別のセッションオブジェクトを渡してください。再開されたターンは同じ保存済み会話履歴に追加されます。セッションライフサイクルの詳細は [セッション](sessions/index.md) を参照してください。
+セッションも使用している場合は、`RunState` から再開するときに同じセッションインスタンスを渡し続けるか、同じバックエンドストアを指す別のセッションオブジェクトを渡します。これにより、再開されたターンは同じ保存済み会話履歴に追加されます。セッションのライフサイクルの詳細については、[セッション](sessions/index.md)を参照してください。
 
 ## 例: 一時停止、承認、再開
 
-以下のスニペットは JavaScript の HITL ガイドを踏襲しています。ツールに承認が必要なときに一時停止し、状態をディスクに保存し、再読み込みして、判断を収集した後に再開します。
+以下のスニペットは JavaScript HITL ガイドに対応するものです。ツールが承認を必要とすると一時停止し、状態をディスクに永続化し、再読み込みして、判断を収集した後に再開します。
 
 ```python
 import asyncio
@@ -167,43 +167,42 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-この例では、`prompt_approval` は `input()` を使用し `run_in_executor(...)` で実行されるため同期的です。承認ソースがすでに非同期 ( 例: HTTP リクエストや非同期データベースクエリ) の場合は、`async def` 関数を使用して直接 `await` できます。
+この例では、`prompt_approval` は `input()` を使用し、`run_in_executor(...)` で実行されるため同期的です。承認元がすでに非同期である場合（たとえば、HTTP リクエストや async データベースクエリ）、代わりに `async def` 関数を使用して直接 `await` できます。
 
-承認待ち中にも出力をストリーミングしたい場合は、`Runner.run_streamed` を呼び出し、完了まで `result.stream_events()` を消費し、その後は上記と同じ `result.to_state()` と再開手順に従ってください。
+承認待ちの間に出力をストリーミングするには、`Runner.run_streamed` を呼び出し、完了するまで `result.stream_events()` を消費してから、上記と同じ `result.to_state()` と再開手順に従います。
 
-## リポジトリのパターンと例
+## リポジトリのパターンとコード例
 
-- **ストリーミング承認**: `examples/agent_patterns/human_in_the_loop_stream.py` は、`stream_events()` を最後まで処理し、保留中ツール呼び出しを承認してから `Runner.run_streamed(agent, state)` で再開する方法を示します。
-- **カスタム拒否テキスト**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py` は、承認が拒否されたときに実行レベルの `tool_error_formatter` と呼び出し単位の `rejection_message` 上書きを組み合わせる方法を示します。
-- **Agent as tool 承認**: `Agent.as_tool(..., needs_approval=...)` は、委譲されたエージェントタスクにレビューが必要な場合にも同じ中断フローを適用します。ネストされた中断も外側の実行に表示されるため、ネスト側ではなく元のトップレベルエージェントを再開してください。
-- **ローカル shell / apply_patch ツール**: `ShellTool` と `ApplyPatchTool` も `needs_approval` をサポートします。将来の呼び出しのために判断をキャッシュするには `state.approve(interruption, always_approve=True)` または `state.reject(..., always_reject=True)` を使用します。自動判断には `on_approval` を指定します ( `examples/tools/shell.py` を参照)。手動判断には中断を処理します ( `examples/tools/shell_human_in_the_loop.py` を参照)。ホスト型 shell 環境は `needs_approval` または `on_approval` をサポートしません。[ツールガイド](tools.md) を参照してください。
-- **ローカル MCP サーバー**: `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` で `require_approval` を使用し、MCP ツール呼び出しを制御します ( `examples/mcp/get_all_mcp_tools_example/main.py` および `examples/mcp/tool_filter_example/main.py` を参照)。
-- **ホスト型 MCP サーバー**: HITL を強制するには `HostedMCPTool` で `require_approval` を `"always"` に設定し、必要に応じて `on_approval_request` を指定して自動承認または拒否します ( `examples/hosted_mcp/human_in_the_loop.py` および `examples/hosted_mcp/on_approval.py` を参照)。信頼済みサーバーには `"never"` を使用します (`examples/hosted_mcp/simple.py`)。
-- **セッションとメモリ**: 複数ターンにわたり承認と会話履歴を保持するには `Runner.run` にセッションを渡します。 SQLite および OpenAI Conversations セッションのバリアントは `examples/memory/memory_session_hitl_example.py` と `examples/memory/openai_session_hitl_example.py` にあります。
-- **Realtime エージェント**: realtime デモは `RealtimeSession` の `approve_tool_call` / `reject_tool_call` を介してツール呼び出しを承認または拒否する WebSocket メッセージを公開します ( サーバー側ハンドラーは `examples/realtime/app/server.py`、API サーフェスは [Realtime ガイド](realtime/guide.md#tool-approvals) を参照)。
+- **ストリーミング承認**: `examples/agent_patterns/human_in_the_loop_stream.py` は、`stream_events()` を最後まで消費し、その後に保留中のツール呼び出しを承認してから `Runner.run_streamed(agent, state)` で再開する方法を示しています。
+- **カスタム拒否テキスト**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py` は、承認が拒否されたときに、実行レベルの `tool_error_formatter` と呼び出しごとの `rejection_message` 上書きを組み合わせる方法を示しています。
+- **ツールとしてのエージェントの承認**: `Agent.as_tool(..., needs_approval=...)` は、委任されたエージェントタスクにレビューが必要な場合に、同じ中断フローを適用します。ネストされた中断も外側の実行に表面化するため、ネストされたエージェントではなく、元のトップレベルエージェントを再開します。
+- **ローカルシェルと apply_patch ツール**: `ShellTool` と `ApplyPatchTool` も `needs_approval` をサポートします。今後の呼び出しに対して判断をキャッシュするには、`state.approve(interruption, always_approve=True)` または `state.reject(..., always_reject=True)` を使用します。自動判断には `on_approval` を指定します（`examples/tools/shell.py` を参照）。手動判断には中断を処理します（`examples/tools/shell_human_in_the_loop.py` を参照）。ホスト型シェル環境は `needs_approval` または `on_approval` をサポートしていません。[ツールガイド](tools.md)を参照してください。
+- **ローカル MCP サーバー**: MCP ツール呼び出しを制御するには、`MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` で `require_approval` を使用します（`examples/mcp/get_all_mcp_tools_example/main.py` と `examples/mcp/tool_filter_example/main.py` を参照）。
+- **ホスト型 MCP サーバー**: HITL を強制するには、`HostedMCPTool` で `require_approval` を `"always"` に設定し、必要に応じて自動承認または拒否のために `on_approval_request` を指定します（`examples/hosted_mcp/human_in_the_loop.py` と `examples/hosted_mcp/on_approval.py` を参照）。信頼できるサーバーには `"never"` を使用します（`examples/hosted_mcp/simple.py`）。
+- **セッションとメモリ**: 承認と会話履歴が複数ターンにわたって保持されるように、`Runner.run` にセッションを渡します。SQLite と OpenAI Conversations セッションのバリエーションは、`examples/memory/memory_session_hitl_example.py` と `examples/memory/openai_session_hitl_example.py` にあります。
+- **Realtime エージェント**: Realtime デモは、`RealtimeSession` 上の `approve_tool_call` / `reject_tool_call` を介してツール呼び出しを承認または拒否する WebSocket メッセージを公開しています（サーバー側ハンドラーについては `examples/realtime/app/server.py`、API サーフェスについては [Realtime ガイド](realtime/guide.md#tool-approvals)を参照）。
 
-## 長時間実行承認
+## 長時間にわたる承認
 
-`RunState` は永続性を考慮して設計されています。保留中作業をデータベースやキューに保存するには `state.to_json()` または `state.to_string()` を使用し、後で `RunState.from_json(...)` または `RunState.from_string(...)` で再作成します。
+`RunState` は耐久性を持つように設計されています。保留中の作業をデータベースまたはキューに保存するには `state.to_json()` または `state.to_string()` を使用し、後で `RunState.from_json(...)` または `RunState.from_string(...)` で再作成します。
 
 有用なシリアライズオプション:
 
--   `context_serializer`: マッピング以外のコンテキストオブジェクトをどのようにシリアライズするかをカスタマイズします。
--   `context_deserializer`: `RunState.from_json(...)` または `RunState.from_string(...)` で状態をロードするときに、マッピング以外のコンテキストオブジェクトを再構築します。
+-   `context_serializer`: 非マッピングのコンテキストオブジェクトをシリアライズする方法をカスタマイズします。
+-   `context_deserializer`: `RunState.from_json(...)` または `RunState.from_string(...)` で状態を読み込むときに、非マッピングのコンテキストオブジェクトを再構築します。
 -   `strict_context=True`: コンテキストがすでに
-    マッピングであるか、適切な serializer / deserializer を提供しない限り、シリアライズまたはデシリアライズを失敗させます。
--   `context_override`: 状態ロード時にシリアライズ済みコンテキストを置き換えます。これは
-    元のコンテキストオブジェクトを復元したくない場合に有用ですが、すでに
-    シリアライズ済みペイロードからそのコンテキストを削除するものではありません。
--   `include_tracing_api_key=True`: 再開作業でも同じ認証情報でトレースをエクスポートし続ける必要がある場合に、
-    シリアライズされたトレースペイロードに tracing API キーを含めます。
+    マッピングであるか、適切なシリアライザー/デシリアライザーを指定している場合を除き、シリアライズまたはデシリアライズを失敗させます。
+-   `context_override`: 状態を読み込むときに、シリアライズされたコンテキストを置き換えます。これは、元のコンテキストオブジェクトを復元したくない場合に便利ですが、
+    すでにシリアライズされたペイロードからそのコンテキストを削除するわけではありません。
+-   `include_tracing_api_key=True`: 同じ認証情報でトレースのエクスポートを継続するために再開後の作業で必要な場合、
+    シリアライズされたトレースペイロードにトレーシング API キーを含めます。
 
-シリアライズされた実行状態には、アプリコンテキストに加えて、承認、
-使用量、シリアライズされた `tool_input`、ネストされた agent-as-tool 再開、トレースメタデータ、サーバー管理の
-会話設定など、SDK 管理の実行時メタデータが含まれます。シリアライズ状態を保存または転送する予定がある場合は、
-`RunContextWrapper.context` を永続化データとして扱い、意図的に
-状態と一緒に移動させたい場合を除き、そこに秘密情報を置かないでください。
+シリアライズされた実行状態には、アプリのコンテキストに加えて、承認、
+使用量、シリアライズされた `tool_input`、ネストされた agent-as-tool の再開、トレースメタデータ、サーバー管理の
+会話設定など、SDK が管理するランタイムメタデータが含まれます。シリアライズされた状態を保存または送信する予定がある場合は、
+`RunContextWrapper.context` を永続化データとして扱い、状態と一緒に移動することを意図している場合を除き、
+そこにシークレットを置かないでください。
 
-## 保留タスクのバージョニング
+## 保留中タスクのバージョニング
 
-承認がしばらく保留される可能性がある場合は、シリアライズ状態と一緒にエージェント定義または SDK のバージョンマーカーを保存してください。これにより、デシリアライズを対応するコードパスに振り分け、モデル、プロンプト、またはツール定義が変更された際の非互換性を回避できます。
+承認がしばらく保留状態のままになる可能性がある場合は、シリアライズされた状態と一緒に、エージェント定義または SDK のバージョンマーカーを保存してください。そうすれば、モデル、プロンプト、ツール定義が変更されたときの非互換性を避けるために、デシリアライズを対応するコードパスにルーティングできます。

docs/ja/index.md

@@ -4,51 +4,51 @@ search:
 ---
 # OpenAI Agents SDK
 
-[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) を使うと、ごく少数の抽象化だけを備えた軽量で使いやすいパッケージで、エージェント型 AI アプリを構築できます。これは、以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番対応に進化させたものです。Agents SDK には、ごく少数の基本コンポーネントがあります。
+[OpenAI Agents SDK](https://github.com/openai/openai-agents-python) は、抽象化をほとんど持たない軽量で使いやすいパッケージで、エージェント型 AI アプリを構築できるようにします。これは、以前のエージェント向け実験プロジェクトである [Swarm](https://github.com/openai/swarm/tree/main) を本番環境対応に発展させたものです。Agents SDK は、非常に少数の基本コンポーネントで構成されています:
 
--   **エージェント**。instructions と tools を備えた LLM です
--   **Agents as tools / ハンドオフ**。特定のタスクについて、エージェントがほかのエージェントに委任できるようにします
--   **ガードレール**。エージェントの入力と出力の検証を可能にします
+-   **エージェント**: 指示とツールを備えた LLM です
+-   **Agents as tools / ハンドオフ**: エージェントが特定のタスクを他のエージェントに委任できるようにします
+-   **ガードレール**: エージェントの入力と出力の検証を可能にします
 
-これらの基本コンポーネントは Python と組み合わせることで、ツールとエージェントの複雑な関係を表現するのに十分な力を発揮し、学習コストを大きくかけることなく実運用のアプリケーションを構築できます。さらに、この SDK には組み込みの **トレーシング** があり、エージェントフローの可視化やデバッグに加えて、評価や、アプリケーション向けのモデルのファインチューニングまで行えます。
+Python と組み合わせることで、これらの基本コンポーネントは、ツールとエージェント間の複雑な関係を表現するのに十分強力であり、習得のハードルを高くすることなく実世界のアプリケーションを構築できます。さらに、SDK には組み込みの **トレーシング** が含まれており、エージェント型フローの可視化とデバッグ、評価、さらにはアプリケーション向けのモデルのファインチューニングも可能です。
 
-## Agents SDK を使う理由
+## Agents SDK の利用理由
 
-この SDK には、設計上の主要な原則が 2 つあります。
+SDK の設計を支える原則は 2 つあります:
 
-1. 使う価値があるだけの十分な機能を備えつつ、素早く学べるよう基本コンポーネントは少数にとどめること。
-2. そのままですぐに使えて、しかも何が起きるかを正確にカスタマイズできること。
+1. 使用する価値がある十分な機能を備えつつ、すばやく学べるだけの少数の基本コンポーネントに抑えること。
+2. そのままでも優れた動作をしつつ、何が起こるかを正確にカスタマイズできること。
 
-以下は、この SDK の主な機能です。
+SDK の主な機能は次のとおりです:
 
--   **エージェントループ**: ツール呼び出しを処理し、結果を LLM に返し、タスクが完了するまで継続する組み込みのエージェントループです。
--   **Python ファースト**: 新しい抽象化を学ぶ必要はなく、組み込みの言語機能を使ってエージェントオーケストレーションや連携を行えます。
--   **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整および委任するための強力な仕組みです。
--   **Sandbox エージェント**: manifest で定義されたファイル、sandbox client の選択、再開可能な sandbox session を備えた、実際に分離されたワークスペース内で専門エージェントを実行します。
--   **ガードレール**: エージェントの実行と並行して入力検証と安全性チェックを実行し、チェックに通らなかった場合は即座に失敗させます。
--   **関数ツール**: 自動スキーマ生成と Pydantic ベースの検証により、任意の Python 関数をツールに変換します。
--   **MCP サーバーツール呼び出し**: 関数ツールと同じ方法で動作する、組み込みの MCP サーバーツール統合です。
+-   **エージェントループ**: ツール呼び出しを処理し、結果を LLM に送り返し、タスクが完了するまで継続する組み込みのエージェントループです。
+-   **Python ファースト**: 新しい抽象化を学ぶ必要なく、組み込みの言語機能を使ってエージェントをオーケストレーションし、連鎖させます。
+-   **Agents as tools / ハンドオフ**: 複数のエージェント間で作業を調整し、委任するための強力な仕組みです。
+-   **Sandbox エージェント**: マニフェストで定義されたファイル、Sandbox クライアントの選択、再開可能なサンドボックスセッションを備えた、実際の隔離ワークスペース内で専門エージェントを実行します。
+-   **ガードレール**: エージェント実行と並行して入力検証と安全性チェックを実行し、チェックに通らない場合は即座に失敗として終了します。
+-   **関数ツール**: スキーマの自動生成と Pydantic によるバリデーションにより、任意の Python 関数をツールに変換します。
+-   **MCP サーバーのツール呼び出し**: 関数ツールと同じように動作する、組み込みの MCP サーバーツール統合です。
 -   **セッション**: エージェントループ内で作業コンテキストを維持するための永続的なメモリレイヤーです。
--   **Human in the loop**: エージェント実行全体で人間を関与させるための組み込みの仕組みです。
--   **トレーシング**: ワークフローの可視化、デバッグ、監視のための組み込みトレーシングで、OpenAI の評価、ファインチューニング、蒸留ツール群をサポートします。
--   **Realtime Agents**: `gpt-realtime-1.5`、自動割り込み検出、コンテキスト管理、ガードレールなどを使用して、強力な音声エージェントを構築できます。
+-   **ヒューマンインザループ**: エージェント実行の各所に人間を関与させるための組み込みの仕組みです。
+-   **トレーシング**: ワークフローを可視化、デバッグ、監視するための組み込みのトレーシングで、OpenAI の評価、ファインチューニング、蒸留ツール群をサポートします。
+-   **Realtime エージェント**: `gpt-realtime-2` を使い、自動割り込み検出、コンテキスト管理、ガードレールなどを備えた強力な音声エージェントを構築します。
 
-## Agents SDK と Responses API の比較
+## Agents SDK と Responses API の選択
 
-この SDK は、OpenAI モデルに対してはデフォルトで Responses API を使用しますが、モデル呼び出しの上により高水準のランタイムを追加します。
+SDK は OpenAI モデルに対してデフォルトで Responses API を使用しますが、モデル呼び出しの周りに高レベルのランタイムを追加します。
 
-次のような場合は、Responses API を直接使用してください。
+次の場合は Responses API を直接使用します:
 
--   ループ、ツールのディスパッチ、状態管理を自分で扱いたい
--   ワークフローが短命で、主にモデルの応答を返すことが目的である
+-   ループ、ツールのディスパッチ、状態処理を自分で管理したい場合
+-   ワークフローが短期間で、主にモデルの応答を返すことが目的の場合
 
-次のような場合は、Agents SDK を使用してください。
+次の場合は Agents SDK を使用します:
 
--   ランタイムにターン管理、ツール実行、ガードレール、ハンドオフ、またはセッションを管理させたい
--   エージェントに成果物を生成させたい、または複数の協調したステップにまたがって動作させたい
--   [Sandbox エージェント](sandbox_agents.md) を通じて、実際のワークスペースや再開可能な実行が必要である
+-   ランタイムにターン、ツール実行、ガードレール、ハンドオフ、またはセッションを管理させたい場合
+-   エージェントが成果物を生成する、または複数の協調したステップにわたって動作する必要がある場合
+-   実際のワークスペース、または [Sandbox エージェント](sandbox_agents.md) による再開可能な実行が必要な場合
 
-どちらか一方を全体で選ぶ必要はありません。多くのアプリケーションでは、管理されたワークフローには SDK を使い、より低水準の経路には Responses API を直接呼び出しています。
+アプリケーション全体でどちらか一方を選ぶ必要はありません。多くのアプリケーションでは、管理されたワークフローには SDK を使用し、低レベルの処理経路では Responses API を直接呼び出します。
 
 ## インストール
 
@@ -56,7 +56,7 @@ search:
 pip install openai-agents
 ```
 
-## Hello World の例
+## Hello world の例
 
 ```python
 from agents import Agent, Runner
@@ -71,7 +71,7 @@ print(result.final_output)
 # Infinite loop's dance.
 ```
 
-(_これを実行する場合は、`OPENAI_API_KEY` 環境変数を設定していることを確認してください_)
+(_これを実行する場合は、 `OPENAI_API_KEY` 環境変数を設定していることを確認してください_)
 
 ```bash
 export OPENAI_API_KEY=sk-...
@@ -79,23 +79,23 @@ export OPENAI_API_KEY=sk-...
 
 ## 開始ポイント
 
--   [Quickstart](quickstart.md) で最初のテキストベースのエージェントを構築します。
--   次に、[Running agents](running_agents.md#choose-a-memory-strategy) でターン間の状態の持ち方を決めます。
--   タスクが実際のファイル、リポジトリ、またはエージェントごとに分離されたワークスペース状態に依存する場合は、[Sandbox agents quickstart](sandbox_agents.md) を参照してください。
--   ハンドオフと manager 型のオーケストレーションのどちらにするかを決める場合は、[Agent orchestration](multi_agent.md) を参照してください。
+-   [クイックスタート](quickstart.md) で、最初のテキストベースのエージェントを構築します。
+-   次に、[エージェントの実行](running_agents.md#choose-a-memory-strategy) で、ターン間で状態をどのように引き継ぐかを決定します。
+-   タスクが実際のファイル、リポジトリ、またはエージェントごとに隔離されたワークスペース状態に依存する場合は、[Sandbox エージェントのクイックスタート](sandbox_agents.md) を参照してください。
+-   ハンドオフとマネージャースタイルのオーケストレーションのどちらにするかを決める場合は、[エージェントオーケストレーション](multi_agent.md) を参照してください。
 
 ## パスの選択
 
-やりたいことは分かっているが、それを説明しているページが分からない場合は、この表を使ってください。
+実行したい作業は分かっているものの、どのページで説明されているか分からない場合は、この表を使用してください。
 
-| 目標 | 開始ポイント |
+| 目的 | 参照先 |
 | --- | --- |
-| 最初のテキストエージェントを構築し、完全な 1 回の実行を見る | [Quickstart](quickstart.md) |
-| 関数ツール、ホストされたツール、または Agents as tools を追加する | [Tools](tools.md) |
-| 実際に分離されたワークスペース内で、コーディング、レビュー、またはドキュメント用エージェントを実行する | [Sandbox agents quickstart](sandbox_agents.md) と [Sandbox clients](sandbox/clients.md) |
-| ハンドオフと manager 型のエージェントオーケストレーションのどちらにするかを決める | [Agent orchestration](multi_agent.md) |
-| ターンをまたいでメモリを維持する | [Running agents](running_agents.md#choose-a-memory-strategy) と [Sessions](sessions/index.md) |
-| OpenAI モデル、websocket トランスポート、または OpenAI 以外のプロバイダーを使う | [Models](models/index.md) |
-| 出力、実行項目、割り込み、再開状態を確認する | [Results](results.md) |
-| `gpt-realtime-1.5` を使った低レイテンシの音声エージェントを構築する | [Realtime agents quickstart](realtime/quickstart.md) と [Realtime transport](realtime/transport.md) |
-| speech-to-text / agent / text-to-speech パイプラインを構築する | [Voice pipeline quickstart](voice/quickstart.md) |
+| 最初のテキストエージェントを構築し、完全な 1 回の実行を確認する | [クイックスタート](quickstart.md) |
+| 関数ツール、OpenAI がホストするツール、または agents as tools を追加する | [ツール](tools.md) |
+| 実際の隔離ワークスペース内で、コーディング、レビュー、またはドキュメント処理のエージェントを実行する | [Sandbox エージェントのクイックスタート](sandbox_agents.md) and [Sandbox クライアント](sandbox/clients.md) |
+| ハンドオフとマネージャースタイルのオーケストレーションのどちらを使うか決める | [エージェントオーケストレーション](multi_agent.md) |
+| ターン間でメモリを保持する | [エージェントの実行](running_agents.md#choose-a-memory-strategy) and [セッション](sessions/index.md) |
+| OpenAI モデル、WebSocket トランスポート、または OpenAI 以外のプロバイダーを使用する | [モデル](models/index.md) |
+| 出力、実行アイテム、割り込み、再開状態を確認する | [実行結果](results.md) |
+| `gpt-realtime-2` を使って低レイテンシの音声エージェントを構築する | [Realtime エージェントのクイックスタート](realtime/quickstart.md) and [Realtime トランスポート](realtime/transport.md) |
+| 音声認識 / エージェント / 音声合成のパイプラインを構築する | [音声パイプラインのクイックスタート](voice/quickstart.md) |

docs/ja/mcp.md

@@ -4,28 +4,33 @@ search:
 ---
 # Model context protocol (MCP)
 
-[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションが言語モデルにツールやコンテキストを公開する方法を標準化します。公式ドキュメントより:
+[Model context protocol](https://modelcontextprotocol.io/introduction) (MCP) は、アプリケーションが言語モデルにツールと
+コンテキストを公開する方法を標準化します。公式ドキュメントより:
 
-> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI アプリケーション向けの USB-C ポートのようなものだと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリーに接続するための標準化された方法を提供するのと同様に、MCP は AI モデルを異なるデータソースやツールに接続するための標準化された方法を提供します。
+> MCP は、アプリケーションが LLM にコンテキストを提供する方法を標準化するオープンプロトコルです。MCP は AI
+> アプリケーションのための USB-C ポートのようなものだと考えてください。USB-C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同じように、MCP
+> は AI モデルをさまざまなデータソースやツールに接続する標準化された方法を提供します。
 
-Agents Python SDK は複数の MCP トランスポートを理解します。これにより、既存の MCP サーバーを再利用したり、独自に構築してファイルシステム、 HTTP 、またはコネクタをバックエンドとするツールをエージェントに公開したりできます。
+Agents Python SDK は複数の MCP トランスポートに対応しています。これにより、既存の MCP サーバーを再利用したり、独自に構築して
+ファイルシステム、HTTP、またはコネクターを基盤とするツールをエージェントに公開できます。
 
 ## MCP 統合の選択
 
-MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行するか、到達可能なトランスポートはどれかを決めてください。以下のマトリクスは、 Python SDK がサポートする選択肢を要約したものです。
+MCP サーバーをエージェントに接続する前に、ツール呼び出しをどこで実行するか、どのトランスポートに到達できるかを決定してください。
+以下の表は、Python SDK がサポートする選択肢をまとめたものです。
 
-| 必要なもの | 推奨オプション |
+| 必要なこと                                                                        | 推奨オプション                                    |
 | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
-| モデルの代わりに OpenAI の Responses API から公開到達可能な MCP サーバーを呼び出す | [`HostedMCPTool`][agents.tool.HostedMCPTool] による **Hosted MCP server tools** |
-| ローカルまたはリモートで実行している Streamable HTTP サーバーに接続する | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] による **Streamable HTTP MCP servers** |
-| Server-Sent Events を使う HTTP を実装したサーバーと通信する | [`MCPServerSse`][agents.mcp.server.MCPServerSse] による **HTTP with SSE MCP servers** |
-| ローカルプロセスを起動し stdin/stdout 経由で通信する | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] による **stdio MCP servers** |
+| OpenAI の Responses API に、モデルの代理で公開到達可能な MCP サーバーを呼び出させる| [`HostedMCPTool`][agents.tool.HostedMCPTool] 経由の **ホスト型 MCP サーバーツール** |
+| ローカルまたはリモートで実行する Streamable HTTP サーバーに接続する                  | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] 経由の **Streamable HTTP MCP サーバー** |
+| Server-Sent Events を用いた HTTP を実装しているサーバーと通信する                          | [`MCPServerSse`][agents.mcp.server.MCPServerSse] 経由の **SSE 付き HTTP MCP サーバー** |
+| ローカルプロセスを起動し、stdin/stdout 経由で通信する                             | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] 経由の **stdio MCP サーバー** |
 
-以下のセクションでは、各オプション、設定方法、どのトランスポートを優先すべきかを説明します。
+以下のセクションでは、各オプション、設定方法、あるトランスポートを別のトランスポートより優先すべき場合について説明します。
 
 ## エージェントレベルの MCP 設定
 
-トランスポートの選択に加えて、 `Agent.mcp_config` を設定して MCP ツールの準備方法を調整できます。
+トランスポートの選択に加えて、`Agent.mcp_config` を設定することで、MCP ツールの準備方法を調整できます。
 
 ```python
 from agents import Agent
@@ -39,35 +44,42 @@ agent = Agent(
         # If None, MCP tool failures are raised as exceptions instead of
         # returning model-visible error text.
         "failure_error_function": None,
+        # Prefix local MCP tool names with their server name.
+        "include_server_in_tool_names": True,
     },
 )
 ```
 
-注記:
+注:
 
-- `convert_schemas_to_strict` はベストエフォートです。スキーマを変換できない場合は元のスキーマが使われます。
-- `failure_error_function` は MCP ツール呼び出し失敗をモデルへどのように提示するかを制御します。
-- `failure_error_function` が未設定の場合、 SDK はデフォルトのツールエラーフォーマッターを使います。
-- サーバーレベルの `failure_error_function` は、そのサーバーに対して `Agent.mcp_config["failure_error_function"]` を上書きします。
+- `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 ツール名を呼び出します。
 
-## トランスポート間の共通パターン
+## トランスポート間で共通するパターン
 
-トランスポートを選んだ後、ほとんどの統合で同じ追加判断が必要です:
+トランスポートを選択した後、多くの統合では同じような追加判断が必要です。
 
-- ツールの一部だけを公開する方法 ([Tool filtering](#tool-filtering))。
-- サーバーが再利用可能なプロンプトも提供するかどうか ([Prompts](#prompts))。
-- `list_tools()` をキャッシュすべきかどうか ([Caching](#caching))。
-- MCP アクティビティがトレースにどう表示されるか ([Tracing](#tracing))。
+- ツールのサブセットのみを公開する方法（[ツールフィルタリング](#tool-filtering)）。
+- サーバーが再利用可能なプロンプトも提供するかどうか（[プロンプト](#prompts)）。
+- `list_tools()` をキャッシュすべきかどうか（[キャッシュ](#caching)）。
+- MCP アクティビティがトレースにどのように表示されるか（[トレーシング](#tracing)）。
 
-ローカル MCP サーバー (`MCPServerStdio` 、 `MCPServerSse` 、 `MCPServerStreamableHttp`) では、承認ポリシーと呼び出しごとの `_meta` ペイロードも共通概念です。 Streamable HTTP セクションが最も完全なコード例を示しており、同じパターンが他のローカルトランスポートにも適用されます。
+ローカル MCP サーバー（`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp`）では、承認ポリシーと呼び出しごとの `_meta` ペイロードも共通の概念です。Streamable HTTP セクションでは最も完全な例を示しており、同じパターンは他のローカルトランスポートにも適用できます。
 
-## 1. Hosted MCP server tools
+## 1. ホスト型 MCP サーバーツール
 
-Hosted ツールは、ツールの往復全体を OpenAI のインフラに委ねます。コード側でツールを列挙・呼び出す代わりに、[`HostedMCPTool`][agents.tool.HostedMCPTool] がサーバーラベル（および任意のコネクタメタデータ）を Responses API に転送します。モデルはリモートサーバーのツールを列挙し、 Python プロセスへの追加コールバックなしで実行します。 Hosted ツールは現在、 Responses API の hosted MCP 統合をサポートする OpenAI モデルで動作します。
+ホスト型ツールでは、ツールの往復処理全体を OpenAI のインフラストラクチャに委ねます。コードでツールを一覧表示して呼び出す代わりに、
+[`HostedMCPTool`][agents.tool.HostedMCPTool] がサーバーラベル（および任意のコネクターメタデータ）を Responses API に転送します。
+モデルはリモートサーバーのツールを一覧表示し、Python プロセスへの追加のコールバックなしでそれらを呼び出します。ホスト型ツールは現在、
+Responses API のホスト型 MCP 統合をサポートする OpenAI モデルで動作します。
 
-### 基本の Hosted MCP ツール
+### 基本的なホスト型 MCP ツール
 
-エージェントの `tools` リストに [`HostedMCPTool`][agents.tool.HostedMCPTool] を追加して Hosted ツールを作成します。 `tool_config` 辞書は REST API に送る JSON を反映します:
+[`HostedMCPTool`][agents.tool.HostedMCPTool] をエージェントの `tools` リストに追加して、ホスト型ツールを作成します。`tool_config`
+dict は、REST API に送信する JSON と同じ構造です。
 
 ```python
 import asyncio
@@ -77,31 +89,36 @@ from agents import Agent, HostedMCPTool, Runner
 async def main() -> None:
     agent = Agent(
         name="Assistant",
+        instructions="Use the DeepWiki hosted MCP server to inspect openai/openai-agents-python.",
         tools=[
             HostedMCPTool(
                 tool_config={
                     "type": "mcp",
-                    "server_label": "gitmcp",
-                    "server_url": "https://gitmcp.io/openai/codex",
+                    "server_label": "deepwiki",
+                    "server_url": "https://mcp.deepwiki.com/mcp",
                     "require_approval": "never",
                 }
             )
         ],
     )
 
-    result = await Runner.run(agent, "Which language is this repository written in?")
+    result = await Runner.run(
+        agent,
+        "Which language is the repository openai/openai-agents-python written in?",
+    )
     print(result.final_output)
 
 asyncio.run(main())
 ```
 
-Hosted サーバーはツールを自動公開するため、 `mcp_servers` に追加する必要はありません。
+ホスト型サーバーはツールを自動的に公開します。`mcp_servers` に追加する必要はありません。
 
-Hosted ツール検索で hosted MCP サーバーを遅延読み込みしたい場合は、 `tool_config["defer_loading"] = True` を設定し、エージェントに [`ToolSearchTool`][agents.tool.ToolSearchTool] を追加してください。これは OpenAI Responses モデルでのみサポートされます。完全なツール検索の設定と制約は [Tools](tools.md#hosted-tool-search) を参照してください。
+ホスト型ツール検索でホスト型 MCP サーバーを遅延読み込みしたい場合は、`tool_config["defer_loading"] = True` を設定し、[`ToolSearchTool`][agents.tool.ToolSearchTool] をエージェントに追加します。これは OpenAI Responses モデルでのみサポートされます。ツール検索の完全な設定と制約については、[ツール](tools.md#hosted-tool-search)を参照してください。
 
-### Hosted MCP 結果のストリーミング
+### ホスト型 MCP 実行結果のストリーミング
 
-Hosted ツールは、関数ツールとまったく同じ方法で結果のストリーミングをサポートします。 `Runner.run_streamed` を使うと、モデルがまだ処理中でも増分 MCP 出力を消費できます:
+ホスト型ツールは、関数ツールとまったく同じ方法で実行結果のストリーミングをサポートします。`Runner.run_streamed` を使用して、
+モデルがまだ動作している間に、増分 MCP 出力を受け取ります。
 
 ```python
 result = Runner.run_streamed(agent, "Summarise this repository's top languages")
@@ -113,12 +130,14 @@ print(result.final_output)
 
 ### 任意の承認フロー
 
-サーバーが機密操作を実行可能な場合、各ツール実行前に人手またはプログラムによる承認を要求できます。 `tool_config` の `require_approval` に、単一ポリシー (`"always"` 、 `"never"`) またはツール名からポリシーへの辞書を設定します。 Python 側で判断するには `on_approval_request` コールバックを提供します。
+サーバーが機密性の高い操作を実行できる場合は、各ツール実行の前に人間による承認またはプログラムによる承認を要求できます。
+`tool_config` の `require_approval` に、単一のポリシー（`"always"`、`"never"`）またはツール名からポリシーへの
+マッピング dict を設定します。Python 内で判断するには、`on_approval_request` コールバックを提供します。
 
 ```python
 from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest
 
-SAFE_TOOLS = {"read_project_metadata"}
+SAFE_TOOLS = {"read_wiki_structure", "read_wiki_contents", "ask_question"}
 
 def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
     if request.data.name in SAFE_TOOLS:
@@ -131,8 +150,8 @@ agent = Agent(
         HostedMCPTool(
             tool_config={
                 "type": "mcp",
-                "server_label": "gitmcp",
-                "server_url": "https://gitmcp.io/openai/codex",
+                "server_label": "deepwiki",
+                "server_url": "https://mcp.deepwiki.com/mcp",
                 "require_approval": "always",
             },
             on_approval_request=approve_tool,
@@ -141,11 +160,12 @@ agent = Agent(
 )
 ```
 
-このコールバックは同期・非同期のどちらでもよく、モデルが実行継続のために承認データを必要とするたびに呼び出されます。
+コールバックは同期または非同期にでき、モデルが実行を続けるために承認データを必要とするたびに呼び出されます。
 
-### コネクタをバックエンドとする Hosted サーバー
+### コネクター対応のホスト型サーバー
 
-Hosted MCP は OpenAI コネクタもサポートします。 `server_url` を指定する代わりに、 `connector_id` とアクセストークンを渡します。 Responses API が認証を処理し、 hosted サーバーがコネクタのツールを公開します。
+ホスト型 MCP は OpenAI コネクターもサポートしています。`server_url` を指定する代わりに、`connector_id` とアクセストークンを指定します。
+Responses API が認証を処理し、ホスト型サーバーがコネクターのツールを公開します。
 
 ```python
 import os
@@ -161,11 +181,14 @@ HostedMCPTool(
 )
 ```
 
-ストリーミング、承認、コネクタを含む完全動作する Hosted ツールのサンプルは、[`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 servers
+## 2. Streamable HTTP MCP サーバー
 
-ネットワーク接続を自分で管理したい場合は、[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。 Streamable HTTP サーバーは、トランスポートを制御したい場合や、低遅延を保ちながら独自インフラ内でサーバーを実行したい場合に最適です。
+ネットワーク接続を自分で管理したい場合は、
+[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp] を使用します。Streamable HTTP サーバーは、トランスポートを自分で制御する場合や、
+レイテンシーを低く保ちながら自分のインフラストラクチャ内でサーバーを実行したい場合に最適です。
 
 ```python
 import asyncio
@@ -200,27 +223,27 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-コンストラクターは追加オプションを受け取ります:
+コンストラクターは追加オプションを受け付けます。
 
-- `client_session_timeout_seconds` は HTTP の読み取りタイムアウトを制御します。
-- `use_structured_content` はテキスト出力より `tool_result.structured_content` を優先するかを切り替えます。
-- `max_retry_attempts` と `retry_backoff_seconds_base` は `list_tools()` と `call_tool()` の自動リトライを追加します。
-- `tool_filter` はツールの一部だけを公開できます（[Tool filtering](#tool-filtering) 参照）。
-- `require_approval` はローカル MCP ツールで human-in-the-loop 承認ポリシーを有効化します。
-- `failure_error_function` はモデルに見える MCP ツール失敗メッセージをカスタマイズします。代わりにエラーを送出したい場合は `None` を設定します。
-- `tool_meta_resolver` は `call_tool()` 前に呼び出しごとの MCP `_meta` ペイロードを注入します。
+- `client_session_timeout_seconds` は HTTP 読み取りタイムアウトを制御します。
+- `use_structured_content` は、テキスト出力より `tool_result.structured_content` を優先するかどうかを切り替えます。
+- `max_retry_attempts` と `retry_backoff_seconds_base` は、`list_tools()` と `call_tool()` に自動再試行を追加します。
+- `tool_filter` により、ツールのサブセットのみを公開できます（[ツールフィルタリング](#tool-filtering)を参照）。
+- `require_approval` は、ローカル MCP ツールで人間参加型の承認ポリシーを有効にします。
+- `failure_error_function` は、モデルに見える MCP ツール失敗メッセージをカスタマイズします。代わりにエラーを発生させるには、`None` に設定します。
+- `tool_meta_resolver` は、`call_tool()` の前に呼び出しごとの MCP `_meta` ペイロードを注入します。
 
 ### ローカル MCP サーバーの承認ポリシー
 
-`MCPServerStdio` 、 `MCPServerSse` 、 `MCPServerStreamableHttp` はすべて `require_approval` を受け付けます。
+`MCPServerStdio`、`MCPServerSse`、`MCPServerStreamableHttp` はすべて `require_approval` を受け付けます。
 
 サポートされる形式:
 
-- すべてのツールに対する `"always"` または `"never"` 。
-- `True` / `False` （ always/never と同等）。
-- ツールごとのマップ。例: `{"delete_file": "always", "read_file": "never"}` 。
-- グループ化オブジェクト:
-  `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}` 。
+- すべてのツールに対する `"always"` または `"never"`。
+- `True` / `False`（always/never と同等）。
+- ツールごとのマップ。例: `{"delete_file": "always", "read_file": "never"}`。
+- グループ化されたオブジェクト:
+  `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`。
 
 ```python
 async with MCPServerStreamableHttp(
@@ -231,11 +254,11 @@ async with MCPServerStreamableHttp(
     ...
 ```
 
-完全な一時停止/再開フローは、 [Human-in-the-loop](human_in_the_loop.md) と `examples/mcp/get_all_mcp_tools_example/main.py` を参照してください。
+完全な一時停止/再開フローについては、[人間参加型](human_in_the_loop.md)および `examples/mcp/get_all_mcp_tools_example/main.py` を参照してください。
 
 ### `tool_meta_resolver` による呼び出しごとのメタデータ
 
-MCP サーバーが `_meta` のリクエストメタデータ（例: テナント ID やトレースコンテキスト）を必要とする場合は `tool_meta_resolver` を使います。以下の例は、 `Runner.run(...)` に `context` として `dict` を渡すことを前提にしています。
+MCP サーバーが `_meta` 内にリクエストメタデータ（たとえば、テナント ID やトレースコンテキスト）を想定している場合は、`tool_meta_resolver` を使用します。以下の例では、`Runner.run(...)` に `context` として `dict` を渡すことを想定しています。
 
 ```python
 from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext
@@ -256,19 +279,20 @@ server = MCPServerStreamableHttp(
 )
 ```
 
-実行コンテキストが Pydantic モデル、 dataclass 、またはカスタムクラスの場合は、代わりに属性アクセスでテナント ID を読み取ってください。
+実行コンテキストが Pydantic モデル、dataclass、またはカスタムクラスの場合は、属性アクセスでテナント ID を読み取ってください。
 
 ### MCP ツール出力: テキストと画像
 
-MCP ツールが画像コンテンツを返す場合、 SDK はそれを自動的に画像ツール出力エントリにマップします。テキスト/画像混在レスポンスは出力項目のリストとして転送されるため、エージェントは通常の関数ツールからの画像出力と同じ方法で MCP 画像結果を処理できます。
+MCP ツールが画像コンテンツを返すと、SDK はそれを画像ツール出力エントリーに自動的にマッピングします。テキスト/画像が混在するレスポンスは出力項目のリストとして転送されるため、エージェントは通常の関数ツールからの画像出力を利用するのと同じ方法で MCP 画像実行結果を利用できます。
 
-## 3. HTTP with SSE MCP servers
+## 3. SSE 付き HTTP MCP サーバー
 
 !!! warning
 
-    MCP プロジェクトは Server-Sent Events トランスポートを非推奨にしています。新規統合では Streamable HTTP または stdio を優先し、 SSE はレガシーサーバー用のみにしてください。
+    MCP プロジェクトでは Server-Sent Events トランスポートが非推奨になりました。新しい統合には Streamable HTTP または stdio を優先し、SSE はレガシーサーバー向けにのみ維持してください。
 
-MCP サーバーが HTTP with SSE トランスポートを実装している場合は、[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポート以外の API は Streamable HTTP サーバーと同一です。
+MCP サーバーが SSE 付き HTTP トランスポートを実装している場合は、
+[`MCPServerSse`][agents.mcp.server.MCPServerSse] をインスタンス化します。トランスポートを除けば、API は Streamable HTTP サーバーと同一です。
 
 ```python
 
@@ -295,9 +319,11 @@ async with MCPServerSse(
     print(result.final_output)
 ```
 
-## 4. stdio MCP servers
+## 4. stdio MCP サーバー
 
-ローカルサブプロセスとして実行される MCP サーバーには、 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使います。 SDK はプロセスを起動し、パイプを開いたまま維持し、コンテキストマネージャー終了時に自動で閉じます。このオプションは、素早い概念実証や、サーバーがコマンドラインエントリポイントしか公開していない場合に有用です。
+ローカルサブプロセスとして実行される MCP サーバーには、[`MCPServerStdio`][agents.mcp.server.MCPServerStdio] を使用します。SDK は
+プロセスを起動し、パイプを開いたままにし、コンテキストマネージャーを抜けると自動的に閉じます。このオプションは、素早い概念実証や、
+サーバーがコマンドラインエントリーポイントのみを公開している場合に役立ちます。
 
 ```python
 from pathlib import Path
@@ -325,7 +351,8 @@ async with MCPServerStdio(
 
 ## 5. MCP サーバーマネージャー
 
-複数の MCP サーバーがある場合は、 `MCPServerManager` を使って事前に接続し、接続済みサブセットをエージェントに公開します。コンストラクターオプションと再接続動作は [MCPServerManager API reference](ref/mcp/manager.md) を参照してください。
+複数の MCP サーバーがある場合は、`MCPServerManager` を使用して事前に接続し、接続済みのサブセットをエージェントに公開します。
+コンストラクターオプションと再接続の動作については、[MCPServerManager API リファレンス](ref/mcp/manager.md)を参照してください。
 
 ```python
 from agents import Agent, Runner
@@ -346,25 +373,26 @@ async with MCPServerManager(servers) as manager:
     print(result.final_output)
 ```
 
-主な挙動:
+主な動作:
 
-- `active_servers` は `drop_failed_servers=True` （デフォルト）時に接続成功したサーバーのみを含みます。
+- `active_servers` には、`drop_failed_servers=True`（デフォルト）の場合、正常に接続されたサーバーのみが含まれます。
 - 失敗は `failed_servers` と `errors` で追跡されます。
-- 最初の接続失敗で例外を発生させるには `strict=True` を設定します。
-- 失敗サーバーのみ再試行するには `reconnect(failed_only=True)` 、全サーバーを再起動するには `reconnect(failed_only=False)` を呼びます。
-- ライフサイクル動作を調整するには `connect_timeout_seconds` 、 `cleanup_timeout_seconds` 、 `connect_in_parallel` を使います。
+- 最初の接続失敗で例外を発生させるには、`strict=True` を設定します。
+- 失敗したサーバーを再試行するには `reconnect(failed_only=True)` を呼び出し、すべてのサーバーを再起動するには `reconnect(failed_only=False)` を呼び出します。
+- ライフサイクルの動作を調整するには、`connect_timeout_seconds`、`cleanup_timeout_seconds`、`connect_in_parallel` を使用します。
 
-## 共通サーバー機能
+## 共通のサーバー機能
 
-以下のセクションは MCP サーバートランスポート全体に適用されます（正確な API 表面はサーバークラスに依存します）。
+以下のセクションは、MCP サーバートランスポート全体に適用されます（正確な API サーフェスはサーバークラスによって異なります）。
 
-## Tool filtering
+## ツールフィルタリング
 
-各 MCP サーバーはツールフィルターをサポートしており、エージェントに必要な関数だけを公開できます。フィルタリングは構築時または実行ごとに動的に行えます。
+各 MCP サーバーはツールフィルターをサポートしているため、エージェントに必要な関数だけを公開できます。フィルタリングは、
+構築時にも実行ごとに動的にも行えます。
 
 ### 静的ツールフィルタリング
 
-シンプルな許可/ブロックリストを設定するには [`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使います:
+単純な許可/ブロックリストを設定するには、[`create_static_tool_filter`][agents.mcp.create_static_tool_filter] を使用します。
 
 ```python
 from pathlib import Path
@@ -382,11 +410,13 @@ filesystem_server = MCPServerStdio(
 )
 ```
 
-`allowed_tool_names` と `blocked_tool_names` の両方が与えられた場合、 SDK はまず許可リストを適用し、その残り集合からブロック対象ツールを除外します。
+`allowed_tool_names` と `blocked_tool_names` の両方が指定された場合、SDK はまず許可リストを適用し、その後、残ったセットから
+ブロックされたツールを削除します。
 
 ### 動的ツールフィルタリング
 
-より高度なロジックには [`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る callable を渡します。 callable は同期・非同期のいずれでもよく、ツールを公開すべき場合に `True` を返します。
+より複雑なロジックには、[`ToolFilterContext`][agents.mcp.ToolFilterContext] を受け取る呼び出し可能オブジェクトを渡します。呼び出し可能オブジェクトは
+同期または非同期にでき、ツールを公開すべき場合に `True` を返します。
 
 ```python
 from pathlib import Path
@@ -410,14 +440,15 @@ async with MCPServerStdio(
     ...
 ```
 
-フィルターコンテキストは、アクティブな `run_context` 、ツールを要求する `agent` 、および `server_name` を公開します。
+フィルターコンテキストは、アクティブな `run_context`、ツールを要求している `agent`、および `server_name` を公開します。
 
-## Prompts
+## プロンプト
 
-MCP サーバーは、エージェント指示を動的生成するプロンプトも提供できます。プロンプト対応サーバーは次の 2 つのメソッドを公開します:
+MCP サーバーは、エージェントの指示を動的に生成するプロンプトも提供できます。プロンプトをサポートするサーバーは、次の 2 つの
+メソッドを公開します。
 
-- `list_prompts()` は利用可能なプロンプトテンプレートを列挙します。
-- `get_prompt(name, arguments)` は具体的なプロンプトを取得します（必要に応じてパラメーター付き）。
+- `list_prompts()` は、利用可能なプロンプトテンプレートを列挙します。
+- `get_prompt(name, arguments)` は、必要に応じてパラメーター付きで具体的なプロンプトを取得します。
 
 ```python
 from agents import Agent
@@ -435,21 +466,22 @@ agent = Agent(
 )
 ```
 
-## Caching
+## キャッシュ
 
-各エージェント実行は各 MCP サーバーで `list_tools()` を呼びます。リモートサーバーは目立つレイテンシを生む可能性があるため、すべての MCP サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変わらないと確信できる場合にのみ `True` に設定してください。後で最新リストを強制したい場合は、サーバーインスタンスで `invalidate_tools_cache()` を呼びます。
+エージェントの各実行では、各 MCP サーバーで `list_tools()` が呼び出されます。リモートサーバーでは顕著なレイテンシーが発生する可能性があるため、すべての MCP
+サーバークラスは `cache_tools_list` オプションを公開しています。ツール定義が頻繁に変わらないと確信できる場合にのみ、`True` に設定してください。後で最新のリストを強制的に取得するには、サーバーインスタンスで `invalidate_tools_cache()` を呼び出します。
 
-## Tracing
+## トレーシング
 
-[Tracing](./tracing.md) は、以下を含む MCP アクティビティを自動で記録します:
+[トレーシング](./tracing.md)は、以下を含む MCP アクティビティを自動的にキャプチャします。
 
-1. ツール一覧取得のための MCP サーバー呼び出し。
-2. ツール呼び出し上の MCP 関連情報。
+1. ツールを一覧表示するための MCP サーバーへの呼び出し。
+2. ツール呼び出しに関する MCP 関連情報。
 
-![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg)
+![MCP トレーシングのスクリーンショット](../assets/images/mcp-tracing.jpg)
 
-## 参考情報
+## 参考資料
 
 - [Model Context Protocol](https://modelcontextprotocol.io/) – 仕様と設計ガイド。
-- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio 、 SSE 、 Streamable HTTP サンプル。
-- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認とコネクタを含む完全な hosted MCP デモ。
+- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 実行可能な stdio、SSE、Streamable HTTP サンプル。
+- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 承認とコネクターを含む完全なホスト型 MCP デモ。

docs/ja/models/index.md

@@ -4,31 +4,31 @@ search:
 ---
 # モデル
 
-Agents SDK には、OpenAI モデルに対する標準サポートが 2 つの形で含まれています。
+Agents SDK には、OpenAI モデルの標準サポートが 2 種類用意されています。
 
-- **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。
-- [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。
+-   **推奨**: 新しい [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用して OpenAI API を呼び出す [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]。
+-   [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) を使用して OpenAI API を呼び出す [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。
 
 ## モデル設定の選択
 
-ご利用の構成に合う最もシンプルな方法から始めてください。
+セットアップに合う最もシンプルな方法から始めてください。
 
-| やりたいこと | 推奨される方法 | 詳細 |
+| 実現したいこと | 推奨される方法 | 詳細 |
 | --- | --- | --- |
-| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデル経路で使用する | [OpenAI モデル](#openai-models) |
-| WebSocket トランスポート経由で OpenAI Responses API を使用する | Responses モデル経路を維持し、WebSocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) |
+| OpenAI モデルのみを使用する | デフォルトの OpenAI プロバイダーを Responses モデルパスで使用する | [OpenAI モデル](#openai-models) |
+| websocket トランスポート経由で OpenAI Responses API を使用する | Responses モデルパスを維持し、websocket トランスポートを有効にする | [Responses WebSocket トランスポート](#responses-websocket-transport) |
 | 1 つの非 OpenAI プロバイダーを使用する | 組み込みのプロバイダー統合ポイントから始める | [非 OpenAI モデル](#non-openai-models) |
-| エージェント間でモデルやプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能差を確認する | [1 つのワークフロー内でのモデルの混在](#mixing-models-in-one-workflow) と [プロバイダー間でのモデルの混在](#mixing-models-across-providers) |
-| 高度な OpenAI Responses リクエスト設定を調整する | OpenAI Responses 経路で `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) |
-| 非 OpenAI または混在プロバイダーのルーティングにサードパーティ製アダプターを使用する | サポートされているベータ版アダプターを比較し、出荷予定のプロバイダー経路を検証する | [サードパーティ製アダプター](#third-party-adapters) |
+| エージェント間でモデルまたはプロバイダーを混在させる | 実行ごと、またはエージェントごとにプロバイダーを選択し、機能差を確認する | [1 つのワークフローでのモデルの混在](#mixing-models-in-one-workflow) と [プロバイダー間でのモデルの混在](#mixing-models-across-providers) |
+| 高度な OpenAI Responses リクエスト設定を調整する | OpenAI Responses パスで `ModelSettings` を使用する | [高度な OpenAI Responses 設定](#advanced-openai-responses-settings) |
+| 非 OpenAI または混在プロバイダーのルーティングにサードパーティアダプターを使用する | サポートされているベータ版アダプターを比較し、リリース予定のプロバイダーパスを検証する | [サードパーティアダプター](#third-party-adapters) |
 
 ## OpenAI モデル
 
-ほとんどの OpenAI のみのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデル経路を使い続ける方法を推奨します。
+ほとんどの OpenAI のみのアプリでは、デフォルトの OpenAI プロバイダーで文字列のモデル名を使用し、Responses モデルパスを維持する方法が推奨されます。
 
-`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。現在のデフォルトは、互換性と低レイテンシーのため [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) です。利用可能な場合は、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) にエージェントを設定することを推奨します。
+`Agent` の初期化時にモデルを指定しない場合、デフォルトモデルが使用されます。低レイテンシのエージェントワークフロー向けに、現在のデフォルトは [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) で、`reasoning.effort="none"` と `verbosity="low"` が設定されています。アクセス権がある場合は、明示的な `model_settings` を維持しつつ、より高品質な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) をエージェントに設定することを推奨します。
 
-[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの他のモデルに切り替えたい場合、エージェントの設定方法は 2 つあります。
+[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。
 
 ### デフォルトモデル
 
@@ -39,7 +39,7 @@ export OPENAI_DEFAULT_MODEL=gpt-5.5
 python3 my_awesome_agent.py
 ```
 
-次に、`RunConfig` を通じて 1 回の実行のデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使用されます。
+次に、`RunConfig` を通じて実行のデフォルトモデルを設定できます。エージェントにモデルを設定しない場合、この実行のモデルが使用されます。
 
 ```python
 from agents import Agent, RunConfig, Runner
@@ -58,7 +58,7 @@ result = await Runner.run(
 
 #### GPT-5 モデル
 
-この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最もよく機能する設定が適用されます。デフォルトモデルの推論エフォートを調整するには、独自の `ModelSettings` を渡します。
+この方法で [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) などの GPT-5 モデルを使用すると、SDK はデフォルトの `ModelSettings` を適用します。ほとんどのユースケースで最も適切に動作する設定が適用されます。デフォルトモデルの reasoning effort を調整するには、独自の `ModelSettings` を渡します。
 
 ```python
 from openai.types.shared import Reasoning
@@ -74,35 +74,35 @@ my_agent = Agent(
 )
 ```
 
-低レイテンシーには、`gpt-5.5` で `reasoning.effort="none"` を使用することを推奨します。gpt-4.1 ファミリー（mini や nano バリアントを含む）も、インタラクティブなエージェントアプリを構築するうえで堅実な選択肢です。
+低レイテンシにするには、GPT-5 モデルで `reasoning.effort="none"` を使用することを推奨します。
 
 #### ComputerTool のモデル選択
 
-エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込みの `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードが維持されます。
+エージェントに [`ComputerTool`][agents.tool.ComputerTool] が含まれる場合、実際の Responses リクエストで有効なモデルによって、SDK が送信する computer-tool ペイロードが決まります。明示的な `gpt-5.5` リクエストでは GA 組み込み `computer` ツールが使用され、明示的な `computer-use-preview` リクエストでは従来の `computer_use_preview` ペイロードが維持されます。
 
-主な例外は、プロンプト管理の呼び出しです。プロンプトテンプレートがモデルを所有し、SDK がリクエストから `model` を省略する場合、SDK はプロンプトがどのモデルに固定されているかを推測しないよう、プレビュー互換の computer ペイロードをデフォルトにします。このフローで GA 経路を維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制してください。
+主な例外は、プロンプト管理の呼び出しです。プロンプトテンプレートがモデルを保持し、SDK がリクエストから `model` を省略する場合、SDK は、プロンプトが固定しているモデルを推測しないように、プレビュー互換の computer ペイロードをデフォルトにします。そのフローで GA パスを維持するには、リクエストで `model="gpt-5.5"` を明示するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制します。
 
-登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名のように引き続き動作します。
+登録済みの [`ComputerTool`][agents.tool.ComputerTool] がある場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` は、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。`ComputerTool` が登録されていない場合、これらの文字列は通常の関数名と同様に動作し続けます。
 
-プレビュー互換リクエストでは `environment` と表示サイズを事前にシリアライズする必要があるため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエストを送信する前に GA セレクターを強制する必要があります。移行の詳細については、[ツール](../tools.md#computertool-and-the-responses-computer-tool)を参照してください。
+プレビュー互換のリクエストでは、`environment` と表示寸法を事前にシリアライズする必要があります。そのため、[`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーを使用するプロンプト管理フローでは、具体的な `Computer` または `AsyncComputer` インスタンスを渡すか、リクエスト送信前に GA セレクターを強制する必要があります。移行の詳細については、[ツール](../tools.md#computertool-and-the-responses-computer-tool)を参照してください。
 
 #### 非 GPT-5 モデル
 
-カスタム `model_settings` なしで非 GPT-5 モデル名を渡した場合、SDK は任意のモデルと互換性のある汎用 `ModelSettings` に戻ります。
+カスタムの `model_settings` なしで非 GPT-5 モデル名を渡すと、SDK は任意のモデルと互換性のある汎用の `ModelSettings` に戻します。
 
-### Responses 専用のツール検索機能
+### Responses のみのツール検索機能
 
 次のツール機能は、OpenAI Responses モデルでのみサポートされています。
 
-- [`ToolSearchTool`][agents.tool.ToolSearchTool]
-- [`tool_namespace()`][agents.tool.tool_namespace]
-- `@function_tool(defer_loading=True)` およびその他の遅延読み込み Responses ツールサーフェス
+-   [`ToolSearchTool`][agents.tool.ToolSearchTool]
+-   [`tool_namespace()`][agents.tool.tool_namespace]
+-   `@function_tool(defer_loading=True)` とその他の遅延読み込み Responses ツールサーフェス
 
-これらの機能は、Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の名前空間名や遅延専用の関数名を強制するのではなく、モデルが `auto` または `required` のツール選択を通じてツールを読み込めるようにしてください。設定の詳細と現在の制約については、[ツール](../tools.md#hosted-tool-search)を参照してください。
+これらの機能は、Chat Completions モデルおよび非 Responses バックエンドでは拒否されます。遅延読み込みツールを使用する場合は、エージェントに `ToolSearchTool()` を追加し、裸の名前空間名や遅延専用の関数名を強制するのではなく、`auto` または `required` のツール選択を通じてモデルにツールを読み込ませてください。セットアップの詳細と現在の制約については、[ツール](../tools.md#hosted-tool-search)を参照してください。
 
 ### Responses WebSocket トランスポート
 
-デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI ベースのモデルを使用する場合、WebSocket トランスポートをオプトインできます。
+デフォルトでは、OpenAI Responses API リクエストは HTTP トランスポートを使用します。OpenAI ベースのモデルを使用する場合は、websocket トランスポートを有効にできます。
 
 #### 基本設定
 
@@ -114,11 +114,11 @@ set_default_openai_responses_transport("websocket")
 
 これは、デフォルトの OpenAI プロバイダーによって解決される OpenAI Responses モデル（`"gpt-5.5"` などの文字列モデル名を含む）に影響します。
 
-トランスポートの選択は、SDK がモデル名をモデルインスタンスに解決するときに行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡す場合、そのトランスポートはすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は WebSocket を使用し、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP を使用し、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡す場合、グローバルデフォルトではなく、そのプロバイダーがトランスポート選択を制御します。
+トランスポートの選択は、SDK がモデル名をモデルインスタンスに解決するときに行われます。具体的な [`Model`][agents.models.interface.Model] オブジェクトを渡す場合、そのトランスポートはすでに固定されています。[`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel] は websocket を使用し、[`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] は HTTP を使用し、[`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] は Chat Completions のままです。`RunConfig(model_provider=...)` を渡す場合、グローバルデフォルトではなく、そのプロバイダーがトランスポート選択を制御します。
 
 #### プロバイダーまたは実行レベルの設定
 
-プロバイダーごと、または実行ごとに WebSocket トランスポートを設定することもできます。
+プロバイダーごと、または実行ごとに websocket トランスポートを設定することもできます。
 
 ```python
 from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -127,6 +127,8 @@ provider = OpenAIProvider(
     use_responses_websocket=True,
     # Optional; if omitted, OPENAI_WEBSOCKET_BASE_URL is used when set.
     websocket_base_url="wss://your-proxy.example/v1",
+    # Optional low-level websocket keepalive settings.
+    responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
 )
 
 agent = Agent(name="Assistant")
@@ -137,7 +139,7 @@ result = await Runner.run(
 )
 ```
 
-OpenAI ベースのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI 設定が harness ID などのプロバイダーレベルの登録メタデータを想定している場合の高度なオプションです。
+OpenAI ベースのプロバイダーは、任意のエージェント登録設定も受け付けます。これは、OpenAI の設定で harness ID などのプロバイダーレベルの登録メタデータが想定されている場合の高度なオプションです。
 
 ```python
 from agents import (
@@ -163,14 +165,14 @@ result = await Runner.run(
 
 #### `MultiProvider` による高度なルーティング
 
-プレフィックスベースのモデルルーティングが必要な場合（たとえば 1 回の実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）は、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。
+プレフィックスベースのモデルルーティングが必要な場合（たとえば 1 つの実行で `openai/...` と `any-llm/...` のモデル名を混在させる場合）は、[`MultiProvider`][agents.MultiProvider] を使用し、そこで `openai_use_responses_websocket=True` を設定します。
 
-`MultiProvider` は、過去のデフォルトを 2 つ維持しています。
+`MultiProvider` は、歴史的なデフォルトを 2 つ保持しています。
 
-- `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。
-- 不明なプレフィックスは、そのまま渡されるのではなく `UserError` を発生させます。
+-   `openai/...` は OpenAI プロバイダーのエイリアスとして扱われるため、`openai/gpt-4.1` はモデル `gpt-4.1` としてルーティングされます。
+-   不明なプレフィックスは、パススルーされるのではなく `UserError` を発生させます。
 
-OpenAI プロバイダーを、リテラルの名前空間付きモデル ID を期待する OpenAI 互換エンドポイントに向ける場合は、パススルー動作を明示的にオプトインしてください。WebSocket が有効な設定では、`MultiProvider` でも `openai_use_responses_websocket=True` を維持してください。
+OpenAI プロバイダーを、リテラルな名前空間付きモデル ID を想定する OpenAI 互換エンドポイントに向ける場合は、パススルー動作を明示的に有効にします。websocket が有効なセットアップでは、`MultiProvider` でも `openai_use_responses_websocket=True` を維持してください。
 
 ```python
 from agents import Agent, MultiProvider, RunConfig, Runner
@@ -196,38 +198,39 @@ result = await Runner.run(
 )
 ```
 
-バックエンドがリテラルの `openai/...` 文字列を期待する場合は、`openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` などの他の名前空間付きモデル ID を期待する場合は、`unknown_prefix_mode="model_id"` を使用します。これらのオプションは WebSocket トランスポート外の `MultiProvider` でも機能します。この例では、このセクションで説明しているトランスポート設定の一部であるため WebSocket を有効にしています。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。
+バックエンドがリテラルな `openai/...` 文字列を想定する場合は、`openai_prefix_mode="model_id"` を使用します。バックエンドが `openrouter/openai/gpt-4.1-mini` など、他の名前空間付きモデル ID を想定する場合は、`unknown_prefix_mode="model_id"` を使用します。これらのオプションは、websocket トランスポート外の `MultiProvider` でも機能します。この例では、このセクションで説明しているトランスポート設定の一部であるため、websocket を有効なままにしています。同じオプションは [`responses_websocket_session()`][agents.responses_websocket_session] でも利用できます。
 
 `MultiProvider` 経由でルーティングしながら同じプロバイダーレベルの登録メタデータが必要な場合は、`openai_agent_registration=OpenAIAgentRegistrationConfig(...)` を渡すと、基盤となる OpenAI プロバイダーに転送されます。
 
-カスタムの OpenAI 互換エンドポイントまたはプロキシを使用する場合、WebSocket トランスポートには互換性のある WebSocket `/responses` エンドポイントも必要です。そのような構成では、`websocket_base_url` を明示的に設定する必要がある場合があります。
+カスタムの OpenAI 互換エンドポイントまたはプロキシを使用する場合、websocket トランスポートには互換性のある websocket `/responses` エンドポイントも必要です。そのようなセットアップでは、`websocket_base_url` を明示的に設定する必要がある場合があります。
 
 #### 注記
 
-- これは WebSocket トランスポート経由の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Chat Completions や非 OpenAI プロバイダーには、それらが Responses WebSocket `/responses` エンドポイントをサポートしていない限り適用されません。
-- 環境でまだ利用できない場合は、`websockets` パッケージをインストールしてください。
-- WebSocket トランスポートを有効にした後、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。ターン間（およびネストされた agent-as-tool 呼び出し）で同じ WebSocket 接続を再利用したいマルチターンワークフローでは、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[エージェントの実行](../running_agents.md)ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。
+-   これは websocket トランスポート上の Responses API であり、[Realtime API](../realtime/guide.md) ではありません。Responses websocket `/responses` エンドポイントをサポートしていない限り、Chat Completions や非 OpenAI プロバイダーには適用されません。
+-   環境でまだ利用できない場合は、`websockets` パッケージをインストールしてください。
+-   websocket トランスポートを有効にした後、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を直接使用できます。複数ターンのワークフローで、ターン間（および入れ子の agent-as-tool 呼び出し）で同じ websocket 接続を再利用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] ヘルパーを推奨します。[エージェントの実行](../running_agents.md)ガイドと [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py) を参照してください。
+-   長い推論ターンやレイテンシの急増があるネットワークでは、`responses_websocket_options` で websocket keepalive の動作をカスタマイズしてください。遅延した pong フレームを許容するには `ping_timeout` を増やすか、ping を有効にしたままハートビートタイムアウトを無効にするには `ping_timeout=None` を設定します。websocket レイテンシより信頼性が重要な場合は、HTTP/SSE トランスポートを優先してください。
 
 ## 非 OpenAI モデル
 
-非 OpenAI プロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くの構成では、サードパーティ製アダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。
+非 OpenAI プロバイダーが必要な場合は、SDK の組み込みプロバイダー統合ポイントから始めてください。多くのセットアップでは、サードパーティアダプターを追加しなくてもこれで十分です。各パターンの例は [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/) にあります。
 
 ### 非 OpenAI プロバイダーの統合方法
 
-| アプローチ | 使用する場面 | スコープ |
+| アプローチ | 使用する場合 | 範囲 |
 | --- | --- | --- |
 | [`set_default_openai_client`][agents.set_default_openai_client] | 1 つの OpenAI 互換エンドポイントを、ほとんどまたはすべてのエージェントのデフォルトにしたい場合 | グローバルデフォルト |
 | [`ModelProvider`][agents.models.interface.ModelProvider] | 1 つのカスタムプロバイダーを 1 回の実行に適用したい場合 | 実行ごと |
-| [`Agent.model`][agents.agent.Agent.model] | 異なるエージェントに異なるプロバイダーまたは具体的なモデルオブジェクトが必要な場合 | エージェントごと |
-| サードパーティ製アダプター | 組み込み経路では提供されない、アダプター管理のプロバイダーカバレッジやルーティングが必要な場合 | [サードパーティ製アダプター](#third-party-adapters)を参照 |
+| [`Agent.model`][agents.agent.Agent.model] | 異なるエージェントに異なるプロバイダーや具体的なモデルオブジェクトが必要な場合 | エージェントごと |
+| サードパーティアダプター | 組み込みパスでは提供されない、アダプター管理のプロバイダー対応範囲やルーティングが必要な場合 | [サードパーティアダプター](#third-party-adapters)を参照 |
 
-これらの組み込み経路で他の LLM プロバイダーを統合できます。
+これらの組み込みパスで、他の LLM プロバイダーを統合できます。
 
-1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。これは、LLM プロバイダーが OpenAI 互換 API エンドポイントを持ち、`base_url` と `api_key` を設定できる場合向けです。設定可能な例は [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。
-2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより、「この実行内のすべてのエージェントにカスタムモデルプロバイダーを使用する」と指定できます。設定可能な例は [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。
-3. [`Agent.model`][agents.agent.Agent.model] により、特定の Agent インスタンスでモデルを指定できます。これにより、異なるエージェントに対して異なるプロバイダーを組み合わせて使用できます。設定可能な例は [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。
+1. [`set_default_openai_client`][agents.set_default_openai_client] は、`AsyncOpenAI` のインスタンスを LLM クライアントとしてグローバルに使用したい場合に便利です。これは、LLM プロバイダーに OpenAI 互換 API エンドポイントがあり、`base_url` と `api_key` を設定できる場合に使用します。設定可能な例については、[examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py) を参照してください。
+2. [`ModelProvider`][agents.models.interface.ModelProvider] は `Runner.run` レベルです。これにより、「この実行内のすべてのエージェントにカスタムモデルプロバイダーを使用する」と指定できます。設定可能な例については、[examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py) を参照してください。
+3. [`Agent.model`][agents.agent.Agent.model] により、特定の Agent インスタンスでモデルを指定できます。これにより、異なるエージェントに対して異なるプロバイダーを自由に組み合わせられます。設定可能な例については、[examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py) を参照してください。
 
-`platform.openai.com` の API キーを持っていない場合は、`set_tracing_disabled()` でトレーシングを無効にするか、[別のトレーシングプロセッサー](../tracing.md)を設定することを推奨します。
+`platform.openai.com` からの API キーがない場合は、`set_tracing_disabled()` でトレーシングを無効にするか、[別のトレーシングプロセッサー](../tracing.md)を設定することを推奨します。
 
 ``` python
 from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
@@ -242,9 +245,9 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model
 
 !!! note
 
-    これらの例では、多くの LLM プロバイダーがまだ Responses API をサポートしていないため、Chat Completions API/モデルを使用しています。ご利用の LLM プロバイダーが Responses をサポートしている場合は、Responses の使用を推奨します。
+    これらの例では、Chat Completions API/モデルを使用しています。多くの LLM プロバイダーは、まだ Responses API をサポートしていないためです。LLM プロバイダーが Responses API をサポートしている場合は、Responses の使用を推奨します。
 
-## 1 つのワークフロー内でのモデルの混在
+## 1 つのワークフローでのモデルの混在
 
 単一のワークフロー内で、エージェントごとに異なるモデルを使用したい場合があります。たとえば、トリアージには小さく高速なモデルを使用し、複雑なタスクにはより大きく高性能なモデルを使用できます。[`Agent`][agents.Agent] を設定する際、次のいずれかの方法で特定のモデルを選択できます。
 
@@ -254,7 +257,7 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model
 
 !!! note
 
-    SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、各ワークフローでは単一のモデル形状を使用することを推奨します。これは、2 つの形状がサポートする機能とツールのセットが異なるためです。ワークフローでモデル形状を組み合わせる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。
+    SDK は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] と [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] の両方の形状をサポートしていますが、2 つの形状でサポートされる機能とツールのセットが異なるため、各ワークフローでは単一のモデル形状を使用することを推奨します。ワークフローでモデル形状を組み合わせる必要がある場合は、使用するすべての機能が両方で利用できることを確認してください。
 
 ```python
 from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -287,10 +290,10 @@ async def main():
     print(result.final_output)
 ```
 
-1. OpenAI モデルの名前を直接設定します。
-2. [`Model`][agents.models.interface.Model] 実装を提供します。
+1.  OpenAI モデルの名前を直接設定します。
+2.  [`Model`][agents.models.interface.Model] 実装を提供します。
 
-エージェントで使用するモデルをさらに設定したい場合は、temperature などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡すことができます。
+エージェントで使用するモデルをさらに設定したい場合は、temperature などの任意のモデル設定パラメーターを提供する [`ModelSettings`][agents.models.interface.ModelSettings] を渡せます。
 
 ```python
 from agents import Agent, ModelSettings
@@ -305,19 +308,20 @@ english_agent = Agent(
 
 ## 高度な OpenAI Responses 設定
 
-OpenAI Responses 経路を使用していて、より詳細に制御したい場合は、`ModelSettings` から始めてください。
+OpenAI Responses パスを使用していて、より詳細な制御が必要な場合は、`ModelSettings` から始めてください。
 
 ### 一般的な高度な `ModelSettings` オプション
 
 OpenAI Responses API を使用している場合、いくつかのリクエストフィールドにはすでに直接対応する `ModelSettings` フィールドがあるため、それらに `extra_args` は不要です。
 
-- `parallel_tool_calls`: 同じターン内で複数のツール呼び出しを許可または禁止します。
-- `truncation`: コンテキストがあふれる場合に失敗する代わりに、Responses API が最も古い会話項目を削除できるようにするには `"auto"` を設定します。
-- `store`: 生成されたレスポンスを後で取得できるようサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存する後続ワークフローや、`store=False` の場合にローカル入力へフォールバックする必要があるセッション圧縮フローで重要です。
-- `prompt_cache_retention`: たとえば `"24h"` で、キャッシュされたプロンプト接頭辞をより長く保持します。
-- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、より豊富なレスポンスペイロードをリクエストします。
-- `top_logprobs`: 出力テキストの上位トークン logprobs をリクエストします。SDK は `message.output_text.logprobs` も自動的に追加します。
-- `retry`: モデル呼び出しに対する runner 管理のリトライ設定をオプトインします。[Runner 管理のリトライ](#runner-managed-retries)を参照してください。
+- `parallel_tool_calls`: 同じターン内の複数のツール呼び出しを許可または禁止します。
+- `truncation`: コンテキストがあふれる場合に失敗するのではなく、Responses API が最も古い会話アイテムを削除できるようにするには、`"auto"` を設定します。
+- `store`: 生成されたレスポンスを後で取得できるようにサーバー側に保存するかどうかを制御します。これは、レスポンス ID に依存する後続ワークフローや、`store=False` のときにローカル入力へのフォールバックが必要になる可能性があるセッション圧縮フローで重要です。
+- `context_management`: `compact_threshold` を使用した Responses 圧縮など、サーバー側のコンテキスト処理を設定します。
+- `prompt_cache_retention`: たとえば `"24h"` を使って、キャッシュされたプロンプトプレフィックスをより長く保持します。
+- `response_include`: `web_search_call.action.sources`、`file_search_call.results`、`reasoning.encrypted_content` など、よりリッチなレスポンスペイロードをリクエストします。
+- `top_logprobs`: 出力テキストの top-token logprobs をリクエストします。SDK は `message.output_text.logprobs` も自動的に追加します。
+- `retry`: モデル呼び出しに対する runner 管理の再試行設定を有効にします。[Runner 管理の再試行](#runner-managed-retries)を参照してください。
 
 ```python
 from agents import Agent, ModelSettings
@@ -329,6 +333,7 @@ research_agent = Agent(
         parallel_tool_calls=False,
         truncation="auto",
         store=True,
+        context_management=[{"type": "compaction", "compact_threshold": 200000}],
         prompt_cache_retention="24h",
         response_include=["web_search_call.action.sources"],
         top_logprobs=5,
@@ -336,13 +341,15 @@ research_agent = Agent(
 )
 ```
 
-`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側から取得できるようには保持しません。これはステートレスまたはゼロデータ保持スタイルのフローに役立ちますが、一方で、通常ならレスポンス ID を再利用する機能が、代わりにローカルで管理される状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていなかった場合、デフォルトの `"auto"` 圧縮経路を入力ベースの圧縮に切り替えます。[セッションガイド](../sessions/index.md#openai-responses-compaction-sessions)を参照してください。
+`store=False` を設定すると、Responses API はそのレスポンスを後でサーバー側から取得できるようには保持しません。これはステートレス、またはゼロデータ保持スタイルのフローに便利ですが、通常ならレスポンス ID を再利用する機能が、代わりにローカル管理の状態に依存する必要があることも意味します。たとえば、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] は、最後のレスポンスが保存されていない場合、デフォルトの `"auto"` 圧縮パスを入力ベースの圧縮に切り替えます。[Sessions ガイド](../sessions/index.md#openai-responses-compaction-sessions)を参照してください。
 
-### `extra_args` の渡し方
+サーバー側圧縮は、[`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] とは異なります。`context_management=[{"type": "compaction", "compact_threshold": ...}]` は各 Responses API リクエストと一緒に送信され、レンダリングされたコンテキストがしきい値を超えると、API はレスポンスの一部として圧縮アイテムを出力できます。`OpenAIResponsesCompactionSession` はターン間でスタンドアロンの `responses.compact` エンドポイントを呼び出し、ローカルセッション履歴を書き換えます。
 
-SDK がまだトップレベルで直接公開していない、プロバイダー固有または新しいリクエストフィールドが必要な場合は、`extra_args` を使用します。
+### `extra_args` の受け渡し
 
-また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。トップレベルで利用できない場合は、それらも `extra_args` で渡せます。
+プロバイダー固有、または SDK がまだトップレベルで直接公開していない新しいリクエストフィールドが必要な場合は、`extra_args` を使用します。
+
+また、OpenAI の Responses API を使用する場合、[他にもいくつかの任意パラメーター](https://platform.openai.com/docs/api-reference/responses/create)（例: `user`、`service_tier` など）があります。それらがトップレベルで利用できない場合は、`extra_args` を使用して渡すこともできます。同じリクエストフィールドを、直接の `ModelSettings` フィールドでも同時に設定しないでください。
 
 ```python
 from agents import Agent, ModelSettings
@@ -358,9 +365,9 @@ english_agent = Agent(
 )
 ```
 
-## Runner 管理のリトライ
+## Runner 管理の再試行
 
-リトライは実行時専用で、オプトインです。`ModelSettings(retry=...)` を設定し、リトライポリシーがリトライを選択しない限り、SDK は一般的なモデルリクエストをリトライしません。
+再試行はランタイム専用で、明示的な有効化が必要です。`ModelSettings(retry=...)` を設定し、再試行ポリシーが再試行を選択しない限り、SDK は一般的なモデルリクエストを再試行しません。
 
 ```python
 from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
@@ -394,79 +401,79 @@ agent = Agent(
 
 | フィールド | 型 | 注記 |
 | --- | --- | --- |
-| `max_retries` | `int | None` | 初回リクエスト後に許可されるリトライ試行回数です。 |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずにリトライする場合のデフォルト遅延戦略です。 |
-| `policy` | `RetryPolicy | None` | リトライするかどうかを決定するコールバックです。このフィールドは実行時専用で、シリアライズされません。 |
+| `max_retries` | `int | None` | 初回リクエスト後に許可される再試行回数。 |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | ポリシーが明示的な遅延を返さずに再試行する場合のデフォルトの遅延戦略。`backoff.max_delay` は、この計算された backoff 遅延のみを上限設定します。ポリシーから返された明示的な遅延や retry-after ヒントには上限を設定しません。 |
+| `policy` | `RetryPolicy | None` | 再試行するかどうかを決定するコールバック。このフィールドはランタイム専用で、シリアライズされません。 |
 
 </div>
 
-リトライポリシーは、次を含む [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。
+再試行ポリシーは、以下を含む [`RetryPolicyContext`][agents.retry.RetryPolicyContext] を受け取ります。
 
-- 試行を考慮した判断を行えるようにする `attempt` と `max_retries`。
-- ストリーミングと非ストリーミングの挙動を分岐できるようにする `stream`。
-- raw な検査用の `error`。
-- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの正規化された事実を表す `normalized`。
-- 基盤となるモデルアダプターがリトライガイダンスを提供できる場合の `provider_advice`。
+- `attempt` と `max_retries`。試行回数を考慮した判断を行えます。
+- `stream`。ストリーミングと非ストリーミングの動作を分岐できます。
+- `error`。生の内容を確認できます。
+- `status_code`、`retry_after`、`error_code`、`is_network_error`、`is_timeout`、`is_abort` などの正規化された情報。
+- 基盤のモデルアダプターが再試行ガイダンスを提供できる場合の `provider_advice`。
 
-ポリシーは次のいずれかを返せます。
+ポリシーは以下のいずれかを返せます。
 
-- 単純なリトライ判断としての `True` / `False`。
-- 遅延を上書きしたい場合や診断理由を添付したい場合の [`RetryDecision`][agents.retry.RetryDecision]。
+- 単純な再試行判断のための `True` / `False`。
+- 遅延を上書きしたり、診断理由を付加したりしたい場合の [`RetryDecision`][agents.retry.RetryDecision]。
 
-SDK は、`retry_policies` でそのまま使えるヘルパーをエクスポートしています。
+SDK は、`retry_policies` に既製のヘルパーをエクスポートしています。
 
-| ヘルパー | 挙動 |
+| ヘルパー | 動作 |
 | --- | --- |
 | `retry_policies.never()` | 常にオプトアウトします。 |
-| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーのリトライ助言に従います。 |
-| `retry_policies.network_error()` | 一時的なトランスポート障害やタイムアウト障害に一致します。 |
+| `retry_policies.provider_suggested()` | 利用可能な場合、プロバイダーの再試行助言に従います。 |
+| `retry_policies.network_error()` | 一時的なトランスポート障害とタイムアウト障害に一致します。 |
 | `retry_policies.http_status([...])` | 選択した HTTP ステータスコードに一致します。 |
-| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使用してリトライします。 |
-| `retry_policies.any(...)` | ネストされたポリシーのいずれかがオプトインした場合にリトライします。 |
-| `retry_policies.all(...)` | ネストされたすべてのポリシーがオプトインした場合にのみリトライします。 |
+| `retry_policies.retry_after()` | retry-after ヒントが利用可能な場合にのみ、その遅延を使用して再試行します。このヘルパーは retry-after 値を明示的なポリシー遅延として扱うため、`backoff.max_delay` はそれを上限設定しません。 |
+| `retry_policies.any(...)` | 入れ子のポリシーのいずれかが有効化した場合に再試行します。 |
+| `retry_policies.all(...)` | 入れ子のすべてのポリシーが有効化した場合にのみ再試行します。 |
 
-ポリシーを合成する場合、`provider_suggested()` は最も安全な最初の構成要素です。プロバイダーがそれらを区別できる場合、プロバイダーの拒否とリプレイ安全性の承認を保持するためです。
+ポリシーを合成する場合、`provider_suggested()` は最も安全な最初の構成要素です。プロバイダーがそれらを区別できる場合に、プロバイダーの拒否とリプレイ安全性の承認を保持するためです。
 
 ##### 安全境界
 
-一部の失敗は自動的には決してリトライされません。
+一部の障害は自動的には再試行されません。
 
-- 中断エラー。
-- プロバイダー助言がリプレイを安全でないと示すリクエスト。
-- 出力がすでに開始され、リプレイが安全でなくなるようなストリーミング実行。
+- 中止エラー。
+- プロバイダーからの助言がリプレイを安全でないと示すリクエスト。
+- リプレイが安全でなくなる形で出力がすでに開始された後のストリーミング実行。
 
-`previous_response_id` または `conversation_id` を使用するステートフルな後続リクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` のような非プロバイダー述語だけでは十分ではありません。リトライポリシーには、通常 `retry_policies.provider_suggested()` を通じて、プロバイダーからのリプレイ安全性の承認を含める必要があります。
+`previous_response_id` または `conversation_id` を使用するステートフルな後続リクエストも、より保守的に扱われます。これらのリクエストでは、`network_error()` や `http_status([500])` など、プロバイダー以外の述語だけでは十分ではありません。再試行ポリシーには、通常 `retry_policies.provider_suggested()` を通じて、プロバイダーからのリプレイ安全性の承認を含める必要があります。
 
 ##### Runner とエージェントのマージ動作
 
 `retry` は、runner レベルとエージェントレベルの `ModelSettings` の間でディープマージされます。
 
 - エージェントは `retry.max_retries` だけを上書きし、runner の `policy` を継承できます。
-- エージェントは `retry.backoff` の一部だけを上書きし、runner から兄弟の backoff フィールドを維持できます。
-- `policy` は実行時専用のため、シリアライズされた `ModelSettings` は `max_retries` と `backoff` を保持しますが、コールバック自体は省略します。
+- エージェントは `retry.backoff` の一部だけを上書きし、runner の兄弟 backoff フィールドを維持できます。
+- `policy` はランタイム専用であるため、シリアライズされた `ModelSettings` は `max_retries` と `backoff` を保持しますが、コールバック自体は省略します。
 
-より詳しい例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [アダプターを使用したリトライ例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)を参照してください。
+より完全な例については、[`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) と [アダプターベースの再試行例](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)を参照してください。
 
 ## 非 OpenAI プロバイダーのトラブルシューティング
 
 ### トレーシングクライアントエラー 401
 
-トレーシングに関連するエラーが発生する場合、これはトレースが OpenAI サーバーにアップロードされるためであり、OpenAI API キーを持っていないことが原因です。これを解決するには 3 つの選択肢があります。
+トレーシングに関連するエラーが発生する場合、トレースが OpenAI サーバーにアップロードされる一方で、OpenAI API キーがないことが原因です。これを解決するには、3 つの選択肢があります。
 
 1. トレーシングを完全に無効にする: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]。
-2. トレーシング用に OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものである必要があります。
-3. 非 OpenAI のトレースプロセッサーを使用する。[トレーシングドキュメント](../tracing.md#custom-tracing-processors)を参照してください。
+2. トレーシング用の OpenAI キーを設定する: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]。この API キーはトレースのアップロードにのみ使用され、[platform.openai.com](https://platform.openai.com/) のものである必要があります。
+3. 非 OpenAI トレースプロセッサーを使用する。[トレーシングドキュメント](../tracing.md#custom-tracing-processors)を参照してください。
 
-### Responses API サポート
+### Responses API のサポート
 
-SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだこれをサポートしていません。その結果、404 や類似の問題が発生する場合があります。解決するには 2 つの選択肢があります。
+SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダーはまだこれをサポートしていません。その結果、404 などの問題が発生する場合があります。解決するには、2 つの選択肢があります。
 
 1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api] を呼び出す。これは、環境変数で `OPENAI_API_KEY` と `OPENAI_BASE_URL` を設定している場合に機能します。
-2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。例は[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)にあります。
+2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] を使用する。[こちら](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)に例があります。
 
-### structured outputs サポート
+### structured outputs のサポート
 
-一部のモデルプロバイダーは、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生することがあります。
+一部のモデルプロバイダーは、[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) をサポートしていません。これにより、次のようなエラーが発生する場合があります。
 
 ```
 
@@ -474,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
 
 ```
 
-これは一部のモデルプロバイダーの制約です。JSON 出力はサポートしていますが、出力に使用する `json_schema` を指定できません。これについては修正に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダーに依存することを推奨します。そうしないと、不正な形式の JSON によってアプリが頻繁に壊れるためです。
+これは一部のモデルプロバイダーの制約です。JSON 出力はサポートしていますが、出力に使用する `json_schema` の指定は許可していません。この問題の修正に取り組んでいますが、JSON schema 出力をサポートしているプロバイダーに依存することを推奨します。そうしないと、不正な形式の JSON が原因でアプリが頻繁に壊れるためです。
 
 ## プロバイダー間でのモデルの混在
 
-モデルプロバイダー間の機能差を認識しておく必要があります。そうしないとエラーに遭遇する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。
+モデルプロバイダー間の機能差を理解しておく必要があります。そうしないと、エラーが発生する可能性があります。たとえば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしていますが、他の多くのプロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。
 
-- サポートされていない `tools` を、それを理解しないプロバイダーに送信しないでください
-- テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外してください
-- structured JSON 出力をサポートしていないプロバイダーは、ときどき無効な JSON を生成することに注意してください。
+-   サポートされていない `tools` を、それらを理解しないプロバイダーに送信しないでください
+-   テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外してください
+-   structured JSON 出力をサポートしていないプロバイダーは、無効な JSON を生成することがある点に注意してください。
 
-## サードパーティ製アダプター
+## サードパーティアダプター
 
-サードパーティ製アダプターは、SDK の組み込みプロバイダー統合ポイントだけでは不十分な場合にのみ使用してください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 経路を優先してください。サードパーティ製アダプターは、OpenAI モデルと非 OpenAI プロバイダーを組み合わせる必要がある場合、または組み込み経路では提供されないアダプター管理のプロバイダーカバレッジやルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に追加の互換性レイヤーを加えるため、機能サポートとリクエストの意味論はプロバイダーによって異なる場合があります。SDK には現在、ベストエフォートのベータ版アダプター統合として Any-LLM と LiteLLM が含まれています。
+SDK の組み込みプロバイダー統合ポイントで十分でない場合にのみ、サードパーティアダプターを使用してください。この SDK で OpenAI モデルのみを使用している場合は、Any-LLM や LiteLLM ではなく、組み込みの [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] パスを優先してください。サードパーティアダプターは、OpenAI モデルと非 OpenAI プロバイダーを組み合わせる必要がある場合、または組み込みパスでは提供されないアダプター管理のプロバイダー対応範囲やルーティングが必要な場合のためのものです。アダプターは SDK と上流のモデルプロバイダーの間に別の互換性レイヤーを追加するため、機能サポートとリクエストセマンティクスはプロバイダーによって異なる場合があります。SDK には現在、Any-LLM と LiteLLM がベストエフォートのベータ版アダプター統合として含まれています。
 
 ### Any-LLM
 
-Any-LLM サポートは、Any-LLM が管理するプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。
+Any-LLM のサポートは、Any-LLM 管理のプロバイダー対応範囲やルーティングが必要な場合向けに、ベストエフォートのベータ版として含まれています。
 
-上流プロバイダーの経路に応じて、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換レイヤーを使用する場合があります。
+上流プロバイダーパスによって、Any-LLM は Responses API、Chat Completions 互換 API、またはプロバイダー固有の互換性レイヤーを使用する場合があります。
 
-Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用したり、`AnyLLMModel` を直接インスタンス化したり、実行スコープで `AnyLLMProvider` を使用したりできます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` の構築時に `api="responses"` または `api="chat_completions"` を渡してください。
+Any-LLM が必要な場合は、`openai-agents[any-llm]` をインストールし、[`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) または [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py) から始めてください。[`MultiProvider`][agents.MultiProvider] で `any-llm/...` モデル名を使用するか、`AnyLLMModel` を直接インスタンス化するか、実行スコープで `AnyLLMProvider` を使用できます。モデルサーフェスを明示的に固定する必要がある場合は、`AnyLLMModel` を構築するときに `api="responses"` または `api="chat_completions"` を渡します。
 
-Any-LLM は引き続きサードパーティ製アダプターレイヤーであるため、プロバイダーの依存関係と機能ギャップは SDK ではなく、上流の Any-LLM によって定義されます。利用メトリクスは、上流プロバイダーが返す場合に自動的に伝播されますが、ストリーミングされる Chat Completions バックエンドでは、使用量チャンクを出力する前に `ModelSettings(include_usage=True)` が必要な場合があります。structured outputs、ツール呼び出し、使用量レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
+Any-LLM はサードパーティアダプターレイヤーであり続けるため、プロバイダー依存関係と機能ギャップは SDK ではなく Any-LLM によって上流で定義されます。使用状況メトリクスは、上流プロバイダーが返す場合に自動的に伝播されますが、ストリーミング Chat Completions バックエンドでは、usage chunks を出力する前に `ModelSettings(include_usage=True)` が必要になる場合があります。structured outputs、ツール呼び出し、使用状況レポート、または Responses 固有の動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
 
 ### LiteLLM
 
-LiteLLM サポートは、LiteLLM 固有のプロバイダーカバレッジやルーティングが必要な場合のために、ベストエフォートのベータ版として含まれています。
+LiteLLM のサポートは、LiteLLM 固有のプロバイダー対応範囲やルーティングが必要な場合向けに、ベストエフォートのベータ版として含まれています。
 
 LiteLLM が必要な場合は、`openai-agents[litellm]` をインストールし、[`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) または [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py) から始めてください。`litellm/...` モデル名を使用するか、[`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel] を直接インスタンス化できます。
 
-一部の LiteLLM ベースのプロバイダーは、デフォルトでは SDK の使用量メトリクスを設定しません。使用量レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡し、structured outputs、ツール呼び出し、使用量レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
+一部の LiteLLM ベースのプロバイダーは、デフォルトでは SDK の使用状況メトリクスを設定しません。使用状況レポートが必要な場合は、`ModelSettings(include_usage=True)` を渡し、structured outputs、ツール呼び出し、使用状況レポート、またはアダプター固有のルーティング動作に依存する場合は、デプロイ予定の正確なプロバイダーバックエンドを検証してください。

docs/ja/models/litellm.md

@@ -8,6 +8,6 @@ search:
   window.location.replace("../#third-party-adapters");
 </script>
 
-このページは [Models の Third-party adapters セクション](index.md#third-party-adapters)に移動しました。
+このページは [Models のサードパーティアダプターセクション](index.md#third-party-adapters) に移動しました。
 
 自動的にリダイレクトされない場合は、上記のリンクを使用してください。

docs/ja/multi_agent.md

@@ -4,61 +4,61 @@ search:
 ---
 # エージェントオーケストレーション
 
-オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントが、どの順序で実行され、次に何が起こるかをどのように決定するか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります。
+オーケストレーションとは、アプリ内でのエージェントの流れを指します。どのエージェントを、どの順序で実行し、次に何が起こるかをどのように決定するか、ということです。エージェントをオーケストレーションする主な方法は 2 つあります：
 
-1. LLM に意思決定させる: LLM の知性を使って計画・推論を行い、それに基づいてどのステップを取るかを決定します。
-2. コードでオーケストレーションする: コードによってエージェントの流れを決定します。
+1. LLM に判断を任せる：LLM の知能を使って計画と推論を行い、それに基づいて取る手順を決定します。
+2. コードによるオーケストレーション：コードでエージェントの流れを決定します。
 
-これらのパターンは組み合わせて使えます。それぞれにトレードオフがあり、以下で説明します。
+これらのパターンは組み合わせることができます。それぞれにトレードオフがあり、以下で説明します。
 
 ## LLM によるオーケストレーション
 
-エージェントは、instructions、tools、ハンドオフを備えた LLM です。つまり、オープンエンドなタスクが与えられた場合、LLM はそのタスクへの取り組み方を自律的に計画でき、tools を使ってアクションを実行しデータを取得し、ハンドオフを使ってサブエージェントにタスクを委譲できます。たとえば、リサーチエージェントには次のようなツールを備えられます。
+エージェントとは、instructions、tools、ハンドオフを備えた LLM です。つまり、自由度の高いタスクが与えられた場合、LLM は、tools を使ってアクションを実行しデータを取得し、ハンドオフを使ってサブエージェントにタスクを委任しながら、そのタスクへの取り組み方を自律的に計画できます。たとえば、リサーチエージェントには次のようなツールを備えられます：
 
--   オンライン情報を見つけるための Web 検索
+-   オンラインで情報を見つけるための Web 検索
 -   独自データや接続先を検索するためのファイル検索と取得
--   コンピュータ上でアクションを実行するためのコンピュータ操作
+-   コンピューター上でアクションを実行するためのコンピュータ操作
 -   データ分析を行うためのコード実行
--   計画、レポート作成などに優れた専門エージェントへのハンドオフ
+-   計画、レポート作成などに優れた専門エージェントへのハンドオフ。
 
-### SDK の中核パターン
+### コア SDK パターン
 
-Python SDK では、次の 2 つのオーケストレーションパターンが最もよく使われます。
+Python SDK では、次の 2 つのオーケストレーションパターンが最もよく登場します：
 
-| パターン | 仕組み | 最適な場面 |
+| パターン | 仕組み | 最適な場合 |
 | --- | --- | --- |
-| Agents as tools | マネージャーエージェントが会話の制御を維持し、`Agent.as_tool()` を通じて専門エージェントを呼び出します。 | 1 つのエージェントに最終回答を担わせたい、複数の専門家の出力を統合したい、または共通のガードレールを 1 か所で適用したい場合。 |
-| ハンドオフ | トリアージエージェントが会話を専門エージェントへ振り分け、その専門エージェントがそのターンの残りでアクティブなエージェントになります。 | 専門エージェントに直接応答させたい、プロンプトを集中させたい、またはマネージャーが結果を説明せずに instructions を切り替えたい場合。 |
+| Agents as tools | マネージャーエージェントが会話の制御を維持し、`Agent.as_tool()` を通じて専門エージェントを呼び出します。 | 1 つのエージェントに最終回答を担わせたい場合、複数の専門エージェントからの出力を統合したい場合、または共通のガードレールを 1 か所で適用したい場合。 |
+| ハンドオフ | トリアージエージェントが会話を専門エージェントにルーティングし、その専門エージェントがそのターンの残りでアクティブなエージェントになります。 | 専門エージェントに直接応答させたい場合、プロンプトを焦点の絞られた状態に保ちたい場合、またはマネージャーが結果を説明することなく instructions を切り替えたい場合。 |
 
-専門エージェントが限定的なサブタスクを支援すべきで、ユーザー向け会話を引き継ぐべきではない場合は **agents as tools** を使います。ルーティング自体がワークフローの一部であり、選ばれた専門エージェントに次のやり取りを担わせたい場合は **handoffs** を使います。
+専門エージェントが範囲の限定されたサブタスクを支援するべきだが、ユーザー向けの会話を引き継ぐべきではない場合は、 **agents as tools** を使用します。ルーティング自体がワークフローの一部であり、選ばれた専門エージェントにインタラクションの次の部分を担わせたい場合は、 **ハンドオフ** を使用します。
 
-2 つを組み合わせることもできます。トリアージエージェントが専門エージェントにハンドオフし、その専門エージェントがさらに限定的なサブタスクのために他のエージェントをツールとして呼び出すことも可能です。
+この 2 つを組み合わせることもできます。トリアージエージェントが専門エージェントにハンドオフし、その専門エージェントがさらに狭いサブタスクのために他のエージェントをツールとして呼び出すこともできます。
 
-このパターンは、タスクがオープンエンドで、LLM の知性に依存したい場合に非常に有効です。ここで最も重要な戦術は次のとおりです。
+このパターンは、タスクの自由度が高く、LLM の知能に頼りたい場合に最適です。ここで最も重要な戦術は次のとおりです：
 
-1. 良いプロンプトに投資する。どのツールが利用可能か、どう使うか、どのパラメーター範囲内で動作すべきかを明確にします。
-2. アプリを監視し、反復改善する。どこで問題が起こるかを確認し、プロンプトを改善します。
-3. エージェントに内省と改善を許可する。たとえば、ループで実行して自己批評させる、またはエラーメッセージを与えて改善させます。
-4. どんなタスクにも対応する汎用エージェントを期待するより、1 つのタスクに優れた専門エージェントを用意します。
-5. [evals](https://platform.openai.com/docs/guides/evals) に投資する。これによりエージェントを改善するための訓練ができ、タスク性能を向上させられます。
+1. 優れたプロンプトに投資します。利用できるツール、その使い方、そしてエージェントが従うべきパラメーターを明確にします。
+2. アプリを監視し、反復改善します。どこで問題が起こるかを確認し、プロンプトを改善します。
+3. エージェントが内省して改善できるようにします。たとえば、ループ内で実行して自己批評させる、またはエラーメッセージを提供して改善させます。
+4. 何でも得意であることを期待される汎用エージェントではなく、1 つのタスクに秀でた専門エージェントを用意します。
+5. [evals](https://platform.openai.com/docs/guides/evals) に投資します。これにより、エージェントをトレーニングして改善し、タスクの遂行能力を高めることができます。
 
-このスタイルのオーケストレーションを支える SDK の基本コンポーネントを確認したい場合は、[tools](tools.md)、[handoffs](handoffs.md)、[running agents](running_agents.md) から始めてください。
+このスタイルのオーケストレーションを支えるコア SDK の基本コンポーネントを知りたい場合は、[ツール](tools.md)、[ハンドオフ](handoffs.md)、[エージェントの実行](running_agents.md) から始めてください。
 
 ## コードによるオーケストレーション
 
-LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度・コスト・性能の面でタスクをより決定的で予測可能にします。ここで一般的なパターンは次のとおりです。
+LLM によるオーケストレーションは強力ですが、コードによるオーケストレーションは、速度、コスト、パフォーマンスの観点でタスクをより決定論的で予測可能にします。ここでの一般的なパターンは次のとおりです：
 
--   [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使い、コードで検査可能な適切な形式のデータを生成する。たとえば、タスクをいくつかのカテゴリーに分類するようエージェントに求め、そのカテゴリーに基づいて次のエージェントを選択できます。
--   1 つの出力を次の入力に変換して複数エージェントを連結する。ブログ記事執筆のようなタスクを、リサーチ、アウトライン作成、記事執筆、批評、改善という一連のステップに分解できます。
--   評価とフィードバックを行うエージェントと組み合わせて、タスク実行エージェントを `while` ループで実行し、評価側が出力が特定の基準を満たしたと言うまで続ける。
--   複数エージェントを並列実行する。たとえば `asyncio.gather` のような Python の基本機能を使います。これは、相互依存しない複数タスクがある場合の高速化に有用です。
+-   [structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使って、コードで検査できる適切な形式のデータを生成します。たとえば、エージェントにタスクをいくつかのカテゴリーに分類させ、そのカテゴリーに基づいて次のエージェントを選択できます。
+-   複数のエージェントをチェーンし、あるエージェントの出力を次のエージェントの入力に変換します。ブログ記事を書くようなタスクを一連のステップに分解できます - リサーチする、アウトラインを書く、ブログ記事を書く、批評し、それから改善します。
+-   タスクを実行するエージェントを `while` ループ内で、評価してフィードバックを提供するエージェントと一緒に実行し、評価者が出力が特定の基準を満たしたと言うまで続けます。
+-   複数のエージェントを並列に実行します。たとえば、`asyncio.gather` のような Python の基本コンポーネントを使います。これは、互いに依存しない複数のタスクがある場合に高速化に役立ちます。
 
-[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に多数のコード例があります。
+[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) には多数のコード例があります。
 
 ## 関連ガイド
 
--   構成パターンとエージェント設定については [Agents](agents.md)。
--   `Agent.as_tool()` とマネージャースタイルのオーケストレーションについては [Tools](tools.md#agents-as-tools)。
--   専門エージェント間の委譲については [Handoffs](handoffs.md)。
--   実行ごとのオーケストレーション制御と会話状態については [Running agents](running_agents.md)。
--   最小のエンドツーエンドなハンドオフ例については [Quickstart](quickstart.md)。
+-   構成パターンとエージェント設定については、[エージェント](agents.md) を参照してください。
+-   `Agent.as_tool()` とマネージャースタイルのオーケストレーションについては、[ツール](tools.md#agents-as-tools) を参照してください。
+-   専門エージェント間の委任については、[ハンドオフ](handoffs.md) を参照してください。
+-   実行ごとのオーケストレーション制御と会話状態については、[エージェントの実行](running_agents.md) を参照してください。
+-   最小限のエンドツーエンドのハンドオフ例については、[クイックスタート](quickstart.md) を参照してください。

docs/ja/quickstart.md

@@ -16,7 +16,7 @@ python -m venv .venv
 
 ### 仮想環境の有効化
 
-新しいターミナルセッションを開始するたびに行います。
+新しいターミナルセッションを開始するたびに行ってください。
 
 macOS または Linux の場合:
 
@@ -40,7 +40,7 @@ pip install openai-agents # or `uv add openai-agents`, etc
 
 まだ持っていない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。
 
-これらのコマンドは、現在のターミナルセッションにキーを設定します。
+以下のコマンドは、現在のターミナルセッションにキーを設定します。
 
 macOS または Linux の場合:
 
@@ -54,7 +54,7 @@ Windows PowerShell の場合:
 $env:OPENAI_API_KEY = "sk-..."
 ```
 
-Windows Command Prompt の場合:
+Windows コマンドプロンプトの場合:
 
 ```cmd
 set "OPENAI_API_KEY=sk-..."
@@ -62,7 +62,7 @@ set "OPENAI_API_KEY=sk-..."
 
 ## 最初のエージェントの作成
 
-エージェントは、instructions、名前、特定のモデルなどの任意の設定で定義されます。
+エージェントは、instructions、名前、および特定のモデルなどの任意の設定で定義します。
 
 ```python
 from agents import Agent
@@ -75,7 +75,7 @@ agent = Agent(
 
 ## 最初のエージェントの実行
 
-[`Runner`][agents.run.Runner] を使用してエージェントを実行し、[`RunResult`][agents.result.RunResult] を受け取ります。
+[`Runner`][agents.run.Runner] を使用してエージェントを実行し、[`RunResult`][agents.result.RunResult] を取得します。
 
 ```python
 import asyncio
@@ -94,23 +94,23 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-2 ターン目では、`result.to_input_list()` を `Runner.run(...)` に渡し戻すか、[session](sessions/index.md) をアタッチするか、`conversation_id` / `previous_response_id` で OpenAI のサーバー管理状態を再利用できます。[エージェントの実行](running_agents.md)ガイドでは、これらのアプローチを比較しています。
+2 回目のターンでは、`result.to_input_list()` を `Runner.run(...)` に戻して渡すか、[セッション](sessions/index.md)をアタッチするか、`conversation_id` / `previous_response_id` で OpenAI によりサーバー側で管理される状態を再利用できます。[エージェントの実行](running_agents.md)ガイドでは、これらのアプローチを比較しています。
 
-目安として、次のルールを使用してください。
+次の目安を使ってください:
 
-| したいこと... | まず使うもの... |
+| 実現したいこと... | まず使うもの... |
 | --- | --- |
 | 完全な手動制御とプロバイダー非依存の履歴 | `result.to_input_list()` |
 | SDK に履歴の読み込みと保存を任せる | [`session=...`](sessions/index.md) |
-| OpenAI が管理するサーバー側の継続 | `previous_response_id` または `conversation_id` |
+| OpenAI 管理のサーバー側継続 | `previous_response_id` または `conversation_id` |
 
-トレードオフと正確な動作については、[エージェントの実行](running_agents.md#choose-a-memory-strategy)を参照してください。
+トレードオフと正確な挙動については、[エージェントの実行](running_agents.md#choose-a-memory-strategy)を参照してください。
 
-タスクが主にプロンプト、ツール、会話状態で完結する場合は、通常の `Agent` と `Runner` を使用してください。エージェントが分離されたワークスペース内の実ファイルを検査または変更する必要がある場合は、[Sandbox エージェントクイックスタート](sandbox_agents.md)に進んでください。
+タスクが主にプロンプト、ツール、会話状態で完結する場合は、シンプルな `Agent` と `Runner` を使います。エージェントが分離されたワークスペース内の実ファイルを検査または変更する必要がある場合は、[Sandbox エージェントのクイックスタート](sandbox_agents.md)に進んでください。
 
 ## エージェントへのツールの付与
 
-エージェントにツールを与えて、情報を検索したりアクションを実行したりできます。
+エージェントにツールを与えることで、情報を調べたりアクションを実行したりできます。
 
 ```python
 import asyncio
@@ -144,14 +144,14 @@ if __name__ == "__main__":
 
 ## さらにいくつかのエージェントの追加
 
-マルチエージェントパターンを選ぶ前に、最終回答を誰が担当すべきかを決めます。
+マルチエージェントパターンを選ぶ前に、最終回答の主導権を誰が持つべきかを決めてください。
 
--   **ハンドオフ**: スペシャリストがそのターンの該当部分について会話を引き継ぎます。
+-   **ハンドオフ**: スペシャリストが、そのターンの該当部分について会話を引き継ぎます。
 -   **Agents as tools**: オーケストレーターが制御を維持し、スペシャリストをツールとして呼び出します。
 
-このクイックスタートでは、最初の例として最も短い **ハンドオフ** を続けます。マネージャースタイルのパターンについては、[エージェントオーケストレーション](multi_agent.md) と [ツール: Agents as tools](tools.md#agents-as-tools) を参照してください。
+このクイックスタートでは、最初の例として最も短いため、 **ハンドオフ** で続けます。マネージャースタイルのパターンについては、[エージェントオーケストレーション](multi_agent.md)と[ツール: agents as tools](tools.md#agents-as-tools)を参照してください。
 
-追加のエージェントも同じ方法で定義できます。`handoff_description` は、ルーティングエージェントに委任すべきタイミングについて追加のコンテキストを提供します。
+追加のエージェントも同じ方法で定義できます。`handoff_description` は、いつ委譲すべきかについて、ルーティングエージェントに追加のコンテキストを提供します。
 
 ```python
 from agents import Agent
@@ -171,7 +171,7 @@ math_tutor_agent = Agent(
 
 ## ハンドオフの定義
 
-エージェントでは、タスクの解決中に選択できる送信ハンドオフオプションの一覧を定義できます。
+エージェントには、タスクを解決する際に選択できるハンドオフ先の選択肢の一覧を定義できます。
 
 ```python
 triage_agent = Agent(
@@ -183,7 +183,7 @@ triage_agent = Agent(
 
 ## エージェントオーケストレーションの実行
 
-Runner は、個々のエージェントの実行、ハンドオフ、およびツール呼び出しを処理します。
+ランナーは、個々のエージェントの実行、すべてのハンドオフ、すべてのツール呼び出しを処理します。
 
 ```python
 import asyncio
@@ -205,21 +205,21 @@ if __name__ == "__main__":
 
 ## 参考コード例
 
-リポジトリには、同じ中核パターンの完全なスクリプトが含まれています。
+このリポジトリには、同じ主要パターンに対応する完全なスクリプトが含まれています:
 
--   [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) は最初の実行用です。
--   [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) は関数ツール用です。
--   [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) はマルチエージェントルーティング用です。
+-   [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) は最初の実行の例です。
+-   [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) は関数ツールの例です。
+-   [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) はマルチエージェントルーティングの例です。
 
 ## トレースの表示
 
-エージェントの実行中に何が起きたかを確認するには、[OpenAI Dashboard の Trace viewer](https://platform.openai.com/traces)に移動して、エージェント実行のトレースを表示します。
+エージェントの実行中に何が起きたかを確認するには、[OpenAI ダッシュボードのトレースビューアー](https://platform.openai.com/traces)に移動して、エージェント実行のトレースを表示してください。
 
 ## 次のステップ
 
-より複雑なエージェント的フローを構築する方法を学びます。
+より複雑なエージェント型フローの構築方法を学びましょう:
 
 -   [エージェント](agents.md)の設定方法について学びます。
--   [エージェントの実行](running_agents.md)と [sessions](sessions/index.md) について学びます。
+-   [エージェントの実行](running_agents.md)と[セッション](sessions/index.md)について学びます。
 -   作業を実際のワークスペース内で行う必要がある場合は、[Sandbox エージェント](sandbox_agents.md)について学びます。
 -   [ツール](tools.md)、[ガードレール](guardrails.md)、[モデル](models/index.md)について学びます。

docs/ja/realtime/guide.md

@@ -2,61 +2,61 @@
 search:
   exclude: true
 ---
-# Realtime エージェントガイド
+# リアルタイムエージェントガイド
 
-このガイドでは、 OpenAI Agents SDK の realtime レイヤーが OpenAI Realtime API にどのように対応しているか、そして Python SDK がその上にどのような追加動作を加えるかを説明します。
+このガイドでは、OpenAI Agents SDK のリアルタイムレイヤーが OpenAI Realtime API にどのように対応するか、また Python SDK がその上にどのような追加動作を提供するかを説明します。
 
-!!! warning "Beta 機能"
+!!! warning "ベータ機能"
 
-    Realtime エージェントは beta 段階です。実装の改善に伴い、破壊的変更が入る可能性があります。
+    リアルタイムエージェントはベータ版です。実装を改善する中で、破壊的変更が入る可能性があります。
 
-!!! note "開始ポイント"
+!!! note "はじめに"
 
-    デフォルトの Python パスを使いたい場合は、まず [quickstart](quickstart.md) を読んでください。アプリでサーバーサイド WebSocket と SIP のどちらを使うべきか判断したい場合は、[Realtime transport](transport.md) を読んでください。ブラウザの WebRTC transport は Python SDK の対象外です。
+    デフォルトの Python パスを使いたい場合は、まず [クイックスタート](quickstart.md) を読んでください。アプリでサーバー側 WebSocket と SIP のどちらを使用すべきか判断している場合は、[Realtime トランスポート](transport.md) を読んでください。ブラウザーの WebRTC トランスポートは Python SDK の一部ではありません。
 
 ## 概要
 
-Realtime エージェントは Realtime API への長時間接続を維持するため、モデルはテキストと音声を段階的に処理し、音声出力をストリーミングし、ツールを呼び出し、毎ターン新しいリクエストを再開せずに割り込みを処理できます。
+リアルタイムエージェントは、モデルがテキストと音声を段階的に処理し、音声出力をストリーミングし、ツールを呼び出し、各ターンで新しいリクエストを再開始することなく中断を処理できるように、Realtime API への長時間接続を開いたままにします。
 
-主な SDK コンポーネントは次のとおりです。
+主な SDK コンポーネントは次のとおりです：
 
--   **RealtimeAgent**: 1 つの realtime 専門エージェント向けの instructions、ツール、出力ガードレール、ハンドオフ
--   **RealtimeRunner**: 開始エージェントを realtime transport に接続するセッションファクトリー
--   **RealtimeSession**: 入力送信、イベント受信、履歴追跡、ツール実行を行うライブセッション
--   **RealtimeModel**: transport 抽象化。デフォルトは OpenAI のサーバーサイド WebSocket 実装です。
+-   **RealtimeAgent**: 1 つのリアルタイム専門エージェントに対する instructions、tools、出力ガードレール、ハンドオフ
+-   **RealtimeRunner**: 開始エージェントをリアルタイムトランスポートに接続するセッションファクトリー
+-   **RealtimeSession**: 入力を送信し、イベントを受信し、履歴を追跡し、ツールを実行するライブセッション
+-   **RealtimeModel**: トランスポート抽象化。デフォルトは OpenAI のサーバー側 WebSocket 実装です。
 
 ## セッションライフサイクル
 
-典型的な realtime セッションは次のようになります。
+一般的なリアルタイムセッションは次のようになります：
 
-1. 1 つ以上の `RealtimeAgent` を作成します。
-2. 開始エージェントで `RealtimeRunner` を作成します。
+1. `RealtimeAgent` を 1 つ以上作成します。
+2. 開始エージェントを指定して `RealtimeRunner` を作成します。
 3. `await runner.run()` を呼び出して `RealtimeSession` を取得します。
 4. `async with session:` または `await session.enter()` でセッションに入ります。
 5. `send_message()` または `send_audio()` でユーザー入力を送信します。
 6. 会話が終了するまでセッションイベントを反復処理します。
 
-テキスト専用 run とは異なり、`runner.run()` は最終 result を即時には生成しません。transport レイヤーと同期を保ちながら、ローカル履歴、バックグラウンドツール実行、ガードレール状態、アクティブなエージェント設定を保持するライブセッションオブジェクトを返します。
+テキストのみの実行とは異なり、`runner.run()` はすぐに最終的な実行結果を生成しません。ローカル履歴、バックグラウンドのツール実行、ガードレール状態、アクティブなエージェント設定をトランスポート層と同期し続けるライブセッションオブジェクトを返します。
 
-デフォルトでは、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用します。そのため、デフォルトの Python パスは Realtime API へのサーバーサイド WebSocket 接続です。別の `RealtimeModel` を渡した場合でも、同じセッションライフサイクルとエージェント機能が適用され、接続メカニズムのみ変更できます。
+デフォルトでは、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用するため、デフォルトの Python パスは Realtime API へのサーバー側 WebSocket 接続です。別の `RealtimeModel` を渡した場合でも、同じセッションライフサイクルとエージェント機能が適用され、接続の仕組みだけが変わることがあります。
 
-## エージェントとセッション設定
+## エージェントとセッションの設定
 
-`RealtimeAgent` は通常の `Agent` 型より意図的に範囲が狭くなっています。
+`RealtimeAgent` は、通常の `Agent` 型より意図的に範囲が絞られています：
 
--   モデル選択はエージェントごとではなくセッションレベルで設定します。
--   structured outputs はサポートされていません。
--   Voice は設定できますが、セッションがすでに音声を生成した後は変更できません。
--   Instructions、関数ツール、ハンドオフ、フック、出力ガードレールはすべて引き続き利用できます。
+-   モデルの選択はエージェント単位ではなく、セッションレベルで設定します。
+-   Structured outputs はサポートされていません。
+-   音声は設定できますが、セッションがすでに音声出力を生成した後は変更できません。
+-   instructions、関数ツール、ハンドオフ、フック、出力ガードレールはすべて引き続き機能します。
 
-`RealtimeSessionModelSettings` は、新しいネストされた `audio` 設定と古いフラットなエイリアスの両方をサポートします。新規コードではネスト形式を推奨し、新しい realtime エージェントには `gpt-realtime-1.5` から始めてください。
+`RealtimeSessionModelSettings` は、新しいネストされた `audio` 設定と、従来のフラットなエイリアスの両方をサポートします。新しいコードではネストされた形を推奨し、新しいリアルタイムエージェントでは `gpt-realtime-2` から始めてください：
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",
@@ -71,7 +71,7 @@ runner = RealtimeRunner(
 )
 ```
 
-有用なセッションレベル設定には次が含まれます。
+有用なセッションレベル設定には次のものがあります：
 
 -   `audio.input.format`, `audio.output.format`
 -   `audio.input.transcription`
@@ -83,7 +83,7 @@ runner = RealtimeRunner(
 -   `prompt`
 -   `tracing`
 
-`RealtimeRunner(config=...)` での有用な run レベル設定には次が含まれます。
+`RealtimeRunner(config=...)` の有用な実行レベル設定には次のものがあります：
 
 -   `async_tool_calls`
 -   `output_guardrails`
@@ -91,13 +91,13 @@ runner = RealtimeRunner(
 -   `tool_error_formatter`
 -   `tracing_disabled`
 
-型付きの完全な仕様は [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。
+型付きで利用できる全体のインターフェイスについては、[`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。
 
 ## 入力と出力
 
-### テキストと構造化ユーザーメッセージ
+### テキストと構造化されたユーザーメッセージ
 
-プレーンテキストまたは構造化 realtime メッセージには [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。
+プレーンテキストまたは構造化されたリアルタイムメッセージには、[`session.send_message()`][agents.realtime.session.RealtimeSession.send_message] を使用します。
 
 ```python
 from agents.realtime import RealtimeUserInputMessage
@@ -115,31 +115,31 @@ message: RealtimeUserInputMessage = {
 await session.send_message(message)
 ```
 
-構造化メッセージは、realtime 会話に画像入力を含める主要な方法です。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) の Web デモ例では、この方法で `input_image` メッセージを転送しています。
+構造化メッセージは、リアルタイム会話に画像入力を含めるための主な方法です。[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) のサンプル Web デモでは、この方法で `input_image` メッセージを転送しています。
 
 ### 音声入力
 
-raw 音声バイトをストリーミングするには [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用します。
+未加工の音声バイトをストリーミングするには、[`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用します：
 
 ```python
 await session.send_audio(audio_bytes)
 ```
 
-サーバーサイドの turn detection が無効な場合、ターン境界の指定はユーザー側の責任です。高レベルの簡易手段は次のとおりです。
+サーバー側のターン検出が無効な場合、ターン境界をマークする責任はあなたにあります。高レベルの便利な方法は次のとおりです：
 
 ```python
 await session.send_audio(audio_bytes, commit=True)
 ```
 
-より低レベルな制御が必要な場合は、基盤となる model transport を通じて `input_audio_buffer.commit` などの raw client event も送信できます。
+より低レベルの制御が必要な場合は、基盤となるモデルトランスポートを通じて `input_audio_buffer.commit` などの raw クライアントイベントを送信することもできます。
 
 ### 手動レスポンス制御
 
-`session.send_message()` は高レベルパスでユーザー入力を送信し、レスポンス開始も自動で行います。raw 音声バッファリングでは、すべての設定で同様に自動実行される **わけではありません** 。
+`session.send_message()` は高レベルのパスを使ってユーザー入力を送信し、レスポンスを開始します。raw 音声バッファリングは、すべての設定で同じことを自動的に行う **わけではありません**。
 
-Realtime API レベルでは、手動ターン制御は raw `session.update` で `turn_detection` をクリアし、その後 `input_audio_buffer.commit` と `response.create` を自分で送信することを意味します。
+Realtime API レベルでは、手動ターン制御とは、raw の `session.update` で `turn_detection` をクリアし、その後 `input_audio_buffer.commit` と `response.create` を自分で送信することを意味します。
 
-ターンを手動管理する場合は、model transport 経由で raw client event を送信できます。
+ターンを手動で管理している場合は、モデルトランスポートを通じて raw クライアントイベントを送信できます：
 
 ```python
 from agents.realtime.model_inputs import RealtimeModelSendRawMessage
@@ -153,19 +153,19 @@ await session.model.send_event(
 )
 ```
 
-このパターンは次の場合に有用です。
+このパターンは次の場合に有用です：
 
--   `turn_detection` が無効で、モデルがいつ応答するかを自分で決めたい場合
--   レスポンスをトリガーする前にユーザー入力を検査またはゲートしたい場合
--   out-of-band レスポンス向けにカスタムプロンプトが必要な場合
+-   `turn_detection` が無効で、モデルがいつ応答すべきかを自分で決めたい場合
+-   レスポンスをトリガーする前に、ユーザー入力を検査したり制御したりしたい場合
+-   帯域外レスポンス用のカスタムプロンプトが必要な場合
 
-[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) の SIP 例では、raw `response.create` を使って開始時の挨拶を強制しています。
+[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) の SIP 例では、冒頭の挨拶を強制するために raw の `response.create` を使用しています。
 
-## イベント、履歴、割り込み
+## イベント、履歴、中断
 
-`RealtimeSession` は高レベル SDK イベントを発行しつつ、必要時には raw model event も転送します。
+`RealtimeSession` は、必要に応じて raw モデルイベントも転送しつつ、より高レベルの SDK イベントを発行します。
 
-価値の高いセッションイベントには次が含まれます。
+特に有用なセッションイベントには次のものがあります：
 
 -   `audio`, `audio_end`, `audio_interrupted`
 -   `agent_start`, `agent_end`
@@ -177,21 +177,21 @@ await session.model.send_event(
 -   `error`
 -   `raw_model_event`
 
-UI 状態管理で特に有用なのは通常 `history_added` と `history_updated` です。これらは、ユーザーメッセージ、assistant メッセージ、ツール呼び出しを含むセッションのローカル履歴を `RealtimeItem` オブジェクトとして公開します。
+UI 状態に最も有用なイベントは通常 `history_added` と `history_updated` です。これらは、ユーザーメッセージ、アシスタントメッセージ、ツール呼び出しを含む、セッションのローカル履歴を `RealtimeItem` オブジェクトとして公開します。
 
-### 割り込みと再生追跡
+### 中断と再生追跡
 
-ユーザーが assistant を割り込んだ場合、セッションは `audio_interrupted` を発行し、サーバーサイド会話がユーザーの実際の聴取内容と一致するよう履歴を更新します。
+ユーザーがアシスタントを中断すると、セッションは `audio_interrupted` を発行し、サーバー側の会話がユーザーが実際に聞いた内容と一致するように履歴を更新します。
 
-低遅延のローカル再生では、デフォルトの再生トラッカーで十分なことが多いです。リモート再生や遅延再生のシナリオ、特に電話では、すべての生成音声がすでに聴取済みと仮定するのではなく、実際の再生進捗に基づいて割り込み切り詰めを行うために [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker] を使用してください。
+低遅延のローカル再生では、デフォルトの再生トラッカーで十分なことが多いです。リモート再生や遅延のある再生シナリオ、特にテレフォニーでは、生成された音声がすべてすでに聞かれたと仮定するのではなく、実際の再生進捗に基づいて中断時の切り詰めが行われるように [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker] を使用してください。
 
-[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) の Twilio 例はこのパターンを示しています。
+[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py) の Twilio 例は、このパターンを示しています。
 
 ## ツール、承認、ハンドオフ、ガードレール
 
 ### 関数ツール
 
-Realtime エージェントはライブ会話中の関数ツールをサポートします。
+リアルタイムエージェントは、ライブ会話中に関数ツールをサポートします：
 
 ```python
 from agents import function_tool
@@ -212,7 +212,7 @@ agent = RealtimeAgent(
 
 ### ツール承認
 
-関数ツールは、実行前に人間の承認を必要とするようにできます。その場合、セッションは `tool_approval_required` を発行し、`approve_tool_call()` または `reject_tool_call()` を呼び出すまでツール実行を一時停止します。
+関数ツールは、実行前に人間による承認を必要とする場合があります。その場合、セッションは `tool_approval_required` を発行し、`approve_tool_call()` または `reject_tool_call()` を呼び出すまでツール実行を一時停止します。
 
 ```python
 async for event in session:
@@ -220,11 +220,11 @@ async for event in session:
         await session.approve_tool_call(event.call_id)
 ```
 
-具体的なサーバーサイド承認ループは [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) を参照してください。human-in-the-loop ドキュメントでも [Human in the loop](../human_in_the_loop.md) でこのフローを参照しています。
+具体的なサーバー側の承認ループについては、[`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py) を参照してください。ヒューマンインザループのドキュメントでも、[ヒューマンインザループ](../human_in_the_loop.md) でこのフローを参照しています。
 
 ### ハンドオフ
 
-Realtime ハンドオフでは、あるエージェントがライブ会話を別の専門エージェントへ転送できます。
+リアルタイムハンドオフにより、あるエージェントがライブ会話を別の専門エージェントへ転送できます：
 
 ```python
 from agents.realtime import RealtimeAgent, realtime_handoff
@@ -241,11 +241,11 @@ main_agent = RealtimeAgent(
 )
 ```
 
-素の `RealtimeAgent` ハンドオフは自動ラップされ、`realtime_handoff(...)` では名前、説明、検証、コールバック、可用性をカスタマイズできます。Realtime ハンドオフは通常の handoff `input_filter` をサポートしません。
+`RealtimeAgent` をそのまま渡すハンドオフは自動的にラップされ、`realtime_handoff(...)` を使うと名前、説明、検証、コールバック、利用可否をカスタマイズできます。リアルタイムハンドオフは通常のハンドオフの `input_filter` をサポートしていません。
 
 ### ガードレール
 
-Realtime エージェントでサポートされるのは出力ガードレールのみです。これらは各部分 token ごとではなく、デバウンスされた transcript 蓄積に対して実行され、例外を送出する代わりに `guardrail_tripped` を発行します。
+リアルタイムエージェントでサポートされるのは出力ガードレールのみです。これらは部分トークンごとではなく、デバウンスされたトランスクリプトの蓄積に対して実行され、例外を発生させる代わりに `guardrail_tripped` を発行します。
 
 ```python
 from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail
@@ -265,11 +265,17 @@ agent = RealtimeAgent(
 )
 ```
 
+リアルタイム出力ガードレールがトリップすると、セッションはアクティブなレスポンスを中断し、
+`response.cancel` を強制し、`guardrail_tripped` を発行し、トリガーされた
+ガードレールの名前を含むフォローアップのユーザーメッセージを送信するため、モデルは代替レスポンスを生成できます。音声プレイヤーは引き続き
+`audio_interrupted` をリッスンしてローカル再生を即座に停止する必要があります。これは、ガードレールが
+デバウンスされたトランスクリプトテキストに対して実行され、トリップワイヤーが発火した時点で一部の音声がすでにバッファリングされている可能性があるためです。
+
 ## SIP とテレフォニー
 
-Python SDK には [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] による第一級の SIP 接続フローが含まれています。
+Python SDK には、[`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel] によるファーストクラスの SIP アタッチフローが含まれています。
 
-Realtime Calls API 経由で着信し、結果として得られる `call_id` にエージェントセッションを接続したい場合に使用します。
+Realtime Calls API 経由で着信があり、生成された `call_id` にエージェントセッションをアタッチしたい場合に使用します：
 
 ```python
 from agents.realtime import RealtimeRunner
@@ -286,20 +292,20 @@ async with await runner.run(
         ...
 ```
 
-まず通話を受け付ける必要があり、受け付けペイロードをエージェント由来のセッション設定に一致させたい場合は、`OpenAIRealtimeSIPModel.build_initial_session_payload(...)` を使用してください。完全なフローは [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) にあります。
+最初に通話を受け入れる必要があり、accept ペイロードをエージェントから導出されたセッション設定と一致させたい場合は、`OpenAIRealtimeSIPModel.build_initial_session_payload(...)` を使用してください。完全なフローは [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py) に示されています。
 
 ## 低レベルアクセスとカスタムエンドポイント
 
-`session.model` から基盤 transport オブジェクトにアクセスできます。
+`session.model` を通じて基盤となるトランスポートオブジェクトにアクセスできます。
 
-必要な場合に使用します。
+次が必要な場合に使用します：
 
 -   `session.model.add_listener(...)` によるカスタムリスナー
--   `response.create` や `session.update` などの raw client event
--   `model_config` 経由のカスタム `url`、`headers`、`api_key` 処理
--   既存 realtime 通話への `call_id` 接続
+-   `response.create` や `session.update` などの raw クライアントイベント
+-   `model_config` を通じたカスタムの `url`、`headers`、`api_key` 処理
+-   既存のリアルタイム通話への `call_id` アタッチ
 
-`RealtimeModelConfig` は次をサポートします。
+`RealtimeModelConfig` は次をサポートします：
 
 -   `api_key`
 -   `url`
@@ -308,9 +314,9 @@ async with await runner.run(
 -   `playback_tracker`
 -   `call_id`
 
-このリポジトリに含まれる `call_id` の例は SIP です。より広い Realtime API では一部のサーバーサイド制御フローにも `call_id` を使いますが、ここでは Python 例としては提供されていません。
+このリポジトリに同梱されている `call_id` の例は SIP です。より広範な Realtime API でも、一部のサーバー側制御フローで `call_id` が使用されますが、ここではそれらは Python のコード例としてパッケージ化されていません。
 
-Azure OpenAI に接続する場合は、 GA Realtime endpoint URL と明示的な headers を渡してください。例:
+Azure OpenAI に接続する場合は、GA Realtime エンドポイント URL と明示的なヘッダーを渡してください。例：
 
 ```python
 session = await runner.run(
@@ -321,7 +327,7 @@ session = await runner.run(
 )
 ```
 
-トークンベース認証では、`headers` に bearer token を使用します。
+トークンベースの認証では、`headers` にベアラートークンを使用します：
 
 ```python
 session = await runner.run(
@@ -332,12 +338,12 @@ session = await runner.run(
 )
 ```
 
-`headers` を渡した場合、SDK は `Authorization` を自動追加しません。realtime エージェントではレガシー beta パス（`/openai/realtime?api-version=...`）を避けてください。
+`headers` を渡した場合、SDK は `Authorization` を自動的に追加しません。リアルタイムエージェントでは、従来のベータパス（`/openai/realtime?api-version=...`）を避けてください。
 
 ## 参考資料
 
--   [Realtime transport](transport.md)
--   [Quickstart](quickstart.md)
--   [OpenAI Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/)
--   [OpenAI Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/)
+-   [Realtime トランスポート](transport.md)
+-   [クイックスタート](quickstart.md)
+-   [OpenAI Realtime 会話](https://developers.openai.com/api/docs/guides/realtime-conversations/)
+-   [OpenAI Realtime サーバー側制御](https://developers.openai.com/api/docs/guides/realtime-server-controls/)
 -   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)

docs/ja/realtime/quickstart.md

@@ -4,33 +4,33 @@ search:
 ---
 # クイックスタート
 
-Python SDK の Realtime エージェントは、WebSocket トランスポート経由の OpenAI Realtime API 上に構築された、サーバーサイドの低レイテンシなエージェントです。
+Python SDK のリアルタイムエージェントは、 WebSocket トランスポート経由の OpenAI Realtime API を基盤とする、サーバー側の低レイテンシエージェントです。
 
-!!! warning "Beta 機能"
+!!! warning "ベータ機能"
 
-    Realtime エージェントは beta です。実装の改善に伴い、破壊的変更が発生する可能性があります。
+    リアルタイムエージェントはベータ版です。実装を改善していく中で、破壊的変更が発生する可能性があります。
 
 !!! note "Python SDK の範囲"
 
-    Python SDK はブラウザー向けの WebRTC トランスポートを **提供しません** 。このページでは、サーバーサイド WebSocket 経由で Python が管理する realtime session のみを扱います。サーバーサイドのオーケストレーション、ツール、承認、テレフォニー統合にはこの SDK を使用してください。あわせて [Realtime transport](transport.md) も参照してください。
+    Python SDK はブラウザー向け WebRTC トランスポートを **提供しません** 。このページでは、サーバー側 WebSocket 上で Python が管理するリアルタイムセッションのみを扱います。この SDK は、サーバー側のオーケストレーション、ツール、承認、テレフォニー連携に使用してください。[リアルタイムトランスポート](transport.md) も参照してください。
 
 ## 前提条件
 
 -   Python 3.10 以上
 -   OpenAI API キー
--   OpenAI Agents SDK の基本的な理解
+-   OpenAI Agents SDK に関する基本的な知識
 
 ## インストール
 
-まだの場合は、OpenAI Agents SDK をインストールします。
+まだの場合は、 OpenAI Agents SDK をインストールしてください:
 
 ```bash
 pip install openai-agents
 ```
 
-## サーバーサイド realtime session の作成
+## サーバー側リアルタイムセッションの作成
 
-### 1. Realtime コンポーネントのインポート
+### 1. リアルタイムコンポーネントのインポート
 
 ```python
 import asyncio
@@ -38,7 +38,7 @@ import asyncio
 from agents.realtime import RealtimeAgent, RealtimeRunner
 ```
 
-### 2. 開始エージェントの定義
+### 2. 開始時のエージェントの定義
 
 ```python
 agent = RealtimeAgent(
@@ -47,16 +47,16 @@ agent = RealtimeAgent(
 )
 ```
 
-### 3. runner の設定
+### 3. ランナーの設定
 
-新しいコードでは、ネストされた `audio.input` / `audio.output` session 設定の形式を推奨します。新しい Realtime エージェントでは、`gpt-realtime-1.5` から始めてください。
+新しいコードでは、ネストされた `audio.input` / `audio.output` のセッション設定形式を推奨します。新しいリアルタイムエージェントでは、 `gpt-realtime-2` から始めてください。
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",
@@ -76,9 +76,9 @@ runner = RealtimeRunner(
 )
 ```
 
-### 4. session の開始と入力の送信
+### 4. セッションの開始と入力の送信
 
-`runner.run()` は `RealtimeSession` を返します。session context に入ると接続が開かれます。
+`runner.run()` は `RealtimeSession` を返します。セッションコンテキストに入ると接続が開かれます。
 
 ```python
 async def main() -> None:
@@ -104,59 +104,59 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-`session.send_message()` はプレーンな文字列または構造化された realtime message のいずれかを受け取ります。raw audio chunk には [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用してください。
+`session.send_message()` は、プレーンな文字列または構造化されたリアルタイムメッセージを受け付けます。未加工の音声チャンクには、 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio] を使用してください。
 
 ## このクイックスタートに含まれない内容
 
--   マイク入力とスピーカー再生のコード。[`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) の realtime コード例を参照してください。
--   SIP / テレフォニー接続フロー。[Realtime transport](transport.md) と [SIP セクション](guide.md#sip-and-telephony) を参照してください。
+-   マイクキャプチャとスピーカー再生のコード。リアルタイムのコード例については、 [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) を参照してください。
+-   SIP / テレフォニーのアタッチフロー。[リアルタイムトランスポート](transport.md) と [SIP セクション](guide.md#sip-and-telephony) を参照してください。
 
 ## 主要設定
 
-基本的な session が動作したら、次によく使われる設定は以下です。
+基本的なセッションが動作したら、多くの方が次に利用する設定は次のとおりです:
 
 -   `model_name`
 -   `audio.input.format`, `audio.output.format`
 -   `audio.input.transcription`
 -   `audio.input.noise_reduction`
--   自動ターン検出のための `audio.input.turn_detection`
+-   自動ターン検出用の `audio.input.turn_detection`
 -   `audio.output.voice`
 -   `tool_choice`, `prompt`, `tracing`
 -   `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter`
 
-`input_audio_format`、`output_audio_format`、`input_audio_transcription`、`turn_detection` などの古いフラットな別名も引き続き動作しますが、新しいコードではネストされた `audio` 設定を推奨します。
+`input_audio_format`、`output_audio_format`、`input_audio_transcription`、`turn_detection` などの古いフラットなエイリアスも引き続き機能しますが、新しいコードではネストされた `audio` 設定を推奨します。
 
-手動でターン制御を行う場合は、[Realtime agents guide](guide.md#manual-response-control) にある説明のとおり、raw の `session.update` / `input_audio_buffer.commit` / `response.create` フローを使用してください。
+手動のターン制御では、 [リアルタイムエージェントガイド](guide.md#manual-response-control) で説明されているように、 raw な `session.update` / `input_audio_buffer.commit` / `response.create` フローを使用してください。
 
-完全なスキーマについては、[`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。
+完全なスキーマについては、 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] と [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings] を参照してください。
 
 ## 接続オプション
 
-環境変数に API キーを設定します。
+環境で API キーを設定します:
 
 ```bash
 export OPENAI_API_KEY="your-api-key-here"
 ```
 
-または、session 開始時に直接渡します。
+または、セッションの開始時に直接渡します:
 
 ```python
 session = await runner.run(model_config={"api_key": "your-api-key"})
 ```
 
-`model_config` は次もサポートします。
+`model_config` は以下もサポートしています:
 
--   `url`: カスタム WebSocket endpoint
--   `headers`: カスタム request header
--   `call_id`: 既存の realtime call に接続します。このリポジトリで文書化されている接続フローは SIP です。
--   `playback_tracker`: ユーザーが実際に聞いた audio の量を報告します
+-   `url`: カスタム WebSocket エンドポイント
+-   `headers`: カスタムリクエストヘッダー
+-   `call_id`: 既存のリアルタイム通話にアタッチします。このリポジトリでは、ドキュメント化されているアタッチフローは SIP です。
+-   `playback_tracker`: ユーザーが実際に聞いた音声の量を報告します
 
-`headers` を明示的に渡した場合、SDK は `Authorization` header を **自動挿入しません** 。
+`headers` を明示的に渡す場合、 SDK は `Authorization` ヘッダーを **挿入しません** 。
 
-Azure OpenAI に接続する場合は、`model_config["url"]` に GA Realtime endpoint URL と明示的な headers を渡してください。realtime エージェントでは、legacy beta path (`/openai/realtime?api-version=...`) を避けてください。詳細は [Realtime agents guide](guide.md#low-level-access-and-custom-endpoints) を参照してください。
+Azure OpenAI に接続する場合は、 `model_config["url"]` に GA Realtime エンドポイント URL を指定し、ヘッダーを明示的に渡してください。リアルタイムエージェントでは、レガシーのベータパス (`/openai/realtime?api-version=...`) は避けてください。詳細は [リアルタイムエージェントガイド](guide.md#low-level-access-and-custom-endpoints) を参照してください。
 
 ## 次のステップ
 
--   サーバーサイド WebSocket と SIP のどちらを選ぶか判断するために [Realtime transport](transport.md) を読んでください。
--   ライフサイクル、構造化入力、承認、ハンドオフ、ガードレール、低レベル制御について [Realtime agents guide](guide.md) を読んでください。
--   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) のコード例を確認してください。
+-   サーバー側 WebSocket と SIP のどちらを選ぶかについては、 [リアルタイムトランスポート](transport.md) をお読みください。
+-   ライフサイクル、構造化入力、承認、ハンドオフ、ガードレール、低レベル制御については、 [リアルタイムエージェントガイド](guide.md) をお読みください。
+-   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) のコード例を参照してください。

docs/ja/realtime/transport.md

@@ -4,32 +4,32 @@ search:
 ---
 # Realtime トランスポート
 
-このページは、realtime エージェントを Python アプリケーションにどのように組み込むかを判断するために使用します。
+このページは、realtime エージェントを Python アプリケーションにどのように組み込むかを判断するために使用してください。
 
 !!! note "Python SDK の境界"
 
-    Python SDK にはブラウザー WebRTC トランスポートは **含まれていません** 。このページは Python SDK のトランスポート選択、つまりサーバーサイド WebSocket と SIP アタッチフローのみを対象としています。ブラウザー WebRTC は別のプラットフォームトピックであり、公式の [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) ガイドに記載されています。
+    Python SDK には、ブラウザー WebRTC トランスポートは含まれて **いません**。このページは、Python SDK のトランスポート選択肢であるサーバー側 WebSocket と SIP アタッチフローのみを扱います。ブラウザー WebRTC は別のプラットフォームトピックであり、公式の [WebRTC による Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) ガイドに記載されています。
 
 ## 判断ガイド
 
-| Goal | Start with | Why |
+| 目的 | はじめに | 理由 |
 | --- | --- | --- |
-| サーバー管理の realtime アプリを構築する | [Quickstart](quickstart.md) | デフォルトの Python パスは、`RealtimeRunner` で管理されるサーバーサイド WebSocket セッションです。 |
-| どのトランスポートとデプロイ形状を選ぶべきか理解する | このページ | トランスポートやデプロイ形状を確定する前に、このページを使用してください。 |
-| エージェントを電話または SIP 通話にアタッチする | [Realtime guide](guide.md) と [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | このリポジトリには、`call_id` で駆動する SIP アタッチフローが含まれています。 |
+| サーバー管理の realtime アプリを構築する | [クイックスタート](quickstart.md) | デフォルトの Python パスは、`RealtimeRunner` によって管理されるサーバー側 WebSocket セッションです。 |
+| 選択すべきトランスポートとデプロイ形態を理解する | このページ | トランスポートやデプロイ形態を決定する前に使用してください。 |
+| エージェントを電話または SIP 通話にアタッチする | [Realtime ガイド](guide.md) と [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | このリポジトリには、`call_id` によって駆動される SIP アタッチフローが含まれています。 |
 
-## サーバーサイド WebSocket というデフォルトの Python パス
+## デフォルトの Python パスであるサーバー側 WebSocket
 
-`RealtimeRunner` は、カスタム `RealtimeModel` を渡さない限り `OpenAIRealtimeWebSocketModel` を使用します。
+カスタム `RealtimeModel` を渡さない限り、`RealtimeRunner` は `OpenAIRealtimeWebSocketModel` を使用します。
 
 つまり、標準的な Python トポロジーは次のようになります。
 
 1. Python サービスが `RealtimeRunner` を作成します。
-2. `await runner.run()` は `RealtimeSession` を返します。
+2. `await runner.run()` が `RealtimeSession` を返します。
 3. セッションに入り、テキスト、構造化メッセージ、または音声を送信します。
 4. `RealtimeSessionEvent` 項目を消費し、音声またはトランスクリプトをアプリケーションに転送します。
 
-このトポロジーは、コアデモアプリ、CLI 例、Twilio Media Streams 例で使用されています。
+これは、コアデモアプリ、CLI の例、Twilio Media Streams の例で使用されているトポロジーです。
 
 -   [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app)
 -   [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli)
@@ -37,40 +37,40 @@ search:
 
 サーバーが音声パイプライン、ツール実行、承認フロー、履歴処理を管理する場合は、このパスを使用してください。
 
-## SIP アタッチというテレフォニーパス
+## テレフォニー向けパスとしての SIP アタッチ
 
-このリポジトリで文書化されているテレフォニーフローでは、Python SDK は `call_id` を介して既存の realtime 通話にアタッチします。
+このリポジトリで説明されているテレフォニーフローでは、Python SDK は `call_id` を介して既存の realtime 通話にアタッチします。
 
 このトポロジーは次のようになります。
 
 1. OpenAI が `realtime.call.incoming` などの webhook をサービスに送信します。
-2. サービスが Realtime Calls API を通じて通話を受け付けます。
+2. サービスが Realtime Calls API を通じて通話を受け入れます。
 3. Python サービスが `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())` を開始します。
 4. セッションは `model_config={"call_id": ...}` で接続し、その後は他の realtime セッションと同様にイベントを処理します。
 
-これは [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) で示されているトポロジーです。
+これは [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) に示されているトポロジーです。
 
-より広い Realtime API でも一部のサーバーサイド制御パターンで `call_id` を使用しますが、このリポジトリで提供されているアタッチ例は SIP です。
+より広範な Realtime API でも、一部のサーバー側制御パターンで `call_id` を使用しますが、このリポジトリに含まれるアタッチ例は SIP です。
 
-## この SDK の対象外であるブラウザー WebRTC
+## この SDK の範囲外であるブラウザー WebRTC
 
-アプリの主要クライアントが Realtime WebRTC を使用するブラウザーである場合:
+アプリの主なクライアントが Realtime WebRTC を使用するブラウザーである場合:
 
--   このリポジトリの Python SDK ドキュメントの対象外として扱ってください。
--   クライアントサイドフローとイベントモデルについては、公式の [Realtime API with WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc/) と [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) のドキュメントを使用してください。
--   ブラウザー WebRTC クライアントに加えてサイドバンドのサーバー接続が必要な場合は、公式の [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) ガイドを使用してください。
--   このリポジトリがブラウザーサイド `RTCPeerConnection` 抽象化や、すぐに使えるブラウザー WebRTC サンプルを提供することは期待しないでください。
+-   このリポジトリの Python SDK ドキュメントの範囲外として扱ってください。
+-   クライアント側のフローとイベントモデルについては、公式の [WebRTC による Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) および [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) ドキュメントを使用してください。
+-   ブラウザー WebRTC クライアントの上にサイドバンドのサーバー接続が必要な場合は、公式の [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) ガイドを使用してください。
+-   このリポジトリが、ブラウザー側の `RTCPeerConnection` 抽象化や、すぐに使えるブラウザー WebRTC サンプルを提供することは期待しないでください。
 
-このリポジトリには現在、ブラウザー WebRTC と Python サイドバンドを組み合わせた例も含まれていません。
+このリポジトリには、現在、ブラウザー WebRTC と Python サイドバンドを組み合わせた例も含まれていません。
 
 ## カスタムエンドポイントとアタッチポイント
 
-[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] のトランスポート設定インターフェースにより、デフォルトパスを調整できます。
+[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig] のトランスポート設定サーフェスを使用すると、デフォルトのパスを調整できます。
 
 -   `url`: WebSocket エンドポイントを上書きします
--   `headers`: Azure 認証ヘッダーなどの明示的なヘッダーを提供します
+-   `headers`: Azure 認証ヘッダーなどの明示的なヘッダーを指定します
 -   `api_key`: API キーを直接、またはコールバック経由で渡します
--   `call_id`: 既存の realtime 通話にアタッチします。このリポジトリで文書化されている例は SIP です。
--   `playback_tracker`: 割り込み処理のために実際の再生進行を報告します
+-   `call_id`: 既存の realtime 通話にアタッチします。このリポジトリで記載されている例は SIP です。
+-   `playback_tracker`: 割り込み処理のために実際の再生進捗を報告します
 
-トポロジーを選択した後の詳細なライフサイクルと機能インターフェースについては、[Realtime agents guide](guide.md) を参照してください。
+トポロジーを選択した後の詳細なライフサイクルと機能サーフェスについては、[Realtime エージェントガイド](guide.md) を参照してください。

docs/ja/release.md

@@ -4,30 +4,78 @@ search:
 ---
 # リリースプロセス / 変更履歴
 
-このプロジェクトは、`0.Y.Z` という形式を使うセマンティックバージョニングを少し変更したバージョンに従います。先頭の `0` は、SDK がまだ急速に進化していることを示します。各構成要素は次のように増やします。
+このプロジェクトは、形式 `0.Y.Z` を使用するセマンティックバージョニングを少し修正したものに従います。先頭の `0` は、SDK がまだ急速に進化中であることを示します。各構成要素は次のように増加させます:
 
-## マイナー（`Y`）バージョン
+## マイナー (`Y`) バージョン
 
-ベータとしてマークされていない公開インターフェイスに対する **破壊的変更** では、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には、破壊的変更が含まれる場合があります。
+ベータとしてマークされていない公開インターフェイスに対する **破壊的変更** の場合、マイナーバージョン `Y` を増やします。たとえば、`0.0.x` から `0.1.x` への移行には破壊的変更が含まれる可能性があります。
 
-破壊的変更を望まない場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。
+破壊的変更を避けたい場合は、プロジェクトで `0.0.x` バージョンに固定することをおすすめします。
 
-## パッチ（`Z`）バージョン
+## パッチ (`Z`) バージョン
 
-破壊的でない変更では、`Z` を増やします。
+非破壊的変更の場合は `Z` を増やします:
 
-- バグ修正
-- 新機能
-- プライベートインターフェイスへの変更
-- ベータ機能の更新
+-   バグ修正
+-   新機能
+-   非公開インターフェイスの変更
+-   ベータ機能の更新
 
 ## 破壊的変更の変更履歴
 
+### 0.17.0
+
+このバージョンでは、サンドボックスのローカルソースの実体化において、ソースパスが `Manifest.extra_path_grants` によってカバーされていない限り、`LocalFile.src` と `LocalDir.src` は実体化時の `base_dir` 内に収められます。`base_dir` は、マニフェストが適用される時点での SDK プロセスの現在の作業ディレクトリです。相対ローカルソースはそのディレクトリから解決され、絶対ローカルソースはすでにそのディレクトリ内にあるか、明示的な許可の配下にある必要があります。これによりローカルアーティファクトの境界に関する問題は解消されますが、そのベースディレクトリ外から信頼済みホストのファイルまたはディレクトリをサンドボックスワークスペースへ意図的にコピーするアプリケーションに影響する可能性があります。
+
+移行するには、信頼済みホストルートをマニフェストレベルで `SandboxPathGrant` により許可してください。サンドボックスがそれらのファイルを読み取るだけでよい場合は、読み取り専用にすることをおすすめします:
+
+```python
+from pathlib import Path
+
+from agents.sandbox import Manifest, SandboxPathGrant
+from agents.sandbox.entries import Dir, LocalDir
+
+# This is an absolute host path outside the SDK process base_dir.
+TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")
+
+manifest = Manifest(
+    extra_path_grants=(
+        # This host root is outside the SDK process base_dir, so the manifest must grant it.
+        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
+    ),
+    entries={
+        # No grant is needed for local sources that stay under the SDK process base_dir.
+        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
+        # This entry reads from the granted host root and copies it into the sandbox workspace.
+        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
+        # Dir creates a sandbox workspace directory; it does not read from the host filesystem.
+        "output": Dir(description="Generated artifacts."),
+    },
+)
+```
+
+`extra_path_grants` は信頼済みアプリケーション設定として扱ってください。アプリケーションがそれらのホストパスをすでに承認していない限り、モデル出力やその他の信頼できないマニフェスト入力から許可を設定しないでください。
+
+### 0.16.0
+
+このバージョンでは、SDK のデフォルトモデルが `gpt-4.1` ではなく `gpt-5.4-mini` になりました。これは、モデルを明示的に設定していないエージェントと実行に影響します。新しいデフォルトは GPT-5 モデルであるため、暗黙的なデフォルトモデル設定には `reasoning.effort="none"` や `verbosity="low"` などの GPT-5 デフォルトが含まれるようになりました。
+
+以前のデフォルトモデルの挙動を維持する必要がある場合は、エージェントまたは実行設定でモデルを明示的に設定するか、`OPENAI_DEFAULT_MODEL` 環境変数を設定してください:
+
+```python
+agent = Agent(name="Assistant", model="gpt-4.1")
+```
+
+主な変更点:
+
+-   `Runner.run`、`Runner.run_sync`、`Runner.run_streamed` は、ターン制限を無効にするために `max_turns=None` を受け取れるようになりました。
+-   サンドボックスワークスペースのハイドレーションは、ローカル、Docker、およびプロバイダーがバックするサンドボックス実装全体で、絶対シンボリックリンクターゲットを含む、アーカイブルートの外部を指すシンボリックリンクを含む tar アーカイブを拒否するようになりました。
+
 ### 0.15.0
 
-このバージョンでは、モデルの拒否は、空のテキスト出力として扱われたり、structured outputs では `MaxTurnsExceeded` になるまで実行ループが再試行されたりするのではなく、`ModelRefusalError` として明示的に表面化されるようになりました。
+このバージョンでは、モデルの拒否応答は、空のテキスト出力として扱われたり、structured outputs の場合に実行ループが `MaxTurnsExceeded` まで再試行したりするのではなく、`ModelRefusalError` として明示的に表面化されるようになりました。
 
-これは、以前に拒否のみのモデル応答が `final_output == ""` で完了することを期待していたコードに影響します。例外を発生させずに拒否を処理するには、`model_refusal` 実行エラーハンドラーを指定してください。
+これは、以前に拒否のみのモデル応答が `final_output == ""` で完了することを期待していたコードに影響します。例外を発生させずに拒否を処理するには、`model_refusal` 実行エラーハンドラーを提供してください:
 
 ```python
 result = Runner.run_sync(
@@ -37,81 +85,81 @@ result = Runner.run_sync(
 )
 ```
 
-structured outputs のエージェントでは、ハンドラーはエージェントの出力スキーマに一致する値を返すことができ、SDK は他の実行エラーハンドラーの最終出力と同様にそれを検証します。
+structured-output エージェントの場合、ハンドラーはエージェントの出力スキーマに一致する値を返すことができ、SDK は他の実行エラーハンドラーの最終出力と同様に検証します。
 
 ### 0.14.0
 
-このマイナーリリースでは **破壊的変更** は導入されませんが、主要な新しいベータ機能領域である Sandbox Agents に加え、ローカル、コンテナ化、ホスト環境全体でそれらを使用するために必要なランタイム、バックエンド、ドキュメントのサポートが追加されます。
+このマイナーリリースでは、破壊的変更は **導入しません** が、主要な新しいベータ機能領域である Sandbox エージェントに加え、ローカル、コンテナ化、ホスト環境全体でそれらを使用するために必要なランタイム、バックエンド、ドキュメントのサポートが追加されています。
 
-ハイライト:
+主な変更点:
 
-- `SandboxAgent`、`Manifest`、`SandboxRunConfig` を中心とする新しいベータ版のサンドボックスランタイムサーフェスを追加し、エージェントがファイル、ディレクトリ、Git リポジトリ、マウント、スナップショット、再開サポートを備えた永続的な分離ワークスペース内で動作できるようにしました。
-- `UnixLocalSandboxClient` と `DockerSandboxClient` によるローカルおよびコンテナ化開発向けのサンドボックス実行バックエンドを追加し、さらにオプションの extras を通じて Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 向けのホスト型プロバイダー統合を追加しました。
-- 将来の実行で以前の実行から得た教訓を再利用できるように、サンドボックスメモリサポートを追加しました。段階的な開示、マルチターングルーピング、設定可能な分離境界、S3 バックアップのワークフローを含む永続化メモリの例に対応しています。
-- ローカルおよび合成ワークスペースエントリー、S3/R2/GCS/Azure Blob Storage/S3 Files 向けのリモートストレージマウント、ポータブルスナップショット、`RunState`、`SandboxSessionState`、または保存済みスナップショットによる再開フローを含む、より広範なワークスペースと再開モデルを追加しました。
-- `examples/sandbox/` の下に、スキル、ハンドオフ、メモリ、プロバイダー固有のセットアップを使ったコーディングタスクや、コードレビュー、データルーム QA、Web サイトのクローン作成といったエンドツーエンドのワークフローを扱う、充実したサンドボックスの例とチュートリアルを追加しました。
-- サンドボックス対応のセッション準備、ケイパビリティバインディング、状態シリアライゼーション、統合トレーシング、プロンプトキャッシュキーのデフォルト、安全性を高めた機密 MCP 出力のリダクションにより、コアランタイムとトレーシングスタックを拡張しました。
+-   `SandboxAgent`、`Manifest`、`SandboxRunConfig` を中心とした新しいベータのサンドボックスランタイムサーフェスを追加しました。これにより、エージェントはファイル、ディレクトリ、Git リポジトリ、マウント、スナップショット、再開サポートを備えた永続的な隔離ワークスペース内で動作できます。
+-   `UnixLocalSandboxClient` と `DockerSandboxClient` によるローカルおよびコンテナ化開発向けのサンドボックス実行バックエンドに加え、任意の extras を通じた Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 向けのホスト型プロバイダー連携を追加しました。
+-   将来の実行が以前の実行から得た知見を再利用できるように、サンドボックスメモリサポートを追加しました。段階的開示、複数ターンのグループ化、設定可能な隔離境界、および S3 バックのワークフローを含む永続化メモリのコード例が含まれます。
+-   ローカルおよび合成ワークスペースエントリー、S3/R2/GCS/Azure Blob Storage/S3 Files 向けのリモートストレージマウント、移植可能なスナップショット、`RunState`、`SandboxSessionState`、または保存済みスナップショットによる再開フローを含む、より広範なワークスペースと再開モデルを追加しました。
+-   `examples/sandbox/` 配下に、充実したサンドボックスのコード例とチュートリアルを追加しました。スキル、ハンドオフ、メモリを用いたコーディングタスク、プロバイダー固有のセットアップ、コードレビュー、データルーム QA、Web サイトのクローン作成などのエンドツーエンドのワークフローを扱います。
+-   サンドボックス対応のセッション準備、ケイパビリティバインディング、状態のシリアライズ、統合トレーシング、プロンプトキャッシュキーのデフォルト、より安全な機密 MCP 出力のマスキングにより、コアランタイムとトレーシングスタックを拡張しました。
 
 ### 0.13.0
 
-このマイナーリリースでは **破壊的変更** は導入されませんが、注目すべき Realtime のデフォルト更新に加え、新しい MCP 機能とランタイム安定性の修正が含まれています。
+このマイナーリリースでは、破壊的変更は **導入しません** が、注目すべき Realtime のデフォルト更新に加え、新しい MCP 機能とランタイム安定性の修正が含まれます。
 
-ハイライト:
+主な変更点:
 
-- デフォルトの websocket Realtime モデルは `gpt-realtime-1.5` になりました。そのため、新しい Realtime エージェントのセットアップでは、追加の設定なしで新しいモデルが使われます。
-- `MCPServer` は `list_resources()`、`list_resource_templates()`、`read_resource()` を公開するようになり、`MCPServerStreamableHttp` は `session_id` を公開するようになりました。これにより、streamable HTTP セッションを再接続やステートレスワーカーをまたいで再開できます。
-- Chat Completions 統合では、`should_replay_reasoning_content` によって reasoning-content の再生をオプトインできるようになり、LiteLLM/DeepSeek などのアダプターにおけるプロバイダー固有の reasoning / ツール呼び出しの継続性が向上します。
-- `SQLAlchemySession` での同時初回書き込み、reasoning 除去後の孤立した assistant メッセージ ID を伴う圧縮リクエスト、`remove_all_tools()` が MCP/reasoning アイテムを残す問題、関数ツールのバッチ実行器における競合など、いくつかのランタイムおよびセッションのエッジケースを修正しました。
+-   デフォルトの WebSocket Realtime モデルは `gpt-realtime-1.5` になりました。そのため、新しい Realtime エージェントのセットアップでは、追加設定なしで新しいモデルが使用されます。
+-   `MCPServer` は `list_resources()`、`list_resource_templates()`、`read_resource()` を公開するようになりました。また、`MCPServerStreamableHttp` は `session_id` を公開するようになったため、ストリーム可能な HTTP セッションを再接続やステートレスワーカーをまたいで再開できます。
+-   Chat Completions 連携は、`should_replay_reasoning_content` によって推論コンテンツの再生をオプトインできるようになりました。これにより、LiteLLM/DeepSeek などのアダプターで、プロバイダー固有の推論 / ツール呼び出しの連続性が向上します。
+-   `SQLAlchemySession` における初回書き込みの同時実行、推論の除去後に孤立した assistant メッセージ ID を持つ圧縮リクエスト、`remove_all_tools()` が MCP/reasoning 項目を残す問題、関数ツールバッチ実行器の競合など、複数のランタイムおよびセッションのエッジケースを修正しました。
 
 ### 0.12.0
 
-このマイナーリリースでは **破壊的変更** は導入されません。主な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)を確認してください。
+このマイナーリリースでは、破壊的変更は **導入しません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)を確認してください。
 
 ### 0.11.0
 
-このマイナーリリースでは **破壊的変更** は導入されません。主な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)を確認してください。
+このマイナーリリースでは、破壊的変更は **導入しません**。主要な機能追加については、[リリースノート](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)を確認してください。
 
 ### 0.10.0
 
-このマイナーリリースでは **破壊的変更** は導入されませんが、OpenAI Responses ユーザー向けの重要な新機能領域として、Responses API の websocket トランスポートサポートが含まれています。
+このマイナーリリースでは、破壊的変更は **導入しません** が、OpenAI Responses ユーザー向けの重要な新機能領域である Responses API の WebSocket トランスポートサポートが含まれます。
 
-ハイライト:
+主な変更点:
 
-- OpenAI Responses モデル向けの websocket トランスポートサポートを追加しました（オプトインです。HTTP は引き続きデフォルトのトランスポートです）。
-- 共有された websocket 対応プロバイダーと `RunConfig` をマルチターン実行全体で再利用するための `responses_websocket_session()` ヘルパー / `ResponsesWebSocketSession` を追加しました。
-- ストリーミング、ツール、承認、フォローアップターンを扱う新しい websocket ストリーミングの例（`examples/basic/stream_ws.py`）を追加しました。
+-   OpenAI Responses モデル向けの WebSocket トランスポートサポートを追加しました（オプトインです。HTTP は引き続きデフォルトのトランスポートです）。
+-   複数ターンの実行全体で共有の WebSocket 対応プロバイダーと `RunConfig` を再利用するための `responses_websocket_session()` ヘルパー / `ResponsesWebSocketSession` を追加しました。
+-   ストリーミング、ツール、承認、フォローアップターンを扱う新しい WebSocket ストリーミングコード例（`examples/basic/stream_ws.py`）を追加しました。
 
 ### 0.9.0
 
-このバージョンでは、Python 3.9 はサポートされなくなりました。このメジャーバージョンは 3 か月前に EOL に達しているためです。より新しいランタイムバージョンにアップグレードしてください。
+このバージョンでは、このメジャーバージョンが 3 か月前に EOL に達したため、Python 3.9 はサポートされなくなりました。より新しいランタイムバージョンへアップグレードしてください。
 
-さらに、`Agent#as_tool()` メソッドから返される値の型ヒントが `Tool` から `FunctionTool` に狭められました。この変更が通常、破壊的な問題を引き起こすことはありませんが、コードがより広い共用体型に依存している場合は、側でいくつかの調整が必要になる可能性があります。
+さらに、`Agent#as_tool()` メソッドから返される値の型ヒントが、`Tool` から `FunctionTool` へ狭められました。この変更は通常、破壊的な問題を引き起こすことはありませんが、コードがより広い Union 型に依存している場合は、側でいくつか調整が必要になる可能性があります。
 
 ### 0.8.0
 
-このバージョンでは、2 つのランタイム動作の変更により移行作業が必要になる場合があります。
+このバージョンでは、2 つのランタイム挙動の変更により、移行作業が必要になる可能性があります:
 
-- **同期** Python callable をラップする関数ツールは、イベントループスレッドで実行されるのではなく、`asyncio.to_thread(...)` を介してワーカースレッドで実行されるようになりました。ツールロジックがスレッドローカル状態やスレッドアフィンなリソースに依存している場合は、非同期ツール実装へ移行するか、ツールコード内でスレッドアフィニティを明示してください。
-- ローカル MCP ツールの失敗処理は設定可能になり、デフォルトの動作では実行全体を失敗させる代わりに、モデルに見えるエラー出力を返せるようになりました。フェイルファストのセマンティクスに依存している場合は、`mcp_config={"failure_error_function": None}` を設定してください。サーバーレベルの `failure_error_function` 値はエージェントレベルの設定を上書きするため、明示的なハンドラーを持つ各ローカル MCP サーバーで `failure_error_function=None` を設定してください。
+-   **同期** Python 呼び出し可能オブジェクトをラップする関数ツールは、イベントループスレッドで実行されるのではなく、`asyncio.to_thread(...)` を介してワーカースレッドで実行されるようになりました。ツールのロジックがスレッドローカル状態やスレッドアフィンなリソースに依存している場合は、async ツール実装へ移行するか、ツールコード内でスレッドアフィニティを明示してください。
+-   ローカル MCP ツールの失敗処理は設定可能になり、デフォルトの挙動では実行全体を失敗させる代わりに、モデルから見えるエラー出力を返す場合があります。フェイルファストのセマンティクスに依存している場合は、`mcp_config={"failure_error_function": None}` を設定してください。サーバーレベルの `failure_error_function` 値はエージェントレベルの設定を上書きするため、明示的なハンドラーを持つ各ローカル MCP サーバーで `failure_error_function=None` を設定してください。
 
 ### 0.7.0
 
-このバージョンでは、既存のアプリケーションに影響する可能性がある動作変更がいくつかありました。
+このバージョンでは、既存のアプリケーションに影響する可能性がある挙動の変更がいくつかありました:
 
-- ネストされたハンドオフ履歴は **オプトイン** になりました（デフォルトでは無効）。v0.6.x のデフォルトのネスト動作に依存していた場合は、`RunConfig(nest_handoff_history=True)` を明示的に設定してください。
-- `gpt-5.1` / `gpt-5.2` のデフォルトの `reasoning.effort` は、`"none"` に変更されました（SDK のデフォルトで設定されていた以前のデフォルト `"low"` からの変更です）。プロンプトや品質 / コストプロファイルが `"low"` に依存していた場合は、`model_settings` で明示的に設定してください。
+-   ネストされたハンドオフ履歴は **オプトイン** になりました（デフォルトでは無効）。v0.6.x のデフォルトのネスト挙動に依存していた場合は、`RunConfig(nest_handoff_history=True)` を明示的に設定してください。
+-   `gpt-5.1` / `gpt-5.2` のデフォルトの `reasoning.effort` は、`"none"` に変更されました（SDK デフォルトで設定されていた以前のデフォルト `"low"` からの変更です）。プロンプトや品質 / コストのプロファイルが `"low"` に依存していた場合は、`model_settings` で明示的に設定してください。
 
 ### 0.6.0
 
-このバージョンでは、デフォルトのハンドオフ履歴は raw のユーザー / assistant ターンを公開するのではなく、単一の assistant メッセージにパッケージ化されるようになり、下流のエージェントに簡潔で予測可能な要約を提供します。
-- 既存の単一メッセージのハンドオフトランスクリプトは、デフォルトで `<CONVERSATION HISTORY>` ブロックの前に "For context, here is the conversation so far between the user and the previous agent:" で始まるようになり、下流のエージェントが明確にラベル付けされた要約を得られるようになりました。
+このバージョンでは、デフォルトのハンドオフ履歴は、生のユーザー / アシスタントターンを公開するのではなく、単一の assistant メッセージにまとめられるようになり、後続のエージェントに簡潔で予測可能な要約を提供します
+-   既存の単一メッセージのハンドオフトランスクリプトは、デフォルトで `<CONVERSATION HISTORY>` ブロックの前に "For context, here is the conversation so far between the user and the previous agent:" で始まるようになったため、後続のエージェントは明確なラベル付きの要約を受け取れます
 
 ### 0.5.0
 
-このバージョンでは、目に見える破壊的変更は導入されませんが、新機能と内部の重要な更新がいくつか含まれています。
+このバージョンでは、目に見える破壊的変更は導入されませんが、新機能と内部のいくつかの重要な更新が含まれます:
 
-- `RealtimeRunner` が [SIP プロトコル接続](https://platform.openai.com/docs/guides/realtime-sip)を処理するためのサポートを追加しました。
-- Python 3.14 互換性のため、`Runner#run_sync` の内部ロジックを大幅に改訂しました。
+-   `RealtimeRunner` が [SIP プロトコル接続](https://platform.openai.com/docs/guides/realtime-sip)を処理するためのサポートを追加しました
+-   Python 3.14 互換性のために、`Runner#run_sync` の内部ロジックを大幅に改訂しました
 
 ### 0.4.0
 
@@ -119,12 +167,12 @@ structured outputs のエージェントでは、ハンドラーはエージェ
 
 ### 0.3.0
 
-このバージョンでは、Realtime API サポートが gpt-realtime モデルとその API インターフェイス（GA バージョン）に移行します。
+このバージョンでは、Realtime API サポートは gpt-realtime モデルとその API インターフェイス（GA バージョン）へ移行します。
 
 ### 0.2.0
 
-このバージョンでは、以前は引数として `Agent` を受け取っていたいくつかの箇所が、代わりに `AgentBase` を受け取るようになりました。たとえば、MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型付け上の変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。
+このバージョンでは、以前は `Agent` を引数として受け取っていたいくつかの箇所が、代わりに `AgentBase` を引数として受け取るようになりました。たとえば、MCP サーバーの `list_tools()` 呼び出しです。これは純粋に型付け上の変更であり、引き続き `Agent` オブジェクトを受け取ります。更新するには、`Agent` を `AgentBase` に置き換えて型エラーを修正するだけです。
 
 ### 0.1.0
 
-このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` という 2 つの新しいパラメーターがあります。`MCPServer` をサブクラス化するすべてのクラスに、これらのパラメーターを追加する必要があります。
+このバージョンでは、[`MCPServer.list_tools()`][agents.mcp.server.MCPServer] に `run_context` と `agent` という 2 つの新しいパラメーターが追加されました。`MCPServer` をサブクラス化しているすべてのクラスに、これらのパラメーターを追加する必要があります。

docs/ja/repl.md

@@ -4,7 +4,7 @@ search:
 ---
 # REPL ユーティリティ
 
-この SDK は、ターミナル上でエージェントの挙動を素早く対話的にテストできる `run_demo_loop` を提供します。
+SDK は、ターミナルでエージェントの動作を直接すばやく対話的にテストするための `run_demo_loop` を提供します。
 
 
 ```python
@@ -19,6 +19,6 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-`run_demo_loop` はループでユーザー入力を促し、ターン間で会話履歴を保持します。デフォルトでは、生成されたモデル出力をストリーミングします。上記の例を実行すると、`run_demo_loop` は対話型のチャットセッションを開始します。入力を継続的に求め、これまでの会話履歴全体を保持することで（エージェントが何について話したかを把握できます）、生成と同時にエージェントの応答をリアルタイムで自動的にストリーミングします。
+`run_demo_loop` はループ内でユーザー入力を求め、ターン間の会話履歴を保持します。デフォルトでは、生成されるモデル出力をストリーミングします。上記の例を実行すると、run_demo_loop は対話型チャットセッションを開始します。入力を継続的に求め、ターン間の会話履歴全体を記憶し（そのためエージェントはこれまでに話し合われた内容を把握できます）、エージェントの応答が生成されるとリアルタイムで自動的にストリーミングします。
 
-このチャットセッションを終了するには、`quit` または `exit` と入力して Enter を押すか、`Ctrl-D` のキーボードショートカットを使用します。
+このチャットセッションを終了するには、単に `quit` または `exit` と入力して Enter キーを押すか、`Ctrl-D` キーボードショートカットを使用します。

docs/ja/results.md

@@ -4,81 +4,81 @@ search:
 ---
 # 実行結果
 
-`Runner.run` メソッドを呼び出すと、2 種類の実行結果タイプのいずれかを受け取ります。
+`Runner.run` メソッドを呼び出すと、次の 2 つの実行結果型のいずれかを受け取ります。
 
-- [`RunResult`][agents.result.RunResult]（`Runner.run(...)` または `Runner.run_sync(...)` から）
-- [`RunResultStreaming`][agents.result.RunResultStreaming]（`Runner.run_streamed(...)` から）
+-   `Runner.run(...)` または `Runner.run_sync(...)` からの [`RunResult`][agents.result.RunResult]
+-   `Runner.run_streamed(...)` からの [`RunResultStreaming`][agents.result.RunResultStreaming]
 
 どちらも [`RunResultBase`][agents.result.RunResultBase] を継承しており、`final_output`、`new_items`、`last_agent`、`raw_responses`、`to_state()` などの共通の実行結果サーフェスを公開します。
 
-`RunResultStreaming` は、[`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete]、[`cancel(...)`][agents.result.RunResultStreaming.cancel] など、ストリーミング固有の制御を追加します。
+`RunResultStreaming` は、[`stream_events()`][agents.result.RunResultStreaming.stream_events]、[`current_agent`][agents.result.RunResultStreaming.current_agent]、[`is_complete`][agents.result.RunResultStreaming.is_complete]、[`cancel(...)`][agents.result.RunResultStreaming.cancel] など、ストリーミング固有の制御機能を追加します。
 
 ## 適切な実行結果サーフェスの選択
 
-ほとんどのアプリケーションでは、いくつかの実行結果プロパティまたはヘルパーだけが必要です。
+ほとんどのアプリケーションでは、いくつかの実行結果プロパティまたはヘルパーだけで十分です。
 
-| 必要なもの | 使用するもの |
+| 必要なもの... | 使用するもの |
 | --- | --- |
 | ユーザーに表示する最終回答 | `final_output` |
-| 完全なローカルトランスクリプトを含む、再生可能な次ターン入力リスト | `to_input_list()` |
-| エージェント、ツール、ハンドオフ、承認メタデータを含む豊富な実行項目 | `new_items` |
+| 完全なローカルトランスクリプトを含む、リプレイ可能な次ターン入力リスト | `to_input_list()` |
+| エージェント、ツール、ハンドオフ、承認メタデータを含む詳細な実行項目 | `new_items` |
 | 通常、次のユーザーターンを処理すべきエージェント | `last_agent` |
-| `previous_response_id` による OpenAI Responses API のチェーン | `last_response_id` |
-| 保留中の承認と再開可能なスナップショット | `interruptions` と `to_state()` |
+| `previous_response_id` による OpenAI Responses API チェーン | `last_response_id` |
+| 保留中の承認と再開可能なスナップショット | `interruptions` and `to_state()` |
 | 現在のネストされた `Agent.as_tool()` 呼び出しに関するメタデータ | `agent_tool_invocation` |
-| raw モデル呼び出しまたはガードレール診断 | `raw_responses` とガードレール実行結果配列 |
+| raw モデル呼び出しまたはガードレール診断 | `raw_responses` and the guardrail result arrays |
 
 ## 最終出力
 
 [`final_output`][agents.result.RunResultBase.final_output] プロパティには、最後に実行されたエージェントの最終出力が含まれます。これは次のいずれかです。
 
-- 最後のエージェントに `output_type` が定義されていなかった場合は `str`
-- 最後のエージェントに出力タイプが定義されていた場合は `last_agent.output_type` 型のオブジェクト
-- たとえば承認中断で一時停止したために、最終出力が生成される前に実行が停止した場合は `None`
+-   最後のエージェントに `output_type` が定義されていなかった場合は `str`
+-   最後のエージェントに出力型が定義されていた場合は `last_agent.output_type` 型のオブジェクト
+-   承認中断で一時停止した場合など、最終出力が生成される前に実行が停止した場合は `None`
 
 !!! note
 
-    `final_output` は `Any` として型付けされています。ハンドオフによってどのエージェントが実行を終了するかが変わる可能性があるため、SDK は取り得る出力タイプの完全な集合を静的に知ることはできません。
+    `final_output` は `Any` として型付けされています。ハンドオフによって、どのエージェントが実行を終了するかが変わる可能性があるため、SDK は考えられる出力型の全体集合を静的に把握できません。
 
-ストリーミングモードでは、ストリームの処理が完了するまで `final_output` は `None` のままです。イベントごとのフローについては [ストリーミング](streaming.md) を参照してください。
+ストリーミングモードでは、ストリームの処理が完了するまで `final_output` は `None` のままです。イベントごとのフローについては、[ストリーミング](streaming.md)を参照してください。
 
 ## 入力、次ターン履歴、新規項目
 
-これらのサーフェスは異なる問いに答えます。
+これらのサーフェスは、それぞれ異なる問いに対応します。
 
-| プロパティまたはヘルパー | 含まれるもの | 最適な用途 |
+| プロパティまたはヘルパー | 含まれる内容 | 最適な用途 |
 | --- | --- | --- |
-| [`input`][agents.result.RunResultBase.input] | この実行セグメントのベース入力です。ハンドオフ入力フィルターが履歴を書き換えた場合、実行が継続したフィルター済み入力が反映されます。 | この実行が実際に入力として使用した内容の監査 |
-| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 実行の入力項目ビューです。デフォルトの `mode="preserve_all"` は、`new_items` から変換された完全な履歴を保持します。`mode="normalized"` は、ハンドオフフィルタリングによってモデル履歴が書き換えられる場合、正規の継続入力を優先します。 | 手動のチャットループ、クライアント管理の会話状態、プレーン項目履歴の確認 |
-| [`new_items`][agents.result.RunResultBase.new_items] | エージェント、ツール、ハンドオフ、承認メタデータを含む豊富な [`RunItem`][agents.items.RunItem] ラッパーです。 | ログ、UI、監査、デバッグ |
+| [`input`][agents.result.RunResultBase.input] | この実行セグメントの基本入力です。ハンドオフ入力フィルターが履歴を書き換えた場合、実行が継続されたフィルター済み入力がここに反映されます。 | この実行が実際に入力として使用した内容の監査 |
+| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 実行を入力項目として見たビューです。デフォルトの `mode="preserve_all"` は、`new_items` から変換された完全な履歴を保持します。`mode="normalized"` は、ハンドオフフィルタリングによってモデル履歴が書き換えられた場合に、正規の継続入力を優先します。 | 手動のチャットループ、クライアント管理の会話状態、プレーンな項目履歴の確認 |
+| [`new_items`][agents.result.RunResultBase.new_items] | エージェント、ツール、ハンドオフ、承認メタデータを含む詳細な [`RunItem`][agents.items.RunItem] ラッパーです。 | ログ、UI、監査、デバッグ |
 | [`raw_responses`][agents.result.RunResultBase.raw_responses] | 実行内の各モデル呼び出しからの raw [`ModelResponse`][agents.items.ModelResponse] オブジェクトです。 | プロバイダーレベルの診断または raw レスポンスの確認 |
 
-実際には、次のように使います。
+実際には、次のように使い分けます。
 
-- プレーンな入力項目ビューが必要な場合は `to_input_list()` を使用します。
-- ハンドオフフィルタリングまたはネストされたハンドオフ履歴の書き換え後、次の `Runner.run(..., input=...)` 呼び出しのための正規のローカル入力が必要な場合は、`to_input_list(mode="normalized")` を使用します。
-- SDK に履歴の読み込みと保存を任せたい場合は、[`session=...`](sessions/index.md) を使用します。
-- `conversation_id` または `previous_response_id` で OpenAI サーバー管理状態を使用している場合は、通常、`to_input_list()` を再送するのではなく、新しいユーザー入力のみを渡して保存済み ID を再利用します。
-- ログ、UI、監査のために変換済みの完全な履歴が必要な場合は、デフォルトの `to_input_list()` モードまたは `new_items` を使用します。
+-   実行のプレーンな入力項目ビューが必要な場合は、`to_input_list()` を使用します。
+-   ハンドオフフィルタリングまたはネストされたハンドオフ履歴の書き換え後に、次の `Runner.run(..., input=...)` 呼び出しに渡す正規のローカル入力が必要な場合は、`to_input_list(mode="normalized")` を使用します。
+-   SDK に履歴の読み込みと保存を任せたい場合は、[`session=...`](sessions/index.md) を使用します。
+-   `conversation_id` または `previous_response_id` を使って OpenAI のサーバー管理状態を使用している場合、通常は `to_input_list()` を再送信する代わりに、新しいユーザー入力のみを渡して保存済み ID を再利用します。
+-   ログ、UI、監査向けに完全な変換済み履歴が必要な場合は、デフォルトの `to_input_list()` モードまたは `new_items` を使用します。
 
-JavaScript SDK とは異なり、Python ではモデル形状の差分のみを表す個別の `output` プロパティは公開されません。SDK メタデータが必要な場合は `new_items` を使用し、raw モデルペイロードが必要な場合は `raw_responses` を確認してください。
+JavaScript SDK とは異なり、Python ではモデル形式の差分のみを表す個別の `output` プロパティは公開されません。SDK メタデータが必要な場合は `new_items` を使用し、raw モデルペイロードが必要な場合は `raw_responses` を確認してください。
 
-コンピュータツールの再生は、raw Responses ペイロードの形状に従います。プレビューモデルの `computer_call` 項目は単一の `action` を保持しますが、`gpt-5.5` のコンピュータ呼び出しはバッチ化された `actions[]` を保持できます。[`to_input_list()`][agents.result.RunResultBase.to_input_list] と [`RunState`][agents.run_state.RunState] はモデルが生成した形状をそのまま保持するため、手動再生、一時停止/再開フロー、保存済みトランスクリプトは、プレビュー版と GA のコンピュータツール呼び出しの両方で引き続き機能します。ローカルの実行結果は、引き続き `new_items` 内の `computer_call_output` 項目として表示されます。
+コンピュータツールのリプレイは、raw Responses ペイロードの形状に従います。プレビューモデルの `computer_call` 項目は単一の `action` を保持しますが、`gpt-5.5` のコンピュータ呼び出しではバッチ化された `actions[]` を保持できます。[`to_input_list()`][agents.result.RunResultBase.to_input_list] と [`RunState`][agents.run_state.RunState] は、モデルが生成した形状をそのまま保持するため、手動リプレイ、一時停止/再開フロー、保存済みトランスクリプトは、プレビュー版と GA 版の両方のコンピュータツール呼び出しで引き続き機能します。ローカル実行結果は引き続き `new_items` 内の `computer_call_output` 項目として表示されます。
 
 ### 新規項目
 
-[`new_items`][agents.result.RunResultBase.new_items] は、実行中に起きたことを最も豊富に確認できるビューを提供します。一般的な項目タイプは次のとおりです。
+[`new_items`][agents.result.RunResultBase.new_items] は、実行中に何が起きたかを最も詳細に確認できるビューです。一般的な項目型は次のとおりです。
 
-- アシスタントメッセージの [`MessageOutputItem`][agents.items.MessageOutputItem]
-- 推論項目の [`ReasoningItem`][agents.items.ReasoningItem]
-- Responses ツール検索リクエストと読み込まれたツール検索結果の [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] および [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
-- ツール呼び出しとその実行結果の [`ToolCallItem`][agents.items.ToolCallItem] および [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
-- 承認のために一時停止したツール呼び出しの [`ToolApprovalItem`][agents.items.ToolApprovalItem]
-- ハンドオフリクエストと完了した転送の [`HandoffCallItem`][agents.items.HandoffCallItem] および [`HandoffOutputItem`][agents.items.HandoffOutputItem]
+-   アシスタントメッセージ用の [`MessageOutputItem`][agents.items.MessageOutputItem]
+-   推論項目用の [`ReasoningItem`][agents.items.ReasoningItem]
+-   Responses のツール検索リクエストと、ロードされたツール検索の実行結果用の [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] および [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
+-   ツール呼び出しとその実行結果用の [`ToolCallItem`][agents.items.ToolCallItem] および [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
+-   承認待ちで一時停止したツール呼び出し用の [`ToolApprovalItem`][agents.items.ToolApprovalItem]
+-   ハンドオフリクエストと完了済みの引き継ぎ用の [`HandoffCallItem`][agents.items.HandoffCallItem] および [`HandoffOutputItem`][agents.items.HandoffOutputItem]
 
-エージェントの関連付け、ツール出力、ハンドオフ境界、または承認境界が必要な場合は、常に `to_input_list()` よりも `new_items` を選択してください。
+エージェントの関連付け、ツール出力、ハンドオフの境界、承認の境界が必要な場合は、常に `to_input_list()` よりも `new_items` を選択してください。
 
-ホスト型ツール検索を使用する場合は、`ToolSearchCallItem.raw_item` を確認してモデルが発行した検索リクエストを確認し、`ToolSearchOutputItem.raw_item` を確認してそのターンで読み込まれた名前空間、関数、またはホスト型 MCP サーバーを確認してください。
+ホスト型ツール検索を使用する場合、モデルが生成した検索リクエストを確認するには `ToolSearchCallItem.raw_item` を確認し、そのターンでどの名前空間、関数、またはホスト型 MCP サーバーがロードされたかを確認するには `ToolSearchOutputItem.raw_item` を確認してください。
 
 ## 会話の継続または再開
 
@@ -86,13 +86,13 @@ JavaScript SDK とは異なり、Python ではモデル形状の差分のみを
 
 [`last_agent`][agents.result.RunResultBase.last_agent] には、最後に実行されたエージェントが含まれます。これは多くの場合、ハンドオフ後の次のユーザーターンで再利用するのに最適なエージェントです。
 
-ストリーミングモードでは、実行の進行に応じて [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] が更新されるため、ストリームが完了する前にハンドオフを観察できます。
+ストリーミングモードでは、[`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent] が実行の進行に合わせて更新されるため、ストリームが終了する前にハンドオフを観察できます。
 
 ### 中断と実行状態
 
-ツールに承認が必要な場合、保留中の承認は [`RunResult.interruptions`][agents.result.RunResult.interruptions] または [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。これには、直接ツールによって発生した承認、ハンドオフ後に到達したツールによって発生した承認、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行によって発生した承認が含まれる場合があります。
+ツールに承認が必要な場合、保留中の承認は [`RunResult.interruptions`][agents.result.RunResult.interruptions] または [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。これには、直接呼び出されたツール、ハンドオフ後に到達したツール、またはネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行によって発生した承認が含まれることがあります。
 
-[`to_state()`][agents.result.RunResult.to_state] を呼び出して、再開可能な [`RunState`][agents.run_state.RunState] を取得し、保留中の項目を承認または却下してから、`Runner.run(...)` または `Runner.run_streamed(...)` で再開します。
+[`to_state()`][agents.result.RunResult.to_state] を呼び出して、再開可能な [`RunState`][agents.run_state.RunState] を取得し、保留中の項目を承認または拒否してから、`Runner.run(...)` または `Runner.run_streamed(...)` で再開します。
 
 ```python
 from agents import Agent, Runner
@@ -107,59 +107,59 @@ if result.interruptions:
     result = await Runner.run(agent, state)
 ```
 
-ストリーミング実行では、まず [`stream_events()`][agents.result.RunResultStreaming.stream_events] の消費を完了し、その後 `result.interruptions` を確認して `result.to_state()` から再開します。完全な承認フローについては、[Human-in-the-loop](human_in_the_loop.md) を参照してください。
+ストリーミング実行では、まず [`stream_events()`][agents.result.RunResultStreaming.stream_events] の消費を完了してから `result.interruptions` を確認し、`result.to_state()` から再開してください。承認フロー全体については、[ヒューマンインザループ](human_in_the_loop.md)を参照してください。
 
 ### サーバー管理の継続
 
-[`last_response_id`][agents.result.RunResultBase.last_response_id] は、実行から得られた最新のモデルレスポンス ID です。OpenAI Responses API チェーンを継続したい場合は、次のターンで `previous_response_id` として渡します。
+[`last_response_id`][agents.result.RunResultBase.last_response_id] は、実行から得られた最新のモデルレスポンス ID です。OpenAI Responses API チェーンを継続したい場合は、次のターンで `previous_response_id` として渡してください。
 
-すでに `to_input_list()`、`session`、または `conversation_id` で会話を継続している場合、通常 `last_response_id` は必要ありません。複数ステップの実行からすべてのモデルレスポンスが必要な場合は、代わりに `raw_responses` を確認してください。
+すでに `to_input_list()`、`session`、または `conversation_id` で会話を継続している場合、通常は `last_response_id` は不要です。複数ステップの実行におけるすべてのモデルレスポンスが必要な場合は、代わりに `raw_responses` を確認してください。
 
-## Agent-as-tool メタデータ
+## ツールとしてのエージェントのメタデータ
 
-ネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行から実行結果が返される場合、[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] は外側のツール呼び出しに関する不変のメタデータを公開します。
+実行結果がネストされた [`Agent.as_tool()`][agents.agent.Agent.as_tool] 実行に由来する場合、[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] は外側のツール呼び出しに関する変更不可のメタデータを公開します。
 
-- `tool_name`
-- `tool_call_id`
-- `tool_arguments`
+-   `tool_name`
+-   `tool_call_id`
+-   `tool_arguments`
 
 通常のトップレベル実行では、`agent_tool_invocation` は `None` です。
 
-これは、ネストされた実行結果を後処理する際に外側のツール名、呼び出し ID、または raw 引数が必要になることがある `custom_output_extractor` 内で特に有用です。周辺の `Agent.as_tool()` パターンについては、[ツール](tools.md) を参照してください。
+これは、ネストされた実行結果を後処理する際に、外側のツール名、呼び出し ID、または生の引数が必要になることがある `custom_output_extractor` 内で特に便利です。関連する `Agent.as_tool()` パターンについては、[ツール](tools.md)を参照してください。
 
-そのネストされた実行の解析済み structured input も必要な場合は、`context_wrapper.tool_input` を読み取ります。これは [`RunState`][agents.run_state.RunState] がネストされたツール入力として汎用的にシリアライズするフィールドであり、`agent_tool_invocation` は現在のネストされた呼び出しに対するライブ実行結果アクセサーです。
+そのネストされた実行のパース済み構造化入力も必要な場合は、`context_wrapper.tool_input` を読み取ってください。これは、ネストされたツール入力に対して [`RunState`][agents.run_state.RunState] が汎用的にシリアライズするフィールドです。一方、`agent_tool_invocation` は、現在のネストされた呼び出しに対するライブの実行結果アクセサーです。
 
 ## ストリーミングのライフサイクルと診断
 
-[`RunResultStreaming`][agents.result.RunResultStreaming] は上記と同じ実行結果サーフェスを継承しますが、ストリーミング固有の制御を追加します。
+[`RunResultStreaming`][agents.result.RunResultStreaming] は、上記と同じ実行結果サーフェスを継承しますが、ストリーミング固有の制御機能を追加します。
 
-- セマンティックなストリームイベントを消費する [`stream_events()`][agents.result.RunResultStreaming.stream_events]
-- 実行中のアクティブなエージェントを追跡する [`current_agent`][agents.result.RunResultStreaming.current_agent]
-- ストリーミング実行が完全に終了したかどうかを確認する [`is_complete`][agents.result.RunResultStreaming.is_complete]
-- 現在のターンの直後または即座に実行を停止する [`cancel(...)`][agents.result.RunResultStreaming.cancel]
+-   セマンティックなストリームイベントを消費するための [`stream_events()`][agents.result.RunResultStreaming.stream_events]
+-   実行途中でアクティブなエージェントを追跡するための [`current_agent`][agents.result.RunResultStreaming.current_agent]
+-   ストリーミング実行が完全に終了したかどうかを確認するための [`is_complete`][agents.result.RunResultStreaming.is_complete]
+-   実行を即時または現在のターン後に停止するための [`cancel(...)`][agents.result.RunResultStreaming.cancel]
 
-非同期イテレーターが終了するまで `stream_events()` を消費し続けてください。ストリーミング実行は、そのイテレーターが終了するまで完了していません。また、`final_output`、`interruptions`、`raw_responses`、セッション永続化の副作用などのサマリープロパティは、最後に見えるトークンが到着した後もまだ確定中の場合があります。
+非同期イテレーターが終了するまで `stream_events()` を消費し続けてください。そのイテレーターが終了するまで、ストリーミング実行は完了していません。また、`final_output`、`interruptions`、`raw_responses` などの要約プロパティや、セッション永続化の副作用は、目に見える最後のトークンが到着した後もまだ確定中の場合があります。
 
-`cancel()` を呼び出した場合は、キャンセルとクリーンアップが正しく完了できるように、`stream_events()` の消費を続けてください。
+`cancel()` を呼び出した場合は、キャンセルとクリーンアップが正しく完了できるように、`stream_events()` を消費し続けてください。
 
-Python では、ストリーミングされた個別の `completed` promise や `error` プロパティは公開されません。終端的なストリーミング失敗は `stream_events()` から例外を送出することで表面化し、`is_complete` は実行が終端状態に到達したかどうかを反映します。
+Python では、ストリーミング用の個別の `completed` プロミスや `error` プロパティは公開されません。終端的なストリーミング失敗は `stream_events()` から例外が送出されることで表面化し、`is_complete` は実行が終端状態に到達したかどうかを反映します。
 
-### Raw レスポンス
+### raw レスポンス
 
-[`raw_responses`][agents.result.RunResultBase.raw_responses] には、実行中に収集された raw モデルレスポンスが含まれます。複数ステップの実行では、たとえばハンドオフや、モデル/ツール/モデルのサイクルの繰り返しをまたいで、複数のレスポンスが生成される場合があります。
+[`raw_responses`][agents.result.RunResultBase.raw_responses] には、実行中に収集された raw モデルレスポンスが含まれます。複数ステップの実行では、ハンドオフをまたいだり、モデル/ツール/モデルのサイクルが繰り返されたりする場合など、複数のレスポンスが生成されることがあります。
 
-[`last_response_id`][agents.result.RunResultBase.last_response_id] は、`raw_responses` の最後のエントリーからの ID にすぎません。
+[`last_response_id`][agents.result.RunResultBase.last_response_id] は、`raw_responses` の最後のエントリの ID にすぎません。
 
-### ガードレール実行結果
+### ガードレールの実行結果
 
 エージェントレベルのガードレールは、[`input_guardrail_results`][agents.result.RunResultBase.input_guardrail_results] および [`output_guardrail_results`][agents.result.RunResultBase.output_guardrail_results] として公開されます。
 
-ツールのガードレールは、[`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] および [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] として別途公開されます。
+ツールガードレールは、[`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] および [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results] として個別に公開されます。
 
-これらの配列は実行全体を通じて蓄積されるため、判断のログ記録、追加のガードレールメタデータの保存、または実行がブロックされた理由のデバッグに役立ちます。
+これらの配列は実行全体で蓄積されるため、判定のログ記録、追加のガードレールメタデータの保存、または実行がブロックされた理由のデバッグに役立ちます。
 
 ### コンテキストと使用量
 
-[`context_wrapper`][agents.result.RunResultBase.context_wrapper] は、承認、使用量、ネストされた `tool_input` など、SDK 管理のランタイムメタデータとともにアプリのコンテキストを公開します。
+[`context_wrapper`][agents.result.RunResultBase.context_wrapper] は、アプリのコンテキストと、承認、使用量、ネストされた `tool_input` など SDK が管理するランタイムメタデータを公開します。
 
-使用量は `context_wrapper.usage` で追跡されます。ストリーミング実行では、ストリームの最後のチャンクが処理されるまで使用量の合計が遅れることがあります。完全なラッパー形状と永続化に関する注意事項については、[コンテキスト管理](context.md) を参照してください。
+使用量は `context_wrapper.usage` で追跡されます。ストリーミング実行では、ストリームの最終チャンクが処理されるまで、使用量の合計値が遅れて反映される場合があります。ラッパーの完全な形状と永続化に関する注意事項については、[コンテキスト管理](context.md)を参照してください。

docs/ja/running_agents.md

@@ -4,11 +4,11 @@ search:
 ---
 # エージェントの実行
 
-[`Runner`][agents.run.Runner] クラスを介してエージェントを実行できます。選択肢は 3 つあります。
+[`Runner`][agents.run.Runner] クラスを通じてエージェントを実行できます。3 つの選択肢があります。
 
-1. [`Runner.run()`][agents.run.Runner.run] は async で実行され、[`RunResult`][agents.result.RunResult] を返します。
-2. [`Runner.run_sync()`][agents.run.Runner.run_sync] は sync メソッドで、内部では単に `.run()` を実行します。
-3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] は async で実行され、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。これはストリーミングモードで LLM を呼び出し、受信したイベントを順次ストリーミングします。
+1. [`Runner.run()`][agents.run.Runner.run] は非同期で実行し、[`RunResult`][agents.result.RunResult] を返します。
+2. [`Runner.run_sync()`][agents.run.Runner.run_sync] は同期メソッドで、内部的には単に `.run()` を実行します。
+3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed] は非同期で実行し、[`RunResultStreaming`][agents.result.RunResultStreaming] を返します。LLM をストリーミングモードで呼び出し、受信したイベントをそのままストリーミングします。
 
 ```python
 from agents import Agent, Runner
@@ -31,38 +31,38 @@ async def main():
 
 `Runner` の run メソッドを使用するときは、開始エージェントと入力を渡します。入力には以下を指定できます。
 
--   文字列（ユーザーメッセージとして扱われます）、
--   OpenAI Responses API 形式の入力項目のリスト、または
--   中断された run を再開する場合の [`RunState`][agents.run_state.RunState]。
+-   文字列（ユーザーメッセージとして扱われます）
+-   OpenAI Responses API 形式の入力項目のリスト
+-   中断された実行を再開する場合の [`RunState`][agents.run_state.RunState]
 
-runner は次にループを実行します。
+その後、runner はループを実行します。
 
-1. 現在のエージェントに対して、現在の入力を使って LLM を呼び出します。
+1. 現在のエージェントに対して、現在の入力で LLM を呼び出します。
 2. LLM が出力を生成します。
     1. LLM が `final_output` を返した場合、ループは終了し、実行結果を返します。
     2. LLM がハンドオフを行った場合、現在のエージェントと入力を更新し、ループを再実行します。
-    3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、結果を追加して、ループを再実行します。
-3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。
+    3. LLM がツール呼び出しを生成した場合、それらのツール呼び出しを実行し、実行結果を追加して、ループを再実行します。
+3. 渡された `max_turns` を超えた場合、[`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 例外を発生させます。このターン制限を無効にするには、`max_turns=None` を渡します。
 
 !!! note
 
-    LLM 出力が「最終出力」とみなされるかどうかのルールは、目的の型のテキスト出力を生成し、ツール呼び出しがないことです。
+    LLM の出力が「最終出力」と見なされるルールは、目的の型のテキスト出力が生成され、ツール呼び出しがないことです。
 
 ### ストリーミング
 
-ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受信できます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む、run に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳細は [ストリーミングガイド](streaming.md) を参照してください。
+ストリーミングを使用すると、LLM の実行中にストリーミングイベントも受け取れます。ストリームが完了すると、[`RunResultStreaming`][agents.result.RunResultStreaming] には、生成されたすべての新しい出力を含む実行に関する完全な情報が含まれます。ストリーミングイベントには `.stream_events()` を呼び出せます。詳細は [ストリーミングガイド](streaming.md) を参照してください。
 
 #### Responses WebSocket トランスポート（任意のヘルパー）
 
-OpenAI Responses websocket トランスポートを有効にしている場合でも、通常の `Runner` API を引き続き使用できます。接続の再利用には websocket セッションヘルパーの使用を推奨しますが、必須ではありません。
+OpenAI Responses WebSocket トランスポートを有効にしても、通常の `Runner` API を引き続き使用できます。WebSocket セッションヘルパーは接続の再利用に推奨されますが、必須ではありません。
 
-これは websocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。
+これは WebSocket トランスポート上の Responses API であり、[Realtime API](realtime/guide.md) ではありません。
 
-トランスポート選択ルール、および具体的なモデルオブジェクトやカスタムプロバイダーに関する注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。
+具体的なモデルオブジェクトやカスタムプロバイダーに関するトランスポート選択ルールと注意点については、[モデル](models/index.md#responses-websocket-transport) を参照してください。
 
 ##### パターン 1: セッションヘルパーなし（動作します）
 
-websocket トランスポートだけを使いたく、SDK に共有プロバイダーやセッションを管理させる必要がない場合に使用します。
+WebSocket トランスポートだけを使用したく、SDK に共有プロバイダー / セッションを管理させる必要がない場合に使用します。
 
 ```python
 import asyncio
@@ -85,11 +85,11 @@ async def main():
 asyncio.run(main())
 ```
 
-このパターンは単発の run には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼び出す場合、同じ `RunConfig` / プロバイダーインスタンスを手動で再利用しない限り、各 run で再接続されることがあります。
+このパターンは単発の実行には問題ありません。`Runner.run()` / `Runner.run_streamed()` を繰り返し呼び出す場合、同じ `RunConfig` / プロバイダーインスタンスを手動で再利用しない限り、各実行で再接続される可能性があります。
 
-##### パターン 2: `responses_websocket_session()` の使用（複数ターンでの再利用に推奨）
+##### パターン 2: `responses_websocket_session()` の使用（複数ターンの再利用に推奨）
 
-複数の run（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含む）にわたって、websocket 対応の共有プロバイダーと `RunConfig` を使いたい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用します。
+複数の実行にわたって共有の WebSocket 対応プロバイダーと `RunConfig` を使用したい場合は、[`responses_websocket_session()`][agents.responses_websocket_session] を使用します（同じ `run_config` を継承するネストされた agent-as-tool 呼び出しを含みます）。
 
 ```python
 import asyncio
@@ -100,7 +100,9 @@ from agents import Agent, responses_websocket_session
 async def main():
     agent = Agent(name="Assistant", instructions="Be concise.")
 
-    async with responses_websocket_session() as ws:
+    async with responses_websocket_session(
+        responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
+    ) as ws:
         first = ws.run_streamed(agent, "Say hello in one short sentence.")
         async for _event in first.stream_events():
             pass
@@ -117,63 +119,88 @@ async def main():
 asyncio.run(main())
 ```
 
-コンテキストを抜ける前に、ストリーミングされた実行結果の消費を完了してください。websocket リクエストがまだ処理中の状態でコンテキストを抜けると、共有接続が強制的に閉じられる場合があります。
+コンテキストを抜ける前に、ストリーミングされた実行結果の消費を完了してください。WebSocket リクエストがまだ実行中の状態でコンテキストを抜けると、共有接続が強制的に閉じられる可能性があります。
 
-### Run config
+長い推論ターンで WebSocket の keepalive タイムアウトに達する場合は、`ping_timeout` を増やすか、`ping_timeout=None` を設定してハートビートタイムアウトを無効にしてください。WebSocket のレイテンシより信頼性が重要な実行では、HTTP/SSE トランスポートを使用してください。
 
-`run_config` パラメーターを使用すると、エージェント run のいくつかのグローバル設定を構成できます。
+### 実行設定
 
-#### 一般的な run config カテゴリー
+`run_config` パラメーターを使用すると、エージェント実行に関するいくつかのグローバル設定を構成できます。
 
-各エージェント定義を変更せずに、単一の run の動作を上書きするには `RunConfig` を使用します。
+#### 一般的な実行設定カテゴリー
+
+各エージェント定義を変更せずに単一の実行の動作を上書きするには、`RunConfig` を使用します。
 
 ##### モデル、プロバイダー、セッションのデフォルト
 
--   [`model`][agents.run.RunConfig.model]: 各 Agent が持つ `model` に関係なく、使用するグローバル LLM モデルを設定できます。
--   [`model_provider`][agents.run.RunConfig.model_provider]: モデル名を検索するためのモデルプロバイダーで、デフォルトは OpenAI です。
+-   [`model`][agents.run.RunConfig.model]: 各 Agent が持つ `model` に関係なく、使用するグローバルな LLM モデルを設定できます。
+-   [`model_provider`][agents.run.RunConfig.model_provider]: モデル名の検索に使用するモデルプロバイダーで、デフォルトは OpenAI です。
 -   [`model_settings`][agents.run.RunConfig.model_settings]: エージェント固有の設定を上書きします。たとえば、グローバルな `temperature` や `top_p` を設定できます。
--   [`session_settings`][agents.run.RunConfig.session_settings]: run 中に履歴を取得するときのセッションレベルのデフォルト（例: `SessionSettings(limit=...)`）を上書きします。
--   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions を使用する際、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは sync または async にできます。
+-   [`session_settings`][agents.run.RunConfig.session_settings]: 実行中に履歴を取得する際のセッションレベルのデフォルト（たとえば `SessionSettings(limit=...)`）を上書きします。
+-   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions を使用する際、各ターンの前に新しいユーザー入力をセッション履歴とどのようにマージするかをカスタマイズします。コールバックは同期でも非同期でもかまいません。
 
 ##### ガードレール、ハンドオフ、モデル入力の整形
 
--   [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての run に含める入力または出力ガードレールのリストです。
--   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフに既にフィルターがない場合に、すべてのハンドオフへ適用するグローバル入力フィルターです。入力フィルターにより、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。
--   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前のトランスクリプトを単一の assistant メッセージに折りたたむオプトインのベータ機能です。ネストされたハンドオフを安定化させている間はデフォルトで無効です。有効にするには `True` に設定し、raw トランスクリプトをそのまま渡すには `False` のままにします。[Runner メソッド][agents.run.Runner] は、渡されない場合にすべて自動的に `RunConfig` を作成するため、クイックスタートやコード例ではデフォルトはオフのままで、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個々のハンドオフは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を介してこの設定を上書きできます。
--   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` にオプトインしたときに、正規化されたトランスクリプト（履歴 + ハンドオフ項目）を受け取る任意の callable です。次のエージェントに転送する入力項目の正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込みの要約を置き換えられます。
--   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力項目）を編集するためのフックです。たとえば、履歴をトリムしたり、システムプロンプトを注入したりできます。
--   [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換するときに、reasoning item ID を保持するか省略するかを制御します。
+-   [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: すべての実行に含める入力または出力ガードレールのリストです。
+-   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: ハンドオフにまだ入力フィルターがない場合に、すべてのハンドオフに適用するグローバル入力フィルターです。入力フィルターを使用すると、新しいエージェントに送信される入力を編集できます。詳細は [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] のドキュメントを参照してください。
+-   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 次のエージェントを呼び出す前に、以前のトランスクリプトを単一のアシスタントメッセージに折りたたむオプトインのベータ機能です。ネストされたハンドオフを安定化させている間、この機能はデフォルトで無効です。有効にするには `True` に設定し、未加工のトランスクリプトをそのまま渡すには `False` のままにします。すべての [Runner メソッド][agents.run.Runner] は、渡されない場合に自動的に `RunConfig` を作成するため、クイックスタートとコード例ではデフォルトでオフのままになり、明示的な [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] コールバックは引き続きこれを上書きします。個別のハンドオフは [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history] を通じてこの設定を上書きできます。
+-   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history` にオプトインした場合に、正規化されたトランスクリプト（履歴 + ハンドオフ項目）を受け取る任意の callable です。次のエージェントに転送する入力項目の正確なリストを返す必要があり、完全なハンドオフフィルターを書かずに組み込みの要約を置き換えられます。
+-   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: モデル呼び出しの直前に、完全に準備されたモデル入力（instructions と入力項目）を編集するフックです。たとえば、履歴をトリミングしたり、システムプロンプトを挿入したりできます。
+-   [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner が以前の出力を次ターンのモデル入力に変換するときに、推論項目 ID を保持するか省略するかを制御します。
 
 ##### トレーシングと可観測性
 
--   [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: run 全体の [トレーシング](tracing.md) を無効にできます。
--   [`tracing`][agents.run.RunConfig.tracing]: run ごとのトレーシング API キーなど、トレースのエクスポート設定を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。
--   [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: LLM やツール呼び出しの入力/出力など、潜在的に機密性の高いデータをトレースに含めるかどうかを設定します。
--   [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: run のトレーシング workflow 名、trace ID、trace group ID を設定します。少なくとも `workflow_name` を設定することをお勧めします。group ID は、複数の run にまたがってトレースをリンクできる任意フィールドです。
+-   [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 実行全体で [トレーシング](tracing.md) を無効にできます。
+-   [`tracing`][agents.run.RunConfig.tracing]: 実行ごとのトレーシング API キーなど、トレースエクスポート設定を上書きするために [`TracingConfig`][agents.tracing.TracingConfig] を渡します。
+-   [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: トレースに、LLM やツール呼び出しの入力 / 出力など、潜在的に機密性の高いデータを含めるかどうかを設定します。
+-   [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 実行のトレーシングワークフロー名、トレース ID、トレースグループ ID を設定します。少なくとも `workflow_name` を設定することをおすすめします。グループ ID は、複数の実行間でトレースを関連付けるための任意フィールドです。
 -   [`trace_metadata`][agents.run.RunConfig.trace_metadata]: すべてのトレースに含めるメタデータです。
 
-##### ツール承認とツールエラーの動作
+##### ツール実行、承認、ツールエラーの動作
 
--   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに見えるメッセージをカスタマイズします。
+-   [`tool_execution`][agents.run.RunConfig.tool_execution]: 一度に実行する関数ツール数を制限するなど、ローカルツール呼び出しに対する SDK 側の実行動作を設定します。
+-   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 承認フロー中にツール呼び出しが拒否された場合に、モデルに表示されるメッセージをカスタマイズします。
 
-ネストされたハンドオフは、オプトインのベータとして利用できます。`RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフに対して有効にするには `handoff(..., nest_handoff_history=True)` を設定して、折りたたまれたトランスクリプトの動作を有効にします。raw トランスクリプトを保持したい場合（デフォルト）は、フラグを未設定のままにするか、必要どおりに会話を正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定します。カスタムマッパーを書かずに生成される要約で使われるラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]（デフォルトに戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）を呼び出します。
+ネストされたハンドオフは、オプトインのベータ機能として利用できます。`RunConfig(nest_handoff_history=True)` を渡すか、特定のハンドオフで `handoff(..., nest_handoff_history=True)` を設定すると、折りたたみトランスクリプト動作を有効にできます。未加工のトランスクリプトを保持したい場合（デフォルト）は、フラグを未設定のままにするか、必要に応じて会話を正確に転送する `handoff_input_filter`（または `handoff_history_mapper`）を指定します。カスタムマッパーを書かずに、生成される要約で使用されるラッパーテキストを変更するには、[`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] を呼び出します（デフォルトに戻すには [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]）。
 
-#### Run config の詳細
+#### 実行設定の詳細
+
+##### `tool_execution`
+
+実行に対してローカル関数ツールの同時実行数を SDK に制限させたい場合は、`tool_execution` を使用します。
+
+```python
+from agents import Agent, RunConfig, Runner, ToolExecutionConfig
+
+agent = Agent(name="Assistant", tools=[...])
+
+result = await Runner.run(
+    agent,
+    "Run the required tool calls.",
+    run_config=RunConfig(
+        tool_execution=ToolExecutionConfig(max_function_tool_concurrency=2),
+    ),
+)
+```
+
+`max_function_tool_concurrency=None` はデフォルトの動作を維持します。モデルが 1 ターンで複数の関数ツール呼び出しを生成した場合、SDK は生成されたすべてのローカル関数ツール呼び出しを開始します。整数値を設定すると、それらのローカル関数ツールのうち同時に実行される数に上限を設けられます。
+
+これはプロバイダー側の [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls] とは別のものです。`parallel_tool_calls` は、モデルが 1 つのレスポンスで複数のツール呼び出しを生成できるかどうかを制御します。`tool_execution.max_function_tool_concurrency` は、モデルがそれらを生成した後に、SDK がローカル関数ツール呼び出しをどのように実行するかを制御します。
 
 ##### `tool_error_formatter`
 
 承認フローでツール呼び出しが拒否されたときにモデルへ返されるメッセージをカスタマイズするには、`tool_error_formatter` を使用します。
 
-フォーマッターは [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取り、内容は次のとおりです。
+フォーマッターは、以下を含む [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs] を受け取ります。
 
 -   `kind`: エラーカテゴリーです。現在は `"approval_rejected"` です。
--   `tool_type`: ツールランタイム（`"function"`, `"computer"`, `"shell"`, `"apply_patch"`, または `"custom"`）です。
+-   `tool_type`: ツールランタイム（`"function"`、`"computer"`、`"shell"`、`"apply_patch"`、または `"custom"`）です。
 -   `tool_name`: ツール名です。
 -   `call_id`: ツール呼び出し ID です。
--   `default_message`: SDK のデフォルトのモデル可視メッセージです。
--   `run_context`: アクティブな run context wrapper です。
+-   `default_message`: SDK のデフォルトのモデル表示メッセージです。
+-   `run_context`: アクティブな実行コンテキストラッパーです。
 
-メッセージを置き換える文字列、または SDK デフォルトを使用する場合は `None` を返します。
+メッセージを置き換えるには文字列を返し、SDK のデフォルトを使用するには `None` を返します。
 
 ```python
 from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs
@@ -198,56 +225,56 @@ result = Runner.run_sync(
 
 ##### `reasoning_item_id_policy`
 
-`reasoning_item_id_policy` は、runner が履歴を引き継ぐとき（たとえば `RunResult.to_input_list()` や session-backed run を使用する場合）に、reasoning item を次ターンのモデル入力へ変換する方法を制御します。
+`reasoning_item_id_policy` は、runner が履歴を引き継ぐとき（たとえば `RunResult.to_input_list()` やセッションに基づく実行を使用する場合）に、推論項目を次ターンのモデル入力へどのように変換するかを制御します。
 
--   `None` または `"preserve"`（デフォルト）: reasoning item ID を保持します。
--   `"omit"`: 生成される次ターン入力から reasoning item ID を取り除きます。
+-   `None` または `"preserve"`（デフォルト）: 推論項目 ID を保持します。
+-   `"omit"`: 生成される次ターンの入力から推論項目 ID を取り除きます。
 
-`"omit"` は主に、reasoning item が `id` 付きで送信されている一方で、必要な後続項目がない場合に発生する Responses API 400 エラーの一種（たとえば `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）に対する、オプトインの緩和策として使用します。
+`"omit"` は主に、推論項目が `id` 付きで送信されているものの、必須の後続項目がない場合に発生する Responses API 400 エラーの一群に対する、オプトインの緩和策として使用します（例: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`）。
 
-これは、SDK が以前の出力から後続入力を構築する複数ターンのエージェント run で発生することがあります（セッション永続化、サーバー管理の会話差分、ストリーミング/非ストリーミングの後続ターン、再開パスを含む）。reasoning item ID が保持されているものの、プロバイダーがその ID を対応する後続項目と対のままにすることを要求する場合です。
+これは、SDK が以前の出力からフォローアップ入力を構築するマルチターンのエージェント実行で発生する可能性があります（セッション永続化、サーバー管理の会話差分、ストリーミング / 非ストリーミングのフォローアップターン、再開パスを含みます）。推論項目 ID が保持されている一方で、プロバイダーがその ID を対応する後続項目とペアのままにすることを要求する場合です。
 
-`reasoning_item_id_policy="omit"` を設定すると、reasoning content は保持しつつ reasoning item の `id` を取り除くため、SDK が生成する後続入力でその API 不変条件をトリガーするのを回避できます。
+`reasoning_item_id_policy="omit"` を設定すると、推論コンテンツは保持したまま推論項目の `id` を取り除くため、SDK が生成するフォローアップ入力でその API 不変条件がトリガーされることを回避できます。
 
-スコープに関する注意:
+スコープに関する注記:
 
--   これは、SDK が後続入力を構築するときに生成/転送する reasoning item のみを変更します。
+-   これは、SDK がフォローアップ入力を構築するときに SDK によって生成 / 転送される推論項目のみを変更します。
 -   ユーザーが指定した初期入力項目は書き換えません。
--   `call_model_input_filter` は、このポリシー適用後でも意図的に reasoning ID を再導入できます。
+-   `call_model_input_filter` は、このポリシー適用後でも意図的に推論 ID を再導入できます。
 
-## 状態と会話の管理
+## 状態と会話管理
 
 ### メモリ戦略の選択
 
-次のターンに状態を引き継ぐ一般的な方法は 4 つあります。
+状態を次のターンへ引き継ぐ一般的な方法は 4 つあります。
 
-| 戦略 | 状態の保存場所 | 最適な用途 | 次ターンで渡すもの |
+| 戦略 | 状態の保存場所 | 最適な用途 | 次のターンで渡すもの |
 | --- | --- | --- | --- |
 | `result.to_input_list()` | アプリのメモリ | 小規模なチャットループ、完全な手動制御、任意のプロバイダー | `result.to_input_list()` からのリストに次のユーザーメッセージを加えたもの |
-| `session` | ストレージと SDK | 永続的なチャット状態、再開可能な run、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別のインスタンス |
+| `session` | ストレージと SDK | 永続的なチャット状態、再開可能な実行、カスタムストア | 同じ `session` インスタンス、または同じストアを指す別のインスタンス |
 | `conversation_id` | OpenAI Conversations API | ワーカーやサービス間で共有したい名前付きのサーバー側会話 | 同じ `conversation_id` と新しいユーザーターンのみ |
-| `previous_response_id` | OpenAI Responses API | 会話リソースを作成しない軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ |
+| `previous_response_id` | OpenAI Responses API | 会話リソースを作成しない、軽量なサーバー管理の継続 | `result.last_response_id` と新しいユーザーターンのみ |
 
-`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理であり、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選んでください。両方の層を意図的に突き合わせているのでない限り、クライアント管理の履歴と OpenAI 管理の状態を混在させると、コンテキストが重複することがあります。
+`result.to_input_list()` と `session` はクライアント管理です。`conversation_id` と `previous_response_id` は OpenAI 管理で、OpenAI Responses API を使用している場合にのみ適用されます。ほとんどのアプリケーションでは、会話ごとに 1 つの永続化戦略を選択します。意図的に両方のレイヤーを調整している場合を除き、クライアント管理の履歴と OpenAI 管理の状態を混在させると、コンテキストが重複する可能性があります。
 
 !!! note
 
-    セッション永続化は、同じ run 内でサーバー管理の会話設定
+    セッション永続化は、同じ実行内でサーバー管理の会話設定
     （`conversation_id`、`previous_response_id`、または `auto_previous_response_id`）と
-    組み合わせることはできません。呼び出しごとに 1 つの方法を選択してください。
+    組み合わせることはできません。呼び出しごとに 1 つのアプローチを選択してください。
 
 ### 会話 / チャットスレッド
 
-いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）場合がありますが、これはチャット会話における 1 つの論理ターンを表します。たとえば以下のとおりです。
+いずれかの run メソッドを呼び出すと、1 つ以上のエージェントが実行される（したがって 1 回以上の LLM 呼び出しが行われる）場合がありますが、チャット会話における単一の論理ターンを表します。例:
 
 1. ユーザーターン: ユーザーがテキストを入力します
-2. Runner run: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントにハンドオフします。2 番目のエージェントがさらにツールを実行し、その後出力を生成します。
+2. Runner の実行: 最初のエージェントが LLM を呼び出し、ツールを実行し、2 番目のエージェントへハンドオフし、2 番目のエージェントがさらにツールを実行してから出力を生成します。
 
-エージェント run の終了時に、ユーザーに何を表示するかを選択できます。たとえば、エージェントによって生成されたすべての新しい項目をユーザーに表示することも、最終出力だけを表示することもできます。どちらの場合でも、その後ユーザーがフォローアップの質問をする可能性があり、その場合は run メソッドを再度呼び出せます。
+エージェント実行の終了時に、ユーザーに何を表示するかを選択できます。たとえば、エージェントによって生成されたすべての新しい項目をユーザーに表示することも、最終出力だけを表示することもできます。いずれの場合でも、その後ユーザーが追加の質問をする可能性があり、その場合は run メソッドを再度呼び出せます。
 
-#### 手動での会話管理
+#### 手動の会話管理
 
-[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して次ターンの入力を取得し、会話履歴を手動で管理できます。
+[`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] メソッドを使用して次のターンの入力を取得し、会話履歴を手動で管理できます。
 
 ```python
 async def main():
@@ -269,7 +296,7 @@ async def main():
 
 #### セッションによる自動会話管理
 
-よりシンプルな方法として、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出さずに会話履歴を自動的に扱えます。
+より簡単な方法として、[Sessions](sessions/index.md) を使用すると、`.to_input_list()` を手動で呼び出すことなく会話履歴を自動的に処理できます。
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -295,8 +322,8 @@ async def main():
 
 Sessions は自動的に以下を行います。
 
--   各 run の前に会話履歴を取得します
--   各 run の後に新しいメッセージを保存します
+-   各実行の前に会話履歴を取得します
+-   各実行の後に新しいメッセージを保存します
 -   異なるセッション ID ごとに別々の会話を維持します
 
 詳細は [Sessions ドキュメント](sessions/index.md) を参照してください。
@@ -304,13 +331,13 @@ Sessions は自動的に以下を行います。
 
 #### サーバー管理の会話
 
-`to_input_list()` や `Sessions` を使ってローカルで扱う代わりに、OpenAI の会話状態機能にサーバー側の会話状態を管理させることもできます。これにより、過去のすべてのメッセージを手動で再送信しなくても、会話履歴を保持できます。以下のいずれのサーバー管理方式でも、各リクエストでは新しいターンの入力のみを渡し、保存された ID を再利用します。詳細は [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。
+`to_input_list()` や `Sessions` でローカルに処理する代わりに、OpenAI の会話状態機能にサーバー側で会話状態を管理させることもできます。これにより、過去のすべてのメッセージを手動で再送信することなく、会話履歴を保持できます。以下のどちらのサーバー管理アプローチでも、各リクエストでは新しいターンの入力だけを渡し、保存した ID を再利用します。詳細は [OpenAI Conversation state ガイド](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。
 
-OpenAI はターン間で状態を追跡する 2 つの方法を提供します。
+OpenAI は、ターン間で状態を追跡する 2 つの方法を提供しています。
 
 ##### 1. `conversation_id` の使用
 
-まず OpenAI Conversations API を使用して会話を作成し、その ID を以降のすべての呼び出しで再利用します。
+まず OpenAI Conversations API を使用して会話を作成し、その後のすべての呼び出しでその ID を再利用します。
 
 ```python
 from agents import Agent, Runner
@@ -333,7 +360,7 @@ async def main():
 
 ##### 2. `previous_response_id` の使用
 
-もう 1 つの選択肢は **response chaining** で、各ターンが前のターンの response ID に明示的にリンクします。
+もう 1 つの選択肢は **レスポンスチェーン** で、各ターンを前のターンのレスポンス ID に明示的にリンクします。
 
 ```python
 from agents import Agent, Runner
@@ -358,32 +385,31 @@ async def main():
         print(f"Assistant: {result.final_output}")
 ```
 
-run が承認のために一時停止し、[`RunState`][agents.run_state.RunState] から再開する場合、
+実行が承認のために一時停止し、[`RunState`][agents.run_state.RunState] から再開した場合、
 SDK は保存された `conversation_id` / `previous_response_id` / `auto_previous_response_id`
 設定を保持するため、再開されたターンは同じサーバー管理の会話で続行されます。
 
-`conversation_id` と `previous_response_id` は相互に排他的です。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用してください。1 つのターンから次のターンへ最も軽量な Responses API 継続プリミティブが必要な場合は `previous_response_id` を使用してください。
+`conversation_id` と `previous_response_id` は同時に使用できません。システム間で共有できる名前付きの会話リソースが必要な場合は `conversation_id` を使用します。あるターンから次のターンへ最も軽量な Responses API の継続基本コンポーネントが必要な場合は `previous_response_id` を使用します。
 
 !!! note
 
     SDK は `conversation_locked` エラーをバックオフ付きで自動的に再試行します。サーバー管理の
-    会話 run では、再試行前に内部の会話トラッカー入力を巻き戻すため、
-    同じ準備済み項目をきれいに再送信できます。
+    会話実行では、再試行前に内部の会話トラッカー入力を巻き戻し、同じ準備済み項目を
+    クリーンに再送信できるようにします。
 
-    ローカルのセッションベース run（`conversation_id`、
-    `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）でも、SDK は再試行後の重複履歴エントリを減らすために、
-    直近に永続化された入力項目をベストエフォートでロールバックします。
+    ローカルセッションベースの実行（`conversation_id`、
+    `previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません）では、SDK は再試行後の重複した履歴エントリを減らすために、
+    直近に永続化された入力項目のベストエフォートなロールバックも実行します。
 
-    この互換性のための再試行は、`ModelSettings.retry` を設定していない場合でも発生します。
-    モデルリクエストに対するより広範なオプトインの再試行動作については、[Runner 管理の再試行](models/index.md#runner-managed-retries) を参照してください。
+    この互換性再試行は、`ModelSettings.retry` を設定していない場合でも発生します。モデルリクエストに対するより広範なオプトインの再試行動作については、[Runner 管理の再試行](models/index.md#runner-managed-retries) を参照してください。
 
 ## フックとカスタマイズ
 
 ### モデル呼び出し入力フィルター
 
-モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。このフックは現在のエージェント、コンテキスト、および結合された入力項目（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。
+モデル呼び出しの直前にモデル入力を編集するには、`call_model_input_filter` を使用します。このフックは現在のエージェント、コンテキスト、結合された入力項目（存在する場合はセッション履歴を含む）を受け取り、新しい `ModelInputData` を返します。
 
-戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトでなければなりません。その `input` フィールドは必須で、入力項目のリストである必要があります。それ以外の形状を返すと `UserError` が発生します。
+戻り値は [`ModelInputData`][agents.run.ModelInputData] オブジェクトである必要があります。その `input` フィールドは必須で、入力項目のリストでなければなりません。それ以外の形状を返すと `UserError` が発生します。
 
 ```python
 from agents import Agent, Runner, RunConfig
@@ -402,19 +428,19 @@ result = Runner.run_sync(
 )
 ```
 
-runner は準備済み入力リストのコピーをフックに渡すため、呼び出し元の元のリストをインプレースで変更せずに、トリム、置換、並べ替えができます。
+runner は準備済み入力リストのコピーをフックに渡すため、呼び出し元の元のリストをその場で変更することなく、トリミング、置換、並べ替えができます。
 
-セッションを使用している場合、`call_model_input_filter` はセッション履歴が既に読み込まれ、現在のターンとマージされた後に実行されます。その前段のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。
+セッションを使用している場合、`call_model_input_filter` はセッション履歴がすでに読み込まれ、現在のターンとマージされた後に実行されます。その前段のマージ手順自体をカスタマイズしたい場合は、[`session_input_callback`][agents.run.RunConfig.session_input_callback] を使用してください。
 
-`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使って OpenAI のサーバー管理会話状態を使用している場合、このフックは次の Responses API 呼び出し向けに準備されたペイロードに対して実行されます。そのペイロードは、以前の履歴全体の再再生ではなく、すでに新しいターンの差分のみを表している場合があります。返した項目だけが、そのサーバー管理の継続に送信済みとしてマークされます。
+`conversation_id`、`previous_response_id`、または `auto_previous_response_id` を使用して OpenAI のサーバー管理の会話状態を使用している場合、このフックは次の Responses API 呼び出し用に準備されたペイロード上で実行されます。そのペイロードは、以前の履歴全体の再生ではなく、すでに新しいターンの差分のみを表している場合があります。返した項目だけが、そのサーバー管理の継続に対して送信済みとしてマークされます。
 
-機密データの墨消し、長い履歴のトリム、追加のシステムガイダンスの注入を行うには、`run_config` を介して run ごとにフックを設定します。
+機密データの編集、長い履歴のトリミング、追加のシステムガイダンスの挿入を行うには、実行ごとに `run_config` でこのフックを設定します。
 
 ## エラーと復旧
 
 ### エラーハンドラー
 
-すべての `Runner` エントリーポイントは、エラー種別をキーにした dict である `error_handlers` を受け取ります。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。
+すべての `Runner` エントリーポイントは、エラー種別をキーとする dict である `error_handlers` を受け取ります。サポートされるキーは `"max_turns"` と `"model_refusal"` です。`MaxTurnsExceeded` または `ModelRefusalError` を発生させる代わりに、制御された最終出力を返したい場合に使用します。
 
 ```python
 from agents import (
@@ -445,7 +471,7 @@ print(result.final_output)
 
 フォールバック出力を会話履歴に追加したくない場合は、`include_in_history=False` を設定します。
 
-モデルの拒否時に、`ModelRefusalError` で run を終了する代わりにアプリケーション固有のフォールバックを生成したい場合は、`"model_refusal"` を使用します。
+モデル拒否が `ModelRefusalError` で実行を終了するのではなく、アプリケーション固有のフォールバックを生成すべき場合は、`"model_refusal"` を使用します。
 
 ```python
 from pydantic import BaseModel
@@ -477,33 +503,37 @@ result = Runner.run_sync(
 print(result.final_output)
 ```
 
-## Durable execution integrations と human-in-the-loop
+## 耐久実行インテグレーションと human-in-the-loop
 
-ツール承認の一時停止/再開パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。
-以下のインテグレーションは、run が長い待機、再試行、またはプロセス再起動にまたがる可能性がある場合の、耐久性のあるオーケストレーション向けです。
+ツール承認の一時停止 / 再開パターンについては、専用の [Human-in-the-loop ガイド](human_in_the_loop.md) から始めてください。
+以下のインテグレーションは、実行が長い待機、再試行、またはプロセス再起動をまたぐ可能性がある場合の耐久性のあるオーケストレーション向けです。
+
+### Dapr
+
+Agents SDK の [Dapr](https://dapr.io) Diagrid インテグレーションを使用すると、human-in-the-loop サポート付きで障害から自動的に復旧する、耐久性のある長時間実行エージェントを実行できます。Dapr はベンダーニュートラルな [CNCF](https://cncf.io) ワークフローオーケストレーターです。Dapr と OpenAI エージェントの始め方は [こちら](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai) です。
 
 ### Temporal
 
-Agents SDK の [Temporal](https://temporal.io/) インテグレーションを使用すると、human-in-the-loop タスクを含む、耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間実行タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) で確認でき、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) で確認できます。 
+Agents SDK の [Temporal](https://temporal.io/) インテグレーションを使用すると、human-in-the-loop タスクを含む、耐久性のある長時間実行ワークフローを実行できます。Temporal と Agents SDK が連携して長時間実行タスクを完了するデモは [この動画](https://www.youtube.com/watch?v=fFBZqzT4DD8) で確認でき、[ドキュメントはこちら](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents) です。 
 
 ### Restate
 
-Agents SDK の [Restate](https://restate.dev/) インテグレーションは、人間による承認、ハンドオフ、セッション管理を含む、軽量で耐久性のあるエージェントに使用できます。このインテグレーションは Restate の単一バイナリランタイムを依存関係として必要とし、プロセス/コンテナーまたはサーバーレス関数としてのエージェント実行をサポートします。
+Agents SDK の [Restate](https://restate.dev/) インテグレーションを使用すると、人間による承認、ハンドオフ、セッション管理を含む、軽量で耐久性のあるエージェントを利用できます。このインテグレーションは依存関係として Restate の単一バイナリランタイムを必要とし、エージェントをプロセス / コンテナまたはサーバーレス関数として実行することをサポートします。
 詳細は [概要](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk) を読むか、[ドキュメント](https://docs.restate.dev/ai) を参照してください。
 
 ### DBOS
 
-Agents SDK の [DBOS](https://dbos.dev/) インテグレーションを使用すると、障害や再起動をまたいで進捗を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。sync と async の両方のメソッドをサポートします。このインテグレーションに必要なのは SQLite または Postgres データベースだけです。詳細はインテグレーションの [リポジトリ](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。
+Agents SDK の [DBOS](https://dbos.dev/) インテグレーションを使用すると、障害や再起動をまたいで進捗を保持する信頼性の高いエージェントを実行できます。長時間実行エージェント、human-in-the-loop ワークフロー、ハンドオフをサポートします。同期メソッドと非同期メソッドの両方をサポートします。このインテグレーションに必要なのは SQLite または Postgres データベースのみです。詳細はインテグレーションの [repo](https://github.com/dbos-inc/dbos-openai-agents) と [ドキュメント](https://docs.dbos.dev/integrations/openai-agents) を参照してください。
 
 ## 例外
 
-SDK は特定の場合に例外を発生させます。完全な一覧は [`agents.exceptions`][] にあります。概要は次のとおりです。
+SDK は特定のケースで例外を発生させます。完全な一覧は [`agents.exceptions`][] にあります。概要は以下のとおりです。
 
--   [`AgentsException`][agents.exceptions.AgentsException]: これは SDK 内で発生するすべての例外の基底クラスです。他のすべての具体的な例外が派生する汎用型として機能します。
--   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: この例外は、エージェントの run が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えたときに発生します。指定された対話ターン数内にエージェントがタスクを完了できなかったことを示します。
--   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成したときに発生します。これには以下が含まれます。
-    -   不正な JSON: モデルがツール呼び出しまたは直接出力で不正な JSON 構造を提供した場合。特に特定の `output_type` が定義されている場合です。
-    -   予期しないツール関連の失敗: モデルが期待された方法でツールを使用できなかった場合
--   [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが設定されたタイムアウトを超え、ツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。
--   [`UserError`][agents.exceptions.UserError]: この例外は、あなた（SDK を使用してコードを書く人）が SDK の使用中に誤りを犯した場合に発生します。通常、不正なコード実装、無効な設定、または SDK API の誤用が原因です。
--   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: この例外は、それぞれ入力ガードレールまたは出力ガードレールの条件が満たされたときに発生します。入力ガードレールは処理前に受信メッセージをチェックし、出力ガードレールは配信前にエージェントの最終応答をチェックします。
+-   [`AgentsException`][agents.exceptions.AgentsException]: SDK 内で発生するすべての例外の基底クラスです。他のすべての具体的な例外の派生元となる汎用型として機能します。
+-   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: この例外は、エージェントの実行が `Runner.run`、`Runner.run_sync`、または `Runner.run_streamed` メソッドに渡された `max_turns` 制限を超えた場合に発生します。エージェントが指定された相互作用ターン数内にタスクを完了できなかったことを示します。制限を無効にするには `max_turns=None` を設定します。
+-   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: この例外は、基盤となるモデル（LLM）が予期しない、または無効な出力を生成した場合に発生します。これには以下が含まれる場合があります。
+    -   不正な形式の JSON: モデルがツール呼び出しまたは直接出力で不正な形式の JSON 構造を提供した場合、特に特定の `output_type` が定義されている場合です。
+    -   予期しないツール関連の失敗: モデルが期待どおりにツールを使用できなかった場合です
+-   [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: この例外は、関数ツール呼び出しが設定されたタイムアウトを超え、そのツールが `timeout_behavior="raise_exception"` を使用している場合に発生します。
+-   [`UserError`][agents.exceptions.UserError]: この例外は、あなた（SDK を使用してコードを書いている人）が SDK の使用中にエラーを起こした場合に発生します。通常、誤ったコード実装、無効な設定、または SDK の API の誤用が原因です。
+-   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: この例外は、それぞれ入力ガードレールまたは出力ガードレールの条件が満たされた場合に発生します。入力ガードレールは処理前に受信メッセージをチェックし、出力ガードレールは配信前にエージェントの最終レスポンスをチェックします。

docs/ja/sandbox/clients.md

@@ -2,13 +2,13 @@
 search:
   exclude: true
 ---
-# Sandbox クライアント
+# サンドボックスクライアント
 
-このページでは、 sandbox の作業をどこで実行するかを選択します。ほとんどの場合、 `SandboxAgent` の定義は同じままで、 sandbox クライアントとクライアント固有のオプションのみが [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変わります。
+このページでは、サンドボックスでの作業をどこで実行するかを選択します。ほとんどの場合、`SandboxAgent` の定義は同じままにし、サンドボックスクライアントとクライアント固有のオプションを [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変更します。
 
-!!! warning "Beta 機能"
+!!! warning "ベータ機能"
 
-    Sandbox エージェントは beta です。一般提供前に API の詳細、デフォルト、対応機能が変更される可能性があり、時間の経過とともにより高度な機能も追加される予定です。
+    サンドボックスエージェントはベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能が変更される可能性があります。また、時間とともにより高度な機能が追加される見込みです。
 
 ## 判断ガイド
 
@@ -16,28 +16,28 @@ search:
 
 | 目的 | まず使うもの | 理由 |
 | --- | --- | --- |
-| macOS または Linux で最速のローカル反復 | `UnixLocalSandboxClient` | 追加インストール不要で、シンプルなローカルファイルシステム開発ができます。 |
+| macOS または Linux での最速のローカル反復 | `UnixLocalSandboxClient` | 追加インストール不要で、シンプルなローカルファイルシステム開発ができます。 |
 | 基本的なコンテナ分離 | `DockerSandboxClient` | 特定のイメージを使って Docker 内で作業を実行します。 |
-| ホスト型実行または本番環境に近い分離 | ホスト型 sandbox クライアント | ワークスペースの境界をプロバイダー管理の環境に移します。 |
+| ホスト型実行または本番環境スタイルの分離 | ホスト型サンドボックスクライアント | ワークスペース境界をプロバイダー管理環境へ移します。 |
 
 </div>
 
 ## ローカルクライアント
 
-ほとんどのユーザーは、まず次の 2 つの sandbox クライアントのいずれかから始めてください。
+ほとんどのユーザーは、これら 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 に切り替えるには、エージェント定義はそのままにして、 run config のみを変更します。
+Unix-local から Docker に切り替えるには、エージェント定義は同じままにして、実行設定だけを変更します。
 
 ```python
 from docker import from_env as docker_from_env
@@ -54,74 +54,74 @@ run_config = RunConfig(
 )
 ```
 
-これは、コンテナ分離やイメージの同等性が必要な場合に使用します。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
+コンテナ分離またはイメージの同等性が必要な場合に使用してください。[examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
 
 ## マウントとリモートストレージ
 
-mount エントリは公開するストレージを記述し、 mount 戦略は sandbox バックエンドがそのストレージをどのように接続するかを記述します。組み込みの mount エントリと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダーの戦略は `agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。
+マウントエントリーはどのストレージを公開するかを表し、マウント戦略はサンドボックスバックエンドがそのストレージをどのようにアタッチするかを表します。組み込みのマウントエントリーと汎用戦略は `agents.sandbox.entries` からインポートします。ホスト型プロバイダーの戦略は `agents.extensions.sandbox` またはプロバイダー固有の拡張パッケージから利用できます。
 
-一般的な mount オプション:
+一般的なマウントオプション:
 
-- `mount_path`: sandbox 内でストレージが表示される場所です。相対パスは manifest ルート配下で解決され、絶対パスはそのまま使われます。
-- `read_only`: デフォルトは `True` です。 sandbox からマウントされたストレージへ書き戻す必要がある場合にのみ `False` に設定してください。
-- `mount_strategy`: 必須です。 mount エントリと sandbox バックエンドの両方に適合する戦略を使用してください。
+- `mount_path`: ストレージがサンドボックス内で表示される場所です。相対パスはマニフェストルート配下で解決され、絶対パスはそのまま使用されます。
+- `read_only`: 既定は `True` です。サンドボックスがマウントされたストレージへ書き戻す必要がある場合にのみ `False` に設定してください。
+- `mount_strategy`: 必須です。マウントエントリーとサンドボックスバックエンドの両方に合う戦略を使用してください。
 
-mount は一時的なワークスペースエントリとして扱われます。スナップショットおよび永続化フローでは、マウントされたリモートストレージを保存済みワークスペースにコピーするのではなく、マウントされたパスを切り離すかスキップします。
+マウントは一時的なワークスペースエントリーとして扱われます。スナップショットと永続化のフローでは、マウントされたリモートストレージを保存済みワークスペースへコピーするのではなく、マウントされたパスをデタッチするかスキップします。
 
-汎用のローカル / コンテナ戦略:
+汎用ローカル / コンテナ戦略:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 戦略またはパターン | 使用する場面 | 注記 |
+| 戦略またはパターン | 使用する場面 | 備考 |
 | --- | --- | --- |
-| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | sandbox イメージで `rclone` を実行できる場合。 | S3 、 GCS 、 R2 、 Azure Blob 、 Box をサポートします。`RcloneMountPattern` は `fuse` モードまたは `nfs` モードで実行できます。 |
-| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` があり、 Mountpoint スタイルの S3 または S3 互換アクセスを使いたい場合。 | `S3Mount` と `GCSMount` をサポートします。 |
-| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` と FUSE サポートがある場合。 | `AzureBlobMount` をサポートします。 |
-| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` があり、既存の S3 Files mount ターゲットに到達できる場合。 | `S3FilesMount` をサポートします。 |
-| `DockerVolumeMountStrategy(driver=...)` | コンテナ起動前に Docker が volume-driver ベースの mount を接続すべき場合。 | Docker 専用です。 S3 、 GCS 、 R2 、 Azure Blob 、 Box は `rclone` をサポートし、 S3 と GCS は `mountpoint` もサポートします。 |
+| `InContainerMountStrategy(pattern=RcloneMountPattern(...))` | サンドボックスイメージで `rclone` を実行できる場合。 | S3、GCS、R2、Azure Blob、Box をサポートします。`RcloneMountPattern` は `fuse` モードまたは `nfs` モードで実行できます。 |
+| `InContainerMountStrategy(pattern=MountpointMountPattern(...))` | イメージに `mount-s3` があり、Mountpoint スタイルの S3 または S3 互換アクセスが必要な場合。 | `S3Mount` と `GCSMount` をサポートします。 |
+| `InContainerMountStrategy(pattern=FuseMountPattern(...))` | イメージに `blobfuse2` があり、FUSE サポートがある場合。 | `AzureBlobMount` をサポートします。 |
+| `InContainerMountStrategy(pattern=S3FilesMountPattern(...))` | イメージに `mount.s3files` があり、既存の S3 Files マウントターゲットに到達できる場合。 | `S3FilesMount` をサポートします。 |
+| `DockerVolumeMountStrategy(driver=...)` | Docker がコンテナ起動前にボリュームドライバー対応のマウントをアタッチする必要がある場合。 | Docker のみです。`rclone` は S3、GCS、R2、Azure Blob、Box をサポートし、`mountpoint` は S3 と GCS もサポートします。 |
 
 </div>
 
-## 対応するホスト型プラットフォーム
+## サポートされるホスト型プラットフォーム
 
-ホスト型環境が必要な場合でも、通常は同じ `SandboxAgent` 定義をそのまま使え、 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で sandbox クライアントのみを変更します。
+ホスト型環境が必要な場合、通常は同じ `SandboxAgent` 定義をそのまま引き継ぎ、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] でサンドボックスクライアントだけを変更します。
 
-このリポジトリのチェックアウト版ではなく公開済み SDK を使っている場合は、対応するパッケージ extra を通じて sandbox-client 依存関係をインストールしてください。
+このリポジトリのチェックアウトではなく公開されている SDK を使用している場合は、対応するパッケージ extra を通じてサンドボックスクライアントの依存関係をインストールしてください。
 
-プロバイダー固有のセットアップに関する注意点や、リポジトリに含まれる拡張の例へのリンクについては、 [examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md) を参照してください。
+プロバイダー固有のセットアップメモと、チェックイン済みの拡張コード例へのリンクについては、[examples/sandbox/extensions/README.md](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/README.md) を参照してください。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
 | クライアント | インストール | 例 |
 | --- | --- | --- |
-| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
-| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
-| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) |
-| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) |
-| `ModalSandboxClient` | `openai-agents[modal]` | [Modal runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) |
-| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) |
-| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
+| `BlaxelSandboxClient` | `openai-agents[blaxel]` | [Blaxel ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) |
+| `CloudflareSandboxClient` | `openai-agents[cloudflare]` | [Cloudflare ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/cloudflare_runner.py) |
+| `DaytonaSandboxClient` | `openai-agents[daytona]` | [Daytona ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/daytona/daytona_runner.py) |
+| `E2BSandboxClient` | `openai-agents[e2b]` | [E2B ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) |
+| `ModalSandboxClient` | `openai-agents[modal]` | [Modal ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) |
+| `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) |
+| `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel ランナー](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
 
 </div>
 
-ホスト型 sandbox クライアントは、プロバイダー固有の mount 戦略を公開しています。ストレージプロバイダーに最も適したバックエンドと mount 戦略を選択してください。
+ホスト型サンドボックスクライアントは、プロバイダー固有のマウント戦略を公開します。ストレージプロバイダーに最も合うバックエンドとマウント戦略を選択してください。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| バックエンド | mount に関する注記 |
+| バックエンド | マウントに関する注記 |
 | --- | --- |
-| Docker | `S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` 、 `S3FilesMount` を、 `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略でサポートします。 |
-| `ModalSandboxClient` | `S3Mount` 、 `R2Mount` 、 HMAC 認証された `GCSMount` に対して、 `ModalCloudBucketMountStrategy` による Modal cloud bucket mount をサポートします。インライン認証情報または名前付き Modal Secret を使用できます。 |
-| `CloudflareSandboxClient` | `S3Mount` 、 `R2Mount` 、 HMAC 認証された `GCSMount` に対して、 `CloudflareBucketMountStrategy` による Cloudflare bucket mount をサポートします。 |
-| `BlaxelSandboxClient` | `S3Mount` 、 `R2Mount` 、 `GCSMount` に対して、 `BlaxelCloudBucketMountStrategy` による cloud bucket mount をサポートします。また、 `agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` による永続的な Blaxel Drive もサポートします。 |
-| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 |
-| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 |
-| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` による rclone ベースの cloud storage mount をサポートします。`S3Mount` 、 `GCSMount` 、 `R2Mount` 、 `AzureBlobMount` 、 `BoxMount` と組み合わせて使用します。 |
-| `VercelSandboxClient` | 現時点ではホスト型固有の mount 戦略は公開されていません。代わりに manifest ファイル、リポジトリ、またはその他のワークスペース入力を使用してください。 |
+| Docker | `InContainerMountStrategy` や `DockerVolumeMountStrategy` などのローカル戦略で、`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` をサポートします。 |
+| `ModalSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`ModalCloudBucketMountStrategy` による Modal のクラウドバケットマウントをサポートします。インライン認証情報、または名前付きの Modal Secret を使用できます。 |
+| `CloudflareSandboxClient` | `S3Mount`、`R2Mount`、HMAC 認証済みの `GCSMount` で、`CloudflareBucketMountStrategy` による Cloudflare バケットマウントをサポートします。 |
+| `BlaxelSandboxClient` | `S3Mount`、`R2Mount`、`GCSMount` で、`BlaxelCloudBucketMountStrategy` によるクラウドバケットマウントをサポートします。`agents.extensions.sandbox.blaxel` の `BlaxelDriveMount` と `BlaxelDriveMountStrategy` による永続的な Blaxel Drives もサポートします。 |
+| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `E2BSandboxClient` | `E2BCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy` による `rclone` ベースのクラウドストレージマウントをサポートします。`S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount` と組み合わせて使用してください。 |
+| `VercelSandboxClient` | 現時点ではホスト型固有のマウント戦略は公開されていません。代わりにマニフェストファイル、リポジトリ、またはその他のワークスペース入力を使用してください。 |
 
 </div>
 
-以下の表は、各バックエンドがどのリモートストレージエントリを直接マウントできるかをまとめたものです。
+以下の表は、各バックエンドが直接マウントできるリモートストレージエントリーをまとめたものです。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
@@ -138,4 +138,4 @@ mount は一時的なワークスペースエントリとして扱われます
 
 </div>
 
-さらに実行可能な例については、ローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターンは [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox) を、ホスト型 sandbox クライアントについては [examples/sandbox/extensions/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox/extensions) を参照してください。
+実行可能なコード例をさらに見るには、ローカル、コーディング、メモリ、ハンドオフ、エージェント合成パターンについては [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) を参照してください。

docs/ja/sandbox/guide.md

@@ -6,11 +6,11 @@ search:
 
 !!! warning "ベータ機能"
 
-    サンドボックスエージェントはベータ版です。一般提供までに API、デフォルト、対応機能の詳細が変更される可能性があり、今後より高度な機能が追加される見込みです。
+    サンドボックスエージェントはベータ版です。一般提供前に API の詳細、デフォルト、サポートされる機能が変更される可能性があります。また、時間の経過とともにより高度な機能が追加される予定です。
 
-現代のエージェントは、ファイルシステム上の実ファイルを扱えるときに最もよく機能します。 **サンドボックスエージェント** は、専用ツールやシェルコマンドを利用して、大規模なドキュメントセットの検索や操作、ファイル編集、成果物生成、コマンド実行を行えます。サンドボックスは、エージェントがあなたに代わって作業するために使える永続的なワークスペースをモデルに提供します。Agents SDK のサンドボックスエージェントは、サンドボックス環境と組み合わせたエージェントを簡単に実行できるようにし、ファイルシステム上に適切なファイルを配置し、サンドボックスをオーケストレーションして、大規模にタスクの開始、停止、再開を容易にします。
+現代的なエージェントは、ファイルシステム上の実ファイルを操作できるときに最も効果的に動作します。**サンドボックスエージェント** は、専用ツールとシェルコマンドを使用して、大規模なドキュメントセットの検索や操作、ファイルの編集、成果物の生成、コマンドの実行を行えます。サンドボックスは、エージェントがユーザーの代わりに作業するために利用できる永続的なワークスペースをモデルに提供します。Agents SDK のサンドボックスエージェントは、サンドボックス環境と組み合わせたエージェントを簡単に実行できるようにし、ファイルシステム上に適切なファイルを配置し、サンドボックスをオーケストレーションして、タスクを大規模に開始、停止、再開しやすくします。
 
-エージェントが必要とするデータを中心にワークスペースを定義します。GitHub リポジトリ、ローカルのファイルやディレクトリ、合成タスクファイル、S3 や Azure Blob Storage などのリモートファイルシステム、その他あなたが提供するサンドボックス入力から開始できます。
+エージェントが必要とするデータを中心にワークスペースを定義します。ワークスペースは、GitHub リポジトリ、ローカルファイルとディレクトリ、合成タスクファイル、S3 や Azure Blob Storage などのリモートファイルシステム、その他提供するサンドボックス入力から開始できます。
 
 <div class="sandbox-harness-image" markdown="1">
 
@@ -18,23 +18,23 @@ search:
 
 </div>
 
-`SandboxAgent` は依然として `Agent` です。`instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、ガードレール、フックなど通常のエージェントインターフェイスを維持し、通常の `Runner` API を通じて実行されます。変わるのは実行境界です。
+`SandboxAgent` は引き続き `Agent` です。`instructions`、`prompt`、`tools`、`handoffs`、`mcp_servers`、`model_settings`、`output_type`、ガードレール、フックなど、通常のエージェントのインターフェイスを保持し、通常の `Runner` API を通じて実行されます。変わるのは実行境界です。
 
-- `SandboxAgent` はエージェント自体を定義します。通常のエージェント設定に加え、`default_manifest`、`base_instructions`、`run_as` などのサンドボックス固有のデフォルト、ファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションなどの機能を定義します。
-- `Manifest` は、新しいサンドボックスワークスペースの開始時の内容とレイアウトを宣言します。これには、ファイル、リポジトリ、マウント、環境が含まれます。
-- サンドボックスセッションは、コマンドが実行されファイルが変更される、稼働中の分離環境です。
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、その実行がどのようにサンドボックスセッションを取得するかを決定します。たとえば、直接注入する、シリアライズされたサンドボックスセッション状態から再接続する、またはサンドボックスクライアントを通じて新しいサンドボックスセッションを作成するなどです。
-- 保存されたサンドボックス状態とスナップショットにより、後続の実行が以前の作業へ再接続したり、保存された内容から新しいサンドボックスセッションを初期化したりできます。
+- `SandboxAgent` はエージェント自体を定義します。通常のエージェント設定に加えて、`default_manifest`、`base_instructions`、`run_as` などのサンドボックス固有のデフォルト、ファイルシステムツール、シェルアクセス、スキル、メモリ、コンパクションなどの機能を含みます。
+- `Manifest` は、ファイル、リポジトリ、マウント、環境など、新規サンドボックスワークスペースの望ましい初期内容とレイアウトを宣言します。
+- サンドボックスセッションは、コマンドが実行されファイルが変更される、ライブの隔離環境です。
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、実行がサンドボックスセッションをどのように取得するかを決定します。たとえば、直接注入する、シリアライズ済みのサンドボックスセッション状態から再接続する、またはサンドボックスクライアントを通じて新規サンドボックスセッションを作成する、といった方法があります。
+- 保存済みのサンドボックス状態とスナップショットにより、後続の実行は以前の作業に再接続したり、保存済みの内容から新規サンドボックスセッションを初期化したりできます。
 
-`Manifest` は新規セッションのワークスペース契約であり、すべての稼働中サンドボックスの完全な信頼できる情報源ではありません。実行における実効ワークスペースは、再利用されたサンドボックスセッション、シリアライズされたサンドボックスセッション状態、または実行時に選択されたスナップショットから来る場合もあります。
+`Manifest` は新規セッションのワークスペース契約であり、すべてのライブサンドボックスに対する完全な唯一の情報源ではありません。実行の有効なワークスペースは、再利用されたサンドボックスセッション、シリアライズ済みのサンドボックスセッション状態、または実行時に選択されたスナップショットから取得される場合があります。
 
-このページ全体で、「サンドボックスセッション」とは、サンドボックスクライアントによって管理される稼働中の実行環境を意味します。これは、[Sessions](../sessions/index.md) で説明されている SDK の会話用 [`Session`][agents.memory.session.Session] インターフェイスとは異なります。
+このページ全体で、「サンドボックスセッション」とはサンドボックスクライアントによって管理されるライブ実行環境を意味します。これは、[Sessions](../sessions/index.md) で説明されている SDK の会話型 [`Session`][agents.memory.session.Session] インターフェイスとは異なります。
 
-外側のランタイムは、承認、トレーシング、ハンドオフ、再開の記録管理を引き続き所有します。サンドボックスセッションは、コマンド、ファイル変更、環境分離を所有します。この分担はモデルの中核部分です。
+外側のランタイムは引き続き、承認、トレーシング、ハンドオフ、再開の記録管理を所有します。サンドボックスセッションは、コマンド、ファイル変更、環境隔離を所有します。この分担は、このモデルの中核です。
 
-### 構成要素の関係
+### 各要素の関係
 
-サンドボックス実行は、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。Runner はエージェントを準備し、稼働中のサンドボックスセッションにバインドし、後続の実行のために状態を保存できます。
+サンドボックス実行は、エージェント定義と実行ごとのサンドボックス設定を組み合わせます。Runner はエージェントを準備し、ライブのサンドボックスセッションにバインドし、後続の実行のために状態を保存できます。
 
 ```mermaid
 flowchart LR
@@ -55,38 +55,38 @@ flowchart LR
 ライフサイクルは 3 つのフェーズで考えてください。
 
 1. `SandboxAgent`、`Manifest`、機能を使って、エージェントと新規ワークスペース契約を定義します。
-2. サンドボックスセッションを注入、再開、または作成する `SandboxRunConfig` を `Runner` に渡して実行します。
-3. Runner が管理する `RunState`、明示的なサンドボックス `session_state`、または保存されたワークスペーススナップショットから後で継続します。
+2. サンドボックスセッションを注入、再開、または作成する `SandboxRunConfig` を `Runner` に渡して、実行を行います。
+3. Runner 管理の `RunState`、明示的なサンドボックス `session_state`、または保存済みワークスペーススナップショットから、後で継続します。
 
-シェルアクセスがたまに使うツールの 1 つにすぎない場合は、[ツールガイド](../tools.md) のホスト型シェルから始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合は、サンドボックスエージェントを使ってください。
+シェルアクセスが時々使うツールの 1 つにすぎない場合は、[ツールガイド](../tools.md) のホスト型シェルから始めてください。ワークスペースの隔離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計の一部である場合は、サンドボックスエージェントを選択してください。
 
 ## 使用すべき場面
 
 サンドボックスエージェントは、ワークスペース中心のワークフローに適しています。例:
 
-- コーディングとデバッグ。たとえば GitHub リポジトリ内の issue レポートに対する自動修正をオーケストレーションし、対象テストを実行する場合
-- ドキュメント処理と編集。たとえばユーザーの財務書類から情報を抽出し、記入済みの税務フォーム草案を作成する場合
-- ファイルに基づくレビューや分析。たとえば回答前にオンボーディング資料、生成されたレポート、成果物バンドルを確認する場合
-- 分離されたマルチエージェントパターン。たとえば各レビュアーやコーディングサブエージェントに専用ワークスペースを与える場合
-- 複数ステップのワークスペースタスク。たとえば 1 回の実行でバグを修正し、後でリグレッションテストを追加する場合や、スナップショットまたはサンドボックスセッション状態から再開する場合
+- コーディングとデバッグ。たとえば、GitHub リポジトリ内の issue レポートに対する自動修正をオーケストレーションし、対象を絞ったテストを実行する場合
+- ドキュメント処理と編集。たとえば、ユーザーの財務ドキュメントから情報を抽出し、完成済みの税務フォーム草案を作成する場合
+- ファイルに基づくレビューまたは分析。たとえば、回答前にオンボーディング資料、生成されたレポート、成果物バンドルを確認する場合
+- 隔離されたマルチエージェントパターン。たとえば、各レビュアーまたはコーディングサブエージェントに独自のワークスペースを与える場合
+- 複数ステップのワークスペースタスク。たとえば、ある実行でバグを修正し、後で回帰テストを追加する場合、またはスナップショットやサンドボックスセッション状態から再開する場合
 
-ファイルや生きたファイルシステムへのアクセスが不要な場合は、`Agent` を使い続けてください。シェルアクセスがたまに使う機能にすぎない場合はホスト型シェルを追加します。ワークスペース境界自体が機能の一部である場合は、サンドボックスエージェントを使います。
+ファイルや生きたファイルシステムへのアクセスが不要な場合は、`Agent` を使い続けてください。シェルアクセスが時々使う機能の 1 つにすぎない場合は、ホスト型シェルを追加してください。ワークスペース境界自体が機能の一部である場合は、サンドボックスエージェントを使用してください。
 
 ## サンドボックスクライアントの選択
 
-ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ分離やイメージの同等性が必要になったら `DockerSandboxClient` に移行します。プロバイダー管理の実行が必要な場合は、ホスト型プロバイダーに移行します。
+ローカル開発では `UnixLocalSandboxClient` から始めてください。コンテナ隔離やイメージの一致性が必要になったら `DockerSandboxClient` に移行してください。プロバイダー管理の実行が必要になったら、ホスト型プロバイダーに移行してください。
 
-ほとんどの場合、[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] でサンドボックスクライアントとそのオプションを変更しても、`SandboxAgent` 定義は同じままです。ローカル、Docker、ホスト型、リモートマウントのオプションについては [サンドボックスクライアント](clients.md) を参照してください。
+ほとんどの場合、`SandboxAgent` 定義は同じままで、サンドボックスクライアントとそのオプションを [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] で変更します。ローカル、Docker、ホスト型、リモートマウントのオプションについては、[サンドボックスクライアント](clients.md) を参照してください。
 
 ## 主要な構成要素
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| レイヤー | 主な SDK 構成要素 | 答える内容 |
+| レイヤー | 主な SDK 構成要素 | 答える問い |
 | --- | --- | --- |
-| エージェント定義 | `SandboxAgent`、`Manifest`、機能 | どのエージェントを実行し、新規セッションのワークスペース契約は何から開始すべきか。 |
-| サンドボックス実行 | `SandboxRunConfig`、サンドボックスクライアント、稼働中のサンドボックスセッション | この実行はどのように稼働中のサンドボックスセッションを取得し、作業はどこで実行されるか。 |
-| 保存されたサンドボックス状態 | `RunState` サンドボックスペイロード、`session_state`、スナップショット | このワークフローは、以前のサンドボックス作業にどのように再接続するか、または保存内容から新しいサンドボックスセッションをどのように初期化するか。 |
+| エージェント定義 | `SandboxAgent`, `Manifest`, capabilities | どのエージェントを実行し、新規セッションのワークスペース契約を何から開始すべきですか？ |
+| サンドボックス実行 | `SandboxRunConfig`、サンドボックスクライアント、ライブサンドボックスセッション | この実行はライブサンドボックスセッションをどのように取得し、作業はどこで実行されますか？ |
+| 保存済みサンドボックス状態 | `RunState` サンドボックスペイロード、`session_state`、スナップショット | このワークフローは以前のサンドボックス作業にどのように再接続するか、または保存済み内容から新規サンドボックスセッションをどのように初期化しますか？ |
 
 </div>
 
@@ -94,157 +94,161 @@ flowchart LR
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 構成要素 | 所有するもの | 問うべき質問 |
+| 構成要素 | 管理するもの | 問うべきこと |
 | --- | --- | --- |
-| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | エージェント定義 | このエージェントは何をすべきで、どのデフォルトを一緒に持たせるべきか。 |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 新規セッションのワークスペースファイルとフォルダー | 実行開始時にファイルシステム上にどのファイルとフォルダーが存在すべきか。 |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | サンドボックスネイティブな動作 | このエージェントにどのツール、instruction 断片、またはランタイム動作を付与すべきか。 |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 実行ごとのサンドボックスクライアントとサンドボックスセッションソース | この実行はサンドボックスセッションを注入、再開、または作成すべきか。 |
-| [`RunState`][agents.run_state.RunState] | Runner が管理する保存済みサンドボックス状態 | 以前の Runner 管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継いでいるか。 |
-| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 明示的にシリアライズされたサンドボックスセッション状態 | `RunState` の外で既にシリアライズしたサンドボックス状態から再開したいか。 |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 新しいサンドボックスセッション用の保存済みワークスペース内容 | 新しいサンドボックスセッションを保存済みファイルや成果物から開始すべきか。 |
+| [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | エージェント定義 | このエージェントは何を行うべきで、どのデフォルトを一緒に持ち運ぶべきですか？ |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 新規セッションのワークスペースファイルとフォルダー | 実行開始時に、ファイルシステム上にどのファイルとフォルダーが存在すべきですか？ |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | サンドボックスネイティブな挙動 | どのツール、指示の断片、またはランタイム挙動をこのエージェントに付与すべきですか？ |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 実行ごとのサンドボックスクライアントとサンドボックスセッションの取得元 | この実行ではサンドボックスセッションを注入、再開、または作成すべきですか？ |
+| [`RunState`][agents.run_state.RunState] | Runner が管理する保存済みサンドボックス状態 | 以前の Runner 管理ワークフローを再開し、そのサンドボックス状態を自動的に引き継いでいますか？ |
+| [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 明示的なシリアライズ済みサンドボックスセッション状態 | `RunState` の外部で既にシリアライズしたサンドボックス状態から再開したいですか？ |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 新規サンドボックスセッション用の保存済みワークスペース内容 | 新規サンドボックスセッションを保存済みファイルや成果物から開始すべきですか？ |
 
 </div>
 
-実用的な設計順序は次のとおりです。
+実践的な設計順序は次のとおりです。
 
 1. `Manifest` で新規セッションのワークスペース契約を定義します。
 2. `SandboxAgent` でエージェントを定義します。
-3. 組み込みまたはカスタム機能を追加します。
-4. `RunConfig(sandbox=SandboxRunConfig(...))` で、各実行がサンドボックスセッションをどのように取得するかを決定します。
+3. 組み込みまたはカスタムの機能を追加します。
+4. 各実行がサンドボックスセッションをどのように取得するかを `RunConfig(sandbox=SandboxRunConfig(...))` で決定します。
 
 ## サンドボックス実行の準備
 
-実行時、Runner はその定義を具体的なサンドボックス付き実行に変換します。
+実行時に、Runner はその定義を具体的なサンドボックス backed の実行に変換します。
 
 1. `SandboxRunConfig` からサンドボックスセッションを解決します。
-   `session=...` を渡した場合、その稼働中のサンドボックスセッションを再利用します。
-   それ以外の場合は、`client=...` を使って作成または再開します。
-2. 実行の実効ワークスペース入力を決定します。
+   `session=...` を渡すと、そのライブサンドボックスセッションを再利用します。
+   それ以外の場合は、`client=...` を使用して作成または再開します。
+2. 実行の有効なワークスペース入力を決定します。
    実行がサンドボックスセッションを注入または再開する場合、その既存のサンドボックス状態が優先されます。
-   そうでない場合、Runner は一時的な manifest オーバーライドまたは `agent.default_manifest` から開始します。
-   これが、`Manifest` だけではすべての実行の最終的な稼働中ワークスペースを定義しない理由です。
-3. 機能に、結果として得られた manifest を処理させます。
-   これにより、最終的なエージェントが準備される前に、機能がファイル、マウント、その他ワークスペーススコープの動作を追加できます。
+   それ以外の場合、Runner は 1 回限りのマニフェストオーバーライド、または `agent.default_manifest` から開始します。
+   そのため、`Manifest` だけでは、すべての実行における最終的なライブワークスペースは定義されません。
+3. 機能に、結果として得られたマニフェストを処理させます。
+   これにより、最終的なエージェントを準備する前に、機能がファイル、マウント、またはその他のワークスペーススコープの挙動を追加できます。
 4. 固定された順序で最終的な instructions を構築します。
-   SDK のデフォルトサンドボックスプロンプト、または明示的に上書きした場合は `base_instructions`、次に `instructions`、次に機能の instruction 断片、次に任意のリモートマウントポリシーテキスト、最後にレンダリングされたファイルシステムツリーです。
-5. 機能ツールを稼働中のサンドボックスセッションにバインドし、準備済みエージェントを通常の `Runner` API を通じて実行します。
+   SDK のデフォルトサンドボックスプロンプト、または明示的にオーバーライドした場合は `base_instructions`、次に `instructions`、次に機能の指示断片、次にリモートマウントのポリシーテキスト、最後にレンダリングされたファイルシステムツリーです。
+5. 機能ツールをライブサンドボックスセッションにバインドし、通常の `Runner` API を通じて準備済みエージェントを実行します。
 
-サンドボックス化は、ターンの意味を変えません。ターンは依然としてモデルステップであり、単一のシェルコマンドやサンドボックスアクションではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。一部の作業はサンドボックス実行レイヤー内にとどまる一方、他のアクションはツール結果、承認、または別のモデルステップを必要とするその他の状態を返す場合があります。実用上の規則として、サンドボックス作業の後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、追加のターンが消費されます。
+サンドボックス化によって、ターンの意味は変わりません。ターンは引き続きモデルステップであり、単一のシェルコマンドやサンドボックスアクションではありません。サンドボックス側の操作とターンの間に固定の 1:1 対応はありません。一部の作業はサンドボックス実行レイヤー内に留まる一方、別のアクションはツール結果、承認、または次のモデルステップを必要とするその他の状態を返す場合があります。実践上の規則として、サンドボックス作業の後にエージェントランタイムが別のモデル応答を必要とする場合にのみ、もう 1 ターンが消費されます。
 
-これらの準備ステップがあるため、`SandboxAgent` を設計する際に考えるべき主なサンドボックス固有オプションは、`default_manifest`、`instructions`、`base_instructions`、`capabilities`、`run_as` です。
+これらの準備手順があるため、`SandboxAgent` を設計するときに考えるべき主なサンドボックス固有オプションは、`default_manifest`、`instructions`、`base_instructions`、`capabilities`、`run_as` です。
 
-## `SandboxAgent` オプション
+## `SandboxAgent` のオプション
 
-通常の `Agent` フィールドに加えて、サンドボックス固有のオプションは次のとおりです。
+通常の `Agent` フィールドに加えて用意されている、サンドボックス固有のオプションは次のとおりです。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| オプション | 最適な用途 |
+| オプション | 主な用途 |
 | --- | --- |
-| `default_manifest` | Runner が作成する新しいサンドボックスセッションのデフォルトワークスペース。 |
+| `default_manifest` | Runner が作成する新規サンドボックスセッションのデフォルトワークスペース。 |
 | `instructions` | SDK サンドボックスプロンプトの後に追加される、追加の役割、ワークフロー、成功基準。 |
-| `base_instructions` | SDK サンドボックスプロンプトを置き換える高度なエスケープハッチ。 |
-| `capabilities` | このエージェントと一緒に持たせるべきサンドボックスネイティブなツールと動作。 |
+| `base_instructions` | SDK サンドボックスプロンプトを置き換える高度なオーバーライド手段。 |
+| `capabilities` | このエージェントと一緒に持ち運ぶべきサンドボックスネイティブなツールと挙動。 |
 | `run_as` | シェルコマンド、ファイル読み取り、パッチなど、モデル向けサンドボックスツールのユーザー ID。 |
 
 </div>
 
-サンドボックスクライアントの選択、サンドボックスセッションの再利用、manifest オーバーライド、スナップショット選択は、エージェントではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。
+サンドボックスクライアントの選択、サンドボックスセッションの再利用、マニフェストオーバーライド、スナップショット選択は、エージェントではなく [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] に属します。
 
 ### `default_manifest`
 
-`default_manifest` は、このエージェント用に Runner が新しいサンドボックスセッションを作成するときに使われるデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。エージェントが通常開始時に持つべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使います。
+`default_manifest` は、Runner がこのエージェント用に新規サンドボックスセッションを作成するときに使用されるデフォルトの [`Manifest`][agents.sandbox.manifest.Manifest] です。エージェントが通常開始すべきファイル、リポジトリ、補助資料、出力ディレクトリ、マウントに使用します。
 
-これはデフォルトにすぎません。実行は `SandboxRunConfig(manifest=...)` で上書きでき、再利用または再開されたサンドボックスセッションは既存のワークスペース状態を保持します。
+これはデフォルトにすぎません。実行は `SandboxRunConfig(manifest=...)` でこれをオーバーライドできます。また、再利用または再開されたサンドボックスセッションは、既存のワークスペース状態を保持します。
 
 ### `instructions` と `base_instructions`
 
-異なるプロンプトをまたいでも維持すべき短いルールには `instructions` を使います。`SandboxAgent` では、これらの instructions は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保ちながら、独自の役割、ワークフロー、成功基準を追加できます。
+異なるプロンプトでも維持すべき短いルールには `instructions` を使用します。`SandboxAgent` では、これらの instructions は SDK のサンドボックスベースプロンプトの後に追加されるため、組み込みのサンドボックスガイダンスを保持しつつ、独自の役割、ワークフロー、成功基準を追加できます。
 
-SDK のサンドボックスベースプロンプトを置き換えたい場合にのみ `base_instructions` を使います。ほとんどのエージェントでは設定すべきではありません。
+SDK サンドボックスベースプロンプトを置き換えたい場合にのみ、`base_instructions` を使用してください。ほとんどのエージェントでは設定すべきではありません。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 配置先 | 用途 | 例 |
+| 配置先... | 用途 | 例 |
 | --- | --- | --- |
-| `instructions` | エージェントの安定した役割、ワークフロールール、成功基準。 | 「オンボーディング書類を確認してからハンドオフする。」「最終ファイルを `output/` に書き込む。」 |
+| `instructions` | エージェントの安定した役割、ワークフロールール、成功基準。 | 「オンボーディングドキュメントを調査してから、ハンドオフします。」、「最終ファイルを `output/` に書き込みます。」 |
 | `base_instructions` | SDK サンドボックスベースプロンプトの完全な置き換え。 | カスタムの低レベルサンドボックスラッパープロンプト。 |
-| ユーザープロンプト | この実行の一回限りの依頼。 | 「このワークスペースを要約してください。」 |
-| manifest 内のワークスペースファイル | より長いタスク仕様、リポジトリローカルの指示、または範囲を限定した参考資料。 | `repo/task.md`、ドキュメントバンドル、サンプルパケット。 |
+| ユーザープロンプト | この実行の 1 回限りのリクエスト。 | 「このワークスペースを要約してください。」 |
+| マニフェスト内のワークスペースファイル | より長いタスク仕様、リポジトリローカルの指示、または範囲が限定された参照資料。 | `repo/task.md`、ドキュメントバンドル、サンプルパケット。 |
 
 </div>
 
-`instructions` の適切な用途は次のとおりです。
+`instructions` の適切な用途には、次のようなものがあります。
 
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) は、PTY 状態が重要な場合にエージェントを 1 つの対話型プロセス内に保ちます。
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py) は、PTY 状態が重要な場合に、エージェントを 1 つの対話型プロセス内に留めます。
 - [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) は、サンドボックスレビュアーが検査後にユーザーへ直接回答することを禁止します。
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) は、最終的な記入済みファイルが実際に `output/` に配置されることを要求します。
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) は、最終的に記入済みのファイルが実際に `output/` に配置されることを要求します。
 - [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) は、正確な検証コマンドを固定し、ワークスペースルート相対のパッチパスを明確にします。
 
-ユーザーの一回限りのタスクを `instructions` にコピーすること、manifest に含めるべき長い参考資料を埋め込むこと、組み込み機能がすでに注入するツールドキュメントを再記述すること、実行時にモデルが必要としないローカルインストールメモを混ぜることは避けてください。
+ユーザーの 1 回限りのタスクを `instructions` にコピーすること、マニフェストに置くべき長い参照資料を埋め込むこと、組み込み機能が既に注入するツールドキュメントを繰り返すこと、または実行時にモデルが必要としないローカルインストールメモを混ぜることは避けてください。
 
-`instructions` を省略しても、SDK はデフォルトのサンドボックスプロンプトを含めます。これは低レベルラッパーには十分ですが、ほとんどのユーザー向けエージェントでは明示的な `instructions` を提供すべきです。
+`instructions` を省略しても、SDK はデフォルトのサンドボックスプロンプトを含めます。低レベルのラッパーにはそれで十分ですが、ほとんどのユーザー向けエージェントでは、明示的な `instructions` を提供すべきです。
 
 ### `capabilities`
 
-機能は、サンドボックスネイティブな動作を `SandboxAgent` に付与します。実行開始前にワークスペースを整形し、サンドボックス固有の instructions を追加し、稼働中のサンドボックスセッションにバインドされるツールを公開し、そのエージェントのモデル動作や入力処理を調整できます。
+機能は、サンドボックスネイティブな挙動を `SandboxAgent` に付与します。実行開始前にワークスペースを形作り、サンドボックス固有の指示を追加し、ライブサンドボックスセッションにバインドされるツールを公開し、そのエージェントのモデル挙動や入力処理を調整できます。
 
 組み込み機能には次のものがあります。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 機能 | 追加する場面 | 注記 |
+| 機能 | 追加する場面 | 注意 |
 | --- | --- | --- |
-| `Shell` | エージェントにシェルアクセスが必要な場合。 | `exec_command` を追加し、サンドボックスクライアントが PTY 対話をサポートする場合は `write_stdin` も追加します。 |
-| `Filesystem` | エージェントがファイルを編集したりローカル画像を検査したりする必要がある場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 |
-| `Skills` | サンドボックス内でスキル検出と具体化を行いたい場合。 | `.agents` や `.agents/skills` を手動でマウントするよりもこちらを推奨します。`Skills` がスキルをインデックス化し、サンドボックス内に具体化します。 |
-| `Memory` | 後続の実行がメモリ成果物を読み取る、または生成するべき場合。 | `Shell` が必要です。ライブ更新には `Filesystem` も必要です。 |
-| `Compaction` | 長時間実行フローでコンパクション項目後のコンテキスト削減が必要な場合。 | モデルサンプリングと入力処理を調整します。 |
+| `Shell` | エージェントがシェルアクセスを必要とする場合。 | `exec_command` を追加し、サンドボックスクライアントが PTY インタラクションをサポートする場合は `write_stdin` も追加します。 |
+| `Filesystem` | エージェントがファイルを編集する、またはローカル画像を検査する必要がある場合。 | `apply_patch` と `view_image` を追加します。パッチパスはワークスペースルート相対です。 |
+| `Skills` | サンドボックス内でスキル検出とマテリアライズを行いたい場合。 | `.agents` または `.agents/skills` を手動でマウントするよりもこちらを優先してください。`Skills` はスキルのインデックス化とサンドボックスへのマテリアライズを行います。 |
+| `Memory` | 後続の実行でメモリ成果物を読み取る、または生成する必要がある場合。 | `Shell` が必要です。ライブ更新には `Filesystem` も必要です。 |
+| `Compaction` | 長時間実行されるフローで、コンパクション項目の後にコンテキストのトリミングが必要な場合。 | モデルサンプリングと入力処理を調整します。 |
 
 </div>
 
-デフォルトでは、`SandboxAgent.capabilities` は `Capabilities.default()` を使い、これには `Filesystem()`、`Shell()`、`Compaction()` が含まれます。`capabilities=[...]` を渡すと、そのリストがデフォルトを置き換えるため、引き続き必要なデフォルト機能を含めてください。
+デフォルトでは、`SandboxAgent.capabilities` は `Capabilities.default()` を使用します。これには `Filesystem()`、`Shell()`、`Compaction()` が含まれます。`capabilities=[...]` を渡すと、そのリストがデフォルトを置き換えるため、引き続き必要なデフォルト機能を含めてください。
 
-スキルについては、どのように具体化したいかに基づいてソースを選んでください。
+スキルについては、どのようにマテリアライズしたいかに基づいてソースを選択してください。
 
-- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、モデルがまずインデックスを検出し、必要なものだけを読み込めるため、大きめのローカルスキルディレクトリに適したデフォルトです。
-- `LocalDirLazySkillSource(source=LocalDir(src=...))` は、SDK プロセスが実行されているファイルシステムから読み取ります。サンドボックスイメージやワークスペース内にしか存在しないパスではなく、元のホスト側スキルディレクトリを渡してください。
+- `Skills(lazy_from=LocalDirLazySkillSource(...))` は、大きめのローカルスキルディレクトリに適したデフォルトです。モデルがまずインデックスを発見し、必要なものだけを読み込めるためです。
+- `LocalDirLazySkillSource(source=LocalDir(src=...))` は、SDK プロセスが実行されているファイルシステムから読み取ります。サンドボックスイメージまたはワークスペース内にのみ存在するパスではなく、元のホスト側スキルディレクトリを渡してください。
 - `Skills(from_=LocalDir(src=...))` は、事前にステージングしたい小さなローカルバンドルに適しています。
 - `Skills(from_=GitRepo(repo=..., ref=...))` は、スキル自体をリポジトリから取得すべき場合に適しています。
 
-`LocalDir.src` は SDK ホスト上のソースパスです。`skills_path` は、`load_skill` が呼び出されたときにスキルがステージングされるサンドボックスワークスペース内の相対宛先パスです。
+`LocalDir.src` は SDK ホスト上のソースパスです。`skills_path` は、`load_skill` が呼び出されたときにスキルがステージングされる、サンドボックスワークスペース内の相対宛先パスです。
 
-スキルがすでに `.agents/skills/<name>/SKILL.md` のような場所にディスク上で存在する場合、そのソースルートを `LocalDir(...)` に指定し、それでも `Skills(...)` を使って公開してください。別のサンドボックス内レイアウトに依存する既存のワークスペース契約がない限り、デフォルトの `skills_path=".agents"` を維持してください。
+スキルが既に `.agents/skills/<name>/SKILL.md` のような場所にディスク上で存在する場合は、そのソースルートを `LocalDir(...)` に指定し、それでも `Skills(...)` を使用して公開してください。別のサンドボックス内レイアウトに依存する既存のワークスペース契約がない限り、デフォルトの `skills_path=".agents"` を維持してください。
 
-適合する場合は組み込み機能を優先してください。組み込みでカバーされないサンドボックス固有のツールや instruction インターフェイスが必要な場合にのみ、カスタム機能を書いてください。
+適合する場合は、組み込み機能を優先してください。組み込みでカバーされないサンドボックス固有のツールや指示面が必要な場合にのみ、カスタム機能を作成してください。
 
 ## 概念
 
-### Manifest
+### マニフェスト
 
-[`Manifest`][agents.sandbox.manifest.Manifest] は、新しいサンドボックスセッションのワークスペースを記述します。ワークスペースの `root` を設定し、ファイルやディレクトリを宣言し、ローカルファイルをコピーし、Git リポジトリをクローンし、リモートストレージマウントを接続し、環境変数を設定し、ユーザーやグループを定義し、ワークスペース外の特定の絶対パスへのアクセスを付与できます。
+[`Manifest`][agents.sandbox.manifest.Manifest] は、新規サンドボックスセッションのワークスペースを記述します。ワークスペースの `root` を設定し、ファイルとディレクトリを宣言し、ローカルファイルをコピーし、Git リポジトリをクローンし、リモートストレージマウントを接続し、環境変数を設定し、ユーザーやグループを定義し、ワークスペース外の特定の絶対パスへのアクセスを許可できます。
 
-Manifest エントリのパスはワークスペース相対です。絶対パスにしたり、`..` でワークスペースから抜けたりすることはできません。これにより、ワークスペース契約をローカル、Docker、ホスト型クライアント間で移植可能に保てます。
+マニフェストエントリのパスはワークスペース相対です。絶対パスにすることや、`..` でワークスペース外へ抜けることはできません。これにより、ワークスペース契約はローカル、Docker、ホスト型クライアント間で移植可能になります。
 
-作業開始前にエージェントが必要とする素材には manifest エントリを使います。
+作業開始前にエージェントが必要とする資料には、マニフェストエントリを使用します。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| Manifest エントリ | 用途 |
+| マニフェストエントリ | 用途 |
 | --- | --- |
 | `File`, `Dir` | 小さな合成入力、補助ファイル、または出力ディレクトリ。 |
-| `LocalFile`, `LocalDir` | サンドボックス内に具体化すべきホストファイルまたはディレクトリ。 |
+| `LocalFile`, `LocalDir` | サンドボックスにマテリアライズすべきホストファイルまたはディレクトリ。 |
 | `GitRepo` | ワークスペースに取得すべきリポジトリ。 |
-| `S3Mount`、`GCSMount`、`R2Mount`、`AzureBlobMount`、`BoxMount`、`S3FilesMount` などのマウント | サンドボックス内に表示すべき外部ストレージ。 |
+| `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` などのマウント | サンドボックス内に表示すべき外部ストレージ。 |
 
 </div>
 
-マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージを接続する方法を記述します。マウントオプションとプロバイダー対応については [サンドボックスクライアント](clients.md#mounts-and-remote-storage) を参照してください。
+`Dir` は、合成子要素から、または出力場所として、サンドボックスワークスペース内にディレクトリを作成します。ホストファイルシステムから読み取るわけではありません。既存のホストディレクトリをサンドボックスワークスペースにコピーすべき場合は、`LocalDir` を使用してください。
 
-優れた manifest 設計では通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` などのワークスペースファイルに置き、instructions 内で `repo/task.md` や `output/report.md` などの相対ワークスペースパスを使います。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなく、サンドボックスワークスペースルートからの相対であることに注意してください。
+`LocalFile.src` と `LocalDir.src` は、デフォルトでは SDK プロセスの作業ディレクトリを基準に解決されます。ソースは、`extra_path_grants` でカバーされていない限り、そのベースディレクトリの下に留まる必要があります。これにより、ローカルソースのマテリアライズは、サンドボックスマニフェストの他の部分と同じホストパスの信頼境界内に保たれます。
 
-`extra_path_grants` は、エージェントがワークスペース外の具体的な絶対パスを必要とする場合にのみ使ってください。たとえば、一時的なツール出力用の `/tmp` や、読み取り専用ランタイム用の `/opt/toolchain` です。grant は、バックエンドがファイルシステムポリシーを適用できる場合、SDK ファイル API とシェル実行の両方に適用されます。
+マウントエントリは公開するストレージを記述し、マウント戦略はサンドボックスバックエンドがそのストレージをどのように接続するかを記述します。マウントオプションとプロバイダーサポートについては、[サンドボックスクライアント](clients.md#mounts-and-remote-storage) を参照してください。
+
+適切なマニフェスト設計では通常、ワークスペース契約を狭く保ち、長いタスク手順を `repo/task.md` などのワークスペースファイルに置き、`repo/task.md` や `output/report.md` などの相対ワークスペースパスを指示で使用します。エージェントが `Filesystem` 機能の `apply_patch` ツールでファイルを編集する場合、パッチパスはシェルの `workdir` ではなくサンドボックスワークスペースルートからの相対であることを忘れないでください。
+
+エージェントがワークスペース外の具体的な絶対パスを必要とする場合、または SDK プロセスの作業ディレクトリ外にある信頼済みローカルソースをマニフェストがコピーする必要がある場合にのみ、`extra_path_grants` を使用してください。例として、一時的なツール出力用の `/tmp`、読み取り専用ランタイム用の `/opt/toolchain`、サンドボックスにマテリアライズすべき生成済みスキルディレクトリなどがあります。付与は、ローカルソースのマテリアライズ、SDK ファイル API、バックエンドがファイルシステムポリシーを適用できる場合のシェル実行に適用されます。
 
 ```python
 from agents.sandbox import Manifest, SandboxPathGrant
@@ -257,13 +261,15 @@ manifest = Manifest(
 )
 ```
 
-スナップショットと `persist_workspace()` は、引き続きワークスペースルートのみを含みます。追加で許可されたパスは実行時アクセスであり、永続的なワークスペース状態ではありません。
+`extra_path_grants` を含むマニフェストは、信頼済み設定として扱ってください。アプリケーションがそれらのホストパスを既に承認していない限り、モデル出力やその他の信頼できないペイロードから付与を読み込まないでください。
+
+スナップショットと `persist_workspace()` は、引き続きワークスペースルートのみを含みます。追加で許可されたパスはランタイムアクセスであり、永続的なワークスペース状態ではありません。
 
 ### 権限
 
-`Permissions` は manifest エントリのファイルシステム権限を制御します。これはサンドボックスが具体化するファイルに関するものであり、モデル権限、承認ポリシー、API 認証情報に関するものではありません。
+`Permissions` は、マニフェストエントリのファイルシステム権限を制御します。これはサンドボックスがマテリアライズするファイルに関するものであり、モデル権限、承認ポリシー、API 認証情報に関するものではありません。
 
-デフォルトでは、manifest エントリは所有者が読み取り、書き込み、実行可能で、グループとその他は読み取り、実行可能です。ステージングされたファイルを非公開、読み取り専用、または実行可能にする必要がある場合は、これを上書きします。
+デフォルトでは、マニフェストエントリは所有者が読み取り/書き込み/実行可能で、グループとその他のユーザーが読み取り/実行可能です。ステージングされたファイルをプライベート、読み取り専用、または実行可能にすべき場合は、これをオーバーライドしてください。
 
 ```python
 from agents.sandbox import FileMode, Permissions
@@ -279,9 +285,9 @@ private_notes = File(
 )
 ```
 
-`Permissions` は、所有者、グループ、その他の各ビットと、そのエントリがディレクトリかどうかを別々に保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列から解析することも、`Permissions.from_mode(...)` で OS モードから派生させることもできます。
+`Permissions` は、所有者、グループ、その他のビットを個別に保持し、さらにエントリがディレクトリかどうかも保持します。直接構築することも、`Permissions.from_str(...)` でモード文字列からパースすることも、`Permissions.from_mode(...)` で OS モードから導出することもできます。
 
-ユーザーは、作業を実行できるサンドボックス ID です。その ID をサンドボックス内に存在させたい場合は manifest に `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行したい場合は `SandboxAgent.run_as` を設定します。`run_as` が manifest にまだ存在しないユーザーを指している場合、Runner が実効 manifest にそのユーザーを追加します。
+ユーザーは、作業を実行できるサンドボックス ID です。その ID をサンドボックスに存在させたい場合は、マニフェストに `User` を追加し、シェルコマンド、ファイル読み取り、パッチなどのモデル向けサンドボックスツールをそのユーザーとして実行すべき場合は `SandboxAgent.run_as` を設定してください。`run_as` がマニフェスト内にまだ存在しないユーザーを指している場合、Runner は有効なマニフェストにそのユーザーを追加します。
 
 ```python
 from agents import Runner
@@ -333,13 +339,13 @@ result = await Runner.run(
 )
 ```
 
-ファイルレベルの共有ルールも必要な場合は、ユーザーと manifest グループ、エントリの `group` メタデータを組み合わせてください。`run_as` ユーザーは誰がサンドボックスネイティブアクションを実行するかを制御し、`Permissions` はサンドボックスがワークスペースを具体化した後、そのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。
+ファイルレベルの共有ルールも必要な場合は、ユーザーとマニフェストグループ、エントリの `group` メタデータを組み合わせてください。`run_as` ユーザーは誰がサンドボックスネイティブなアクションを実行するかを制御し、`Permissions` はサンドボックスがワークスペースをマテリアライズした後に、そのユーザーがどのファイルを読み取り、書き込み、実行できるかを制御します。
 
-### SnapshotSpec
+### スナップショット仕様
 
-`SnapshotSpec` は、保存されたワークスペース内容をどこから復元し、どこへ永続化するかを新しいサンドボックスセッションに伝えます。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズされた接続状態です。
+`SnapshotSpec` は、新規サンドボックスセッションで保存済みワークスペース内容をどこから復元し、どこへ永続化して戻すかを指定します。これはサンドボックスワークスペースのスナップショットポリシーであり、`session_state` は特定のサンドボックスバックエンドを再開するためのシリアライズ済み接続状態です。
 
-ローカルの永続スナップショットには `LocalSnapshotSpec` を使い、アプリがリモートスナップショットクライアントを提供する場合は `RemoteSnapshotSpec` を使います。ローカルスナップショットのセットアップが利用できない場合はフォールバックとして no-op スナップショットが使われ、高度な呼び出し元はワークスペーススナップショット永続化を望まない場合に明示的に使うこともできます。
+ローカルの永続スナップショットには `LocalSnapshotSpec` を使用し、アプリがリモートスナップショットクライアントを提供する場合は `RemoteSnapshotSpec` を使用します。ローカルスナップショットのセットアップが利用できない場合はフォールバックとして no-op スナップショットが使用され、高度な呼び出し元はワークスペーススナップショットの永続化を望まない場合に明示的に使用できます。
 
 ```python
 from pathlib import Path
@@ -356,13 +362,13 @@ run_config = RunConfig(
 )
 ```
 
-Runner が新しいサンドボックスセッションを作成すると、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時、スナップショットが復元可能であれば、実行が継続する前にサンドボックスが保存済みワークスペース内容を復元します。クリーンアップ時、Runner 所有のサンドボックスセッションはワークスペースをアーカイブし、スナップショットを通じて永続化します。
+Runner が新規サンドボックスセッションを作成すると、サンドボックスクライアントはそのセッション用のスナップショットインスタンスを構築します。開始時に、スナップショットが復元可能であれば、実行が継続する前にサンドボックスは保存済みワークスペース内容を復元します。クリーンアップ時には、Runner 所有のサンドボックスセッションがワークスペースをアーカイブし、スナップショットを通じて永続化して戻します。
 
-`snapshot` を省略した場合、ランタイムは可能であればデフォルトのローカルスナップショット場所を使おうとします。それを設定できない場合は、no-op スナップショットにフォールバックします。マウントされたパスや一時的なパスは、永続的なワークスペース内容としてスナップショットにコピーされません。
+`snapshot` を省略すると、ランタイムは可能な場合にデフォルトのローカルスナップショット場所を使用しようとします。それをセットアップできない場合は、no-op スナップショットにフォールバックします。マウントされたパスと一時パスは、永続的なワークスペース内容としてスナップショットにコピーされません。
 
-### サンドボックスライフサイクル
+### サンドボックスのライフサイクル
 
-ライフサイクルモードは **SDK 所有** と **開発者所有** の 2 つです。
+ライフサイクルモードは 2 つあります。**SDK 所有** と **開発者所有** です。
 
 <div class="sandbox-lifecycle-diagram" markdown="1">
 
@@ -390,7 +396,7 @@ sequenceDiagram
 
 </div>
 
-サンドボックスが 1 回の実行の間だけ存在すればよい場合は、SDK 所有ライフサイクルを使います。`client`、任意の `manifest`、任意の `snapshot`、クライアントの `options` を渡します。Runner はサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショットに裏付けられたワークスペース状態を永続化し、サンドボックスを停止し、クライアントに Runner 所有リソースをクリーンアップさせます。
+サンドボックスが 1 回の実行の間だけ存続すればよい場合は、SDK 所有のライフサイクルを使用します。`client`、任意の `manifest`、任意の `snapshot`、クライアント `options` を渡します。Runner はサンドボックスを作成または再開し、開始し、エージェントを実行し、スナップショット backed のワークスペース状態を永続化し、サンドボックスをシャットダウンし、クライアントに Runner 所有リソースをクリーンアップさせます。
 
 ```python
 result = await Runner.run(
@@ -402,7 +408,7 @@ result = await Runner.run(
 )
 ```
 
-サンドボックスを事前に作成したい場合、1 つの稼働中サンドボックスを複数実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを正確に決めたい場合は、開発者所有ライフサイクルを使います。`session=...` を渡すと、Runner はその稼働中サンドボックスを使用しますが、あなたの代わりに閉じることはありません。
+サンドボックスを先に作成したい場合、1 つのライブサンドボックスを複数の実行で再利用したい場合、実行後にファイルを検査したい場合、自分で作成したサンドボックス上でストリーミングしたい場合、またはクリーンアップのタイミングを厳密に決めたい場合は、開発者所有のライフサイクルを使用します。`session=...` を渡すと、Runner はそのライブサンドボックスを使用しますが、代わりに閉じることはありません。
 
 ```python
 sandbox = await client.create(manifest=agent.default_manifest)
@@ -413,7 +419,7 @@ async with sandbox:
     await Runner.run(agent, "Write the final report.", run_config=run_config)
 ```
 
-通常の形はコンテキストマネージャーです。入場時にサンドボックスを開始し、終了時にセッションクリーンアップライフサイクルを実行します。アプリがコンテキストマネージャーを使えない場合は、ライフサイクルメソッドを直接呼び出してください。
+通常はコンテキストマネージャーの形を使用します。エントリ時にサンドボックスを開始し、終了時にセッションのクリーンアップライフサイクルを実行します。アプリでコンテキストマネージャーを使用できない場合は、ライフサイクルメソッドを直接呼び出してください。
 
 ```python
 sandbox = await client.create(
@@ -434,62 +440,64 @@ finally:
     await sandbox.aclose()
 ```
 
-`stop()` はスナップショットに裏付けられたワークスペース内容を永続化するだけで、サンドボックスを破棄しません。`aclose()` は完全なセッションクリーンアップ経路です。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。
+`stop()` はスナップショット backed のワークスペース内容だけを永続化し、サンドボックスを破棄しません。`aclose()` は完全なセッションクリーンアップパスです。停止前フックを実行し、`stop()` を呼び出し、サンドボックスリソースをシャットダウンし、セッションスコープの依存関係を閉じます。
 
-## `SandboxRunConfig` オプション
+## `SandboxRunConfig` のオプション
 
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションがどこから来るか、および新しいセッションをどのように初期化するかを決める実行ごとのオプションを保持します。
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig] は、サンドボックスセッションがどこから来るか、および新規セッションをどのように初期化すべきかを決定する、実行ごとのオプションを保持します。
 
-### サンドボックスソース
+### サンドボックスの取得元
 
-これらのオプションは、Runner がサンドボックスセッションを再利用、再開、または作成するかを決定します。
+これらのオプションは、Runner がサンドボックスセッションを再利用、再開、または作成すべきかを決定します。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| オプション | 使用する場面 | 注記 |
+| オプション | 使用する場面 | 注意 |
 | --- | --- | --- |
-| `client` | Runner にサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | 稼働中のサンドボックス `session` を提供しない限り必須です。 |
-| `session` | すでに自分で稼働中のサンドボックスセッションを作成している場合。 | 呼び出し元がライフサイクルを所有し、Runner はその稼働中サンドボックスセッションを再利用します。 |
-| `session_state` | シリアライズされたサンドボックスセッション状態はあるが、稼働中のサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。Runner はその明示的な状態から所有セッションとして再開します。 |
+| `client` | Runner にサンドボックスセッションの作成、再開、クリーンアップを任せたい場合。 | ライブサンドボックス `session` を提供しない限り必須です。 |
+| `session` | 既にライブサンドボックスセッションを自分で作成している場合。 | 呼び出し元がライフサイクルを所有します。Runner はそのライブサンドボックスセッションを再利用します。 |
+| `session_state` | シリアライズ済みのサンドボックスセッション状態はあるが、ライブサンドボックスセッションオブジェクトはない場合。 | `client` が必要です。Runner はその明示的な状態から所有セッションとして再開します。 |
 
 </div>
 
 実際には、Runner は次の順序でサンドボックスセッションを解決します。
 
-1. `run_config.sandbox.session` を注入した場合、その稼働中のサンドボックスセッションが直接再利用されます。
-2. それ以外で、実行が `RunState` から再開している場合、保存されたサンドボックスセッション状態が再開されます。
-3. それ以外で、`run_config.sandbox.session_state` を渡した場合、Runner はその明示的にシリアライズされたサンドボックスセッション状態から再開します。
-4. それ以外の場合、Runner は新しいサンドボックスセッションを作成します。その新規セッションでは、提供されていれば `run_config.sandbox.manifest` を使い、なければ `agent.default_manifest` を使います。
+1. `run_config.sandbox.session` を注入した場合、そのライブサンドボックスセッションが直接再利用されます。
+2. それ以外で、実行が `RunState` から再開される場合、保存されているサンドボックスセッション状態が再開されます。
+3. それ以外で、`run_config.sandbox.session_state` を渡した場合、Runner はその明示的なシリアライズ済みサンドボックスセッション状態から再開します。
+4. それ以外の場合、Runner は新規サンドボックスセッションを作成します。その新規セッションでは、提供されている場合は `run_config.sandbox.manifest` を使用し、そうでない場合は `agent.default_manifest` を使用します。
 
-### 新規セッション入力
+### 新規セッションの入力
 
-これらのオプションは、Runner が新しいサンドボックスセッションを作成する場合にのみ関係します。
+これらのオプションは、Runner が新規サンドボックスセッションを作成する場合にのみ意味を持ちます。
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| オプション | 使用する場面 | 注記 |
+| オプション | 使用する場面 | 注意 |
 | --- | --- | --- |
-| `manifest` | 一回限りの新規セッションワークスペース上書きをしたい場合。 | 省略時は `agent.default_manifest` にフォールバックします。 |
-| `snapshot` | 新しいサンドボックスセッションをスナップショットから初期化すべき場合。 | 再開に似たフローやリモートスナップショットクライアントに有用です。 |
-| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、Modal アプリ名、E2B テンプレート、タイムアウト、類似のクライアント固有設定で一般的です。 |
+| `manifest` | 1 回限りの新規セッションワークスペースオーバーライドが必要な場合。 | 省略時は `agent.default_manifest` にフォールバックします。 |
+| `snapshot` | 新規サンドボックスセッションをスナップショットから初期化すべき場合。 | 再開に似たフローやリモートスナップショットクライアントに有用です。 |
+| `options` | サンドボックスクライアントが作成時オプションを必要とする場合。 | Docker イメージ、Modal アプリ名、E2B テンプレート、タイムアウト、および同様のクライアント固有設定で一般的です。 |
 
 </div>
 
-### 具体化制御
+### マテリアライズ制御
 
-`concurrency_limits` は、サンドボックス具体化作業をどれだけ並列実行できるかを制御します。大きな manifest やローカルディレクトリのコピーでより厳密なリソース制御が必要な場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使います。特定の制限を無効にするには、いずれかの値を `None` に設定します。
+`concurrency_limits` は、サンドボックスのマテリアライズ作業をどの程度並列に実行できるかを制御します。大きなマニフェストやローカルディレクトリコピーでより厳密なリソース制御が必要な場合は、`SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)` を使用してください。いずれかの値を `None` に設定すると、その特定の制限を無効にできます。
 
-覚えておくべき影響がいくつかあります。
+`archive_limits` は、アーカイブ抽出に対する SDK 側のリソースチェックを制御します。SDK のデフォルトしきい値を有効にするには `archive_limits=SandboxArchiveLimits()` を設定します。アーカイブにより厳密なリソース制御が必要な場合は、`SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` などの明示的な値を渡してください。SDK アーカイブリソース制限なしのデフォルト動作を維持するには `archive_limits=None` のままにし、個別のフィールドだけを無効にするにはそのフィールドを `None` に設定します。
 
-- 新規セッション: `manifest=` と `snapshot=` は、Runner が新しいサンドボックスセッションを作成する場合にのみ適用されます。
-- 再開とスナップショット: `session_state=` は以前にシリアライズされたサンドボックス状態へ再接続します。一方、`snapshot=` は保存済みワークスペース内容から新しいサンドボックスセッションを初期化します。
-- クライアント固有オプション: `options=` はサンドボックスクライアントに依存します。Docker や多くのホスト型クライアントでは必要です。
-- 注入された稼働中セッション: 実行中のサンドボックス `session` を渡した場合、機能による manifest 更新は、互換性のある非マウントエントリを追加できます。`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` の変更、既存エントリの削除、エントリタイプの置換、マウントエントリの追加または変更はできません。
-- Runner API: `SandboxAgent` の実行は、引き続き通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使います。
+留意すべき点がいくつかあります。
+
+- 新規セッション: `manifest=` と `snapshot=` は、Runner が新規サンドボックスセッションを作成する場合にのみ適用されます。
+- 再開とスナップショット: `session_state=` は以前にシリアライズされたサンドボックス状態に再接続します。一方、`snapshot=` は保存済みワークスペース内容から新規サンドボックスセッションを初期化します。
+- クライアント固有オプション: `options=` はサンドボックスクライアントに依存します。Docker や多くのホスト型クライアントでは必須です。
+- 注入されたライブセッション: 実行中のサンドボックス `session` を渡す場合、機能駆動のマニフェスト更新は互換性のある非マウントエントリを追加できます。`manifest.root`、`manifest.environment`、`manifest.users`、`manifest.groups` を変更すること、既存エントリを削除すること、エントリタイプを置き換えること、マウントエントリを追加または変更することはできません。
+- Runner API: `SandboxAgent` の実行は引き続き、通常の `Runner.run()`、`Runner.run_sync()`、`Runner.run_streamed()` API を使用します。
 
 ## 完全な例: コーディングタスク
 
-このコーディング形式の例は、出発点として適したデフォルトです。
+このコーディングスタイルの例は、デフォルトの出発点として適しています。
 
 ```python
 import asyncio
@@ -568,19 +576,19 @@ if __name__ == "__main__":
     )
 ```
 
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、Unix ローカル実行間で決定的に検証できるように、小さなシェルベースのリポジトリを使っています。実際のタスクリポジトリはもちろん、Python、JavaScript、その他何でも構いません。
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例は、Unix ローカル実行間で決定論的に検証できるように、小さなシェルベースのリポジトリを使用しています。実際のタスクリポジトリは、もちろん Python、JavaScript、またはその他何でもかまいません。
 
 ## 一般的なパターン
 
-上記の完全な例から始めてください。多くの場合、同じ `SandboxAgent` をそのまま保ち、サンドボックスクライアント、サンドボックスセッションソース、またはワークスペースソースだけを変更できます。
+上記の完全な例から始めてください。多くの場合、同じ `SandboxAgent` をそのまま維持し、サンドボックスクライアント、サンドボックスセッションの取得元、またはワークスペースの取得元だけを変更できます。
 
 ### サンドボックスクライアントの切り替え
 
-エージェント定義は同じままにし、実行設定だけを変更します。コンテナ分離やイメージの同等性が必要な場合は Docker を使い、プロバイダー管理の実行が必要な場合はホスト型プロバイダーを使います。例とプロバイダーオプションについては [サンドボックスクライアント](clients.md) を参照してください。
+エージェント定義は同じままにし、実行設定だけを変更します。コンテナ隔離やイメージの一致性が必要な場合は Docker を使用し、プロバイダー管理の実行が必要な場合はホスト型プロバイダーを使用します。例とプロバイダーオプションについては、[サンドボックスクライアント](clients.md) を参照してください。
 
-### ワークスペースの上書き
+### ワークスペースのオーバーライド
 
-エージェント定義は同じままにし、新規セッション manifest だけを差し替えます。
+エージェント定義は同じままにし、新規セッションのマニフェストだけを差し替えます。
 
 ```python
 from agents.run import RunConfig
@@ -600,11 +608,11 @@ run_config = RunConfig(
 )
 ```
 
-同じエージェントの役割を、異なるリポジトリ、パケット、タスクバンドルに対して、エージェントを再構築せずに実行したい場合に使います。上記の検証済みコーディング例は、一回限りの上書きではなく `default_manifest` を使って同じパターンを示しています。
+同じエージェントの役割を、エージェントを再構築せずに異なるリポジトリ、パケット、またはタスクバンドルに対して実行すべき場合に使用します。上記の検証済みコーディング例では、1 回限りのオーバーライドではなく `default_manifest` で同じパターンを示しています。
 
 ### サンドボックスセッションの注入
 
-明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、稼働中のサンドボックスセッションを注入します。
+明示的なライフサイクル制御、実行後の検査、または出力コピーが必要な場合は、ライブサンドボックスセッションを注入します。
 
 ```python
 from agents import Runner
@@ -625,11 +633,11 @@ async with sandbox:
     )
 ```
 
-実行後にワークスペースを検査したい場合や、すでに開始済みのサンドボックスセッション上でストリーミングしたい場合に使います。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
+実行後にワークスペースを検査したい場合や、既に開始済みのサンドボックスセッション上でストリーミングしたい場合に使用します。[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) と [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py) を参照してください。
 
 ### セッション状態からの再開
 
-`RunState` の外でサンドボックス状態をすでにシリアライズしている場合は、Runner にその状態から再接続させます。
+`RunState` の外部で既にサンドボックス状態をシリアライズしている場合は、Runner にその状態から再接続させます。
 
 ```python
 from agents.run import RunConfig
@@ -646,11 +654,11 @@ run_config = RunConfig(
 )
 ```
 
-サンドボックス状態が独自のストレージやジョブシステムにあり、`Runner` にそこから直接再開させたい場合に使います。シリアライズ / デシリアライズフローについては [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。
+サンドボックス状態が独自のストレージまたはジョブシステムに存在し、`Runner` にそこから直接再開させたい場合に使用します。シリアライズ/デシリアライズのフローについては、[examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py) を参照してください。
 
 ### スナップショットからの開始
 
-保存済みファイルと成果物から新しいサンドボックスを初期化します。
+保存済みファイルと成果物から新規サンドボックスを初期化します。
 
 ```python
 from pathlib import Path
@@ -667,11 +675,11 @@ run_config = RunConfig(
 )
 ```
 
-新しい実行を `agent.default_manifest` だけでなく、保存済みワークスペース内容から開始すべき場合に使います。ローカルスナップショットフローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を、リモートスナップショットクライアントについては [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。
+新規実行を `agent.default_manifest` だけではなく、保存済みワークスペース内容から開始すべき場合に使用します。ローカルスナップショットフローについては [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を、リモートスナップショットクライアントについては [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py) を参照してください。
 
 ### Git からのスキル読み込み
 
-ローカルスキルソースをリポジトリベースのものに差し替えます。
+ローカルスキルソースを、リポジトリ backed のものに差し替えます。
 
 ```python
 from agents.sandbox.capabilities import Capabilities, Skills
@@ -682,11 +690,11 @@ capabilities = Capabilities.default() + [
 ]
 ```
 
-スキルバンドルに独自のリリースサイクルがある場合や、サンドボックス間で共有すべき場合に使います。[examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) を参照してください。
+スキルバンドルに独自のリリースサイクルがある場合や、サンドボックス間で共有すべき場合に使用します。[examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py) を参照してください。
 
 ### ツールとしての公開
 
-ツールエージェントは、独自のサンドボックス境界を持つことも、親実行の稼働中サンドボックスを再利用することもできます。再利用は、高速な読み取り専用探索エージェントに有用です。別のサンドボックスを作成、ハイドレート、スナップショットするコストを払わずに、親が使っている正確なワークスペースを検査できます。
+ツールエージェントは、独自のサンドボックス境界を持つことも、親実行のライブサンドボックスを再利用することもできます。再利用は、高速な読み取り専用の探索エージェントに有用です。別のサンドボックスの作成、ハイドレーション、スナップショット作成にコストをかけずに、親が使用している正確なワークスペースを検査できます。
 
 ```python
 from agents import Runner
@@ -768,9 +776,9 @@ async with sandbox:
     )
 ```
 
-ここでは親エージェントが `coordinator` として実行され、explorer ツールエージェントが同じ稼働中サンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーが読み取り可能なため、explorer はそれらをすばやく検査できますが、書き込みビットは持ちません。`work/` ディレクトリは coordinator のユーザー / グループだけが利用できるため、親は最終成果物を書き込める一方で、explorer は読み取り専用のままです。
+ここでは、親エージェントは `coordinator` として実行され、探索ツールエージェントは同じライブサンドボックスセッション内で `explorer` として実行されます。`pricing_packet/` エントリは `other` ユーザーが読み取り可能であるため、explorer はすばやく検査できますが、書き込みビットは持ちません。`work/` ディレクトリは coordinator のユーザー/グループだけが利用できるため、親は最終成果物を書き込めますが、explorer は読み取り専用のままです。
 
-ツールエージェントに本当の分離が必要な場合は、独自のサンドボックス `RunConfig` を与えます。
+ツールエージェントに実際の隔離が必要な場合は、代わりに独自のサンドボックス `RunConfig` を与えます。
 
 ```python
 from docker import from_env as docker_from_env
@@ -791,11 +799,11 @@ rollout_agent.as_tool(
 )
 ```
 
-ツールエージェントが自由に変更したり、信頼できないコマンドを実行したり、異なるバックエンド / イメージを使うべき場合は、別のサンドボックスを使います。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
+ツールエージェントが自由に変更すべき場合、信頼できないコマンドを実行すべき場合、または異なるバックエンド/イメージを使用すべき場合は、別のサンドボックスを使用してください。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
 
-### ローカルツールと MCP との組み合わせ
+### ローカルツールおよび MCP との組み合わせ
 
-同じエージェントで通常のツールを使いながら、サンドボックスワークスペースを維持します。
+同じエージェントで通常のツールを使用しながら、サンドボックスワークスペースも維持します。
 
 ```python
 from agents.sandbox import SandboxAgent
@@ -810,46 +818,46 @@ agent = SandboxAgent(
 )
 ```
 
-ワークスペース検査がエージェントの仕事の一部にすぎない場合に使います。[examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py) を参照してください。
+ワークスペース検査がエージェントの仕事の一部にすぎない場合に使用します。[examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py) を参照してください。
 
 ## メモリ
 
-将来のサンドボックスエージェント実行が過去の実行から学ぶべき場合は、`Memory` 機能を使います。メモリは SDK の会話用 `Session` メモリとは別です。教訓をサンドボックスワークスペース内のファイルに抽出し、後続の実行がそれらのファイルを読めるようにします。
+将来のサンドボックスエージェント実行が以前の実行から学習すべき場合は、`Memory` 機能を使用します。メモリは SDK の会話型 `Session` メモリとは別です。学びをサンドボックスワークスペース内のファイルに蒸留し、後続の実行がそれらのファイルを読み取れるようにします。
 
-セットアップ、読み取り / 生成動作、マルチターン会話、レイアウト分離については [エージェントメモリ](memory.md) を参照してください。
+セットアップ、読み取り/生成の挙動、マルチターン会話、レイアウト隔離については、[エージェントメモリ](memory.md) を参照してください。
 
 ## 構成パターン
 
 単一エージェントのパターンが明確になったら、次の設計上の問いは、より大きなシステムのどこにサンドボックス境界を置くかです。
 
-サンドボックスエージェントは、SDK の他の部分とも引き続き構成できます。
+サンドボックスエージェントは、引き続き SDK の他の部分と組み合わせられます。
 
-- [ハンドオフ](../handoffs.md): ドキュメント量の多い作業を、非サンドボックスの受付エージェントからサンドボックスレビュアーへハンドオフします。
-- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しで `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールに独自のサンドボックス境界を持たせます。
-- [MCP](../mcp.md) と通常の関数ツール: サンドボックス機能は `mcp_servers` や通常の Python ツールと共存できます。
-- [エージェントの実行](../running_agents.md): サンドボックス実行も通常の `Runner` API を使います。
+- [ハンドオフ](../handoffs.md): ドキュメントの多い作業を、非サンドボックスの受付エージェントからサンドボックスレビュアーにハンドオフします。
+- [Agents as tools](../tools.md#agents-as-tools): 複数のサンドボックスエージェントをツールとして公開します。通常は各 `Agent.as_tool(...)` 呼び出しに `run_config=RunConfig(sandbox=SandboxRunConfig(...))` を渡し、各ツールが独自のサンドボックス境界を持つようにします。
+- [MCP](../mcp.md) と通常の関数ツール: サンドボックス機能は、`mcp_servers` や通常の Python ツールと共存できます。
+- [エージェントの実行](../running_agents.md): サンドボックス実行も通常の `Runner` API を使用します。
 
 特に一般的なパターンは 2 つあります。
 
-- 非サンドボックスエージェントが、ワークフローのうちワークスペース分離を必要とする部分だけをサンドボックスエージェントへハンドオフする
-- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールが独自の分離ワークスペースを持つようにする
+- ワークフローのうちワークスペース隔離が必要な部分だけを、非サンドボックスエージェントからサンドボックスエージェントにハンドオフする
+- オーケストレーターが複数のサンドボックスエージェントをツールとして公開する。通常は各 `Agent.as_tool(...)` 呼び出しごとに別々のサンドボックス `RunConfig` を使い、各ツールが独自の隔離ワークスペースを持つようにする
 
 ### ターンとサンドボックス実行
 
-ハンドオフと agent-as-tool 呼び出しは、分けて説明すると理解しやすくなります。
+ハンドオフと agent-as-tool 呼び出しは分けて説明すると理解しやすくなります。
 
-ハンドオフでは、トップレベルの実行とトップレベルのターンループは引き続き 1 つです。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの受付エージェントがサンドボックスレビュアーへハンドオフした場合、同じ実行内の次のモデル呼び出しはサンドボックスエージェント向けに準備され、そのサンドボックスエージェントが次のターンを担当するエージェントになります。言い換えると、ハンドオフは同じ実行の次のターンを所有するエージェントを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
+ハンドオフでは、引き続き 1 つのトップレベル実行と 1 つのトップレベルターンループがあります。アクティブなエージェントは変わりますが、実行がネストされるわけではありません。非サンドボックスの受付エージェントがサンドボックスレビュアーにハンドオフすると、同じ実行内の次のモデル呼び出しはサンドボックスエージェント用に準備され、そのサンドボックスエージェントが次のターンを担当します。言い換えると、ハンドオフは同じ実行の次のターンをどのエージェントが所有するかを変更します。[examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py) を参照してください。
 
-`Agent.as_tool(...)` では関係が異なります。外側のオーケストレーターは 1 つの外側ターンを使ってツールを呼び出すことを決定し、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行には、独自のターンループ、`max_turns`、承認、通常は独自のサンドボックス `RunConfig` があります。1 つのネストされたターンで終了する場合もあれば、複数かかる場合もあります。外側のオーケストレーターの視点では、その作業全体は 1 つのツール呼び出しの背後にあるため、ネストされたターンは外側の実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
+`Agent.as_tool(...)` では、関係が異なります。外側のオーケストレーターは、ツールを呼び出すと決定するために外側の 1 ターンを使用し、そのツール呼び出しがサンドボックスエージェントのネストされた実行を開始します。ネストされた実行は、独自のターンループ、`max_turns`、承認、そして通常は独自のサンドボックス `RunConfig` を持ちます。1 つのネストされたターンで完了する場合もあれば、複数かかる場合もあります。外側のオーケストレーターの視点では、その作業全体が 1 つのツール呼び出しの背後にあるため、ネストされたターンは外側の実行のターンカウンターを増やしません。[examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py) を参照してください。
 
-承認動作も同じ分担に従います。
+承認の挙動も同じ分担に従います。
 
-- ハンドオフでは、サンドボックスエージェントがその実行内のアクティブなエージェントになっているため、承認は同じトップレベル実行にとどまります
-- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認は外側の実行に表示されますが、保存されたネスト実行状態から来ており、外側の実行が再開されるとネストされたサンドボックス実行を再開します
+- ハンドオフでは、サンドボックスエージェントがその実行内のアクティブエージェントになるため、承認は同じトップレベル実行に留まります
+- `Agent.as_tool(...)` では、サンドボックスツールエージェント内で発生した承認も外側の実行に表示されますが、それらは保存されたネスト実行状態から来ており、外側の実行が再開されるとネストされたサンドボックス実行を再開します
 
-## 参考資料
+## 関連情報
 
-- [クイックスタート](quickstart.md): サンドボックスエージェントを 1 つ実行します。
+- [クイックスタート](quickstart.md): 1 つのサンドボックスエージェントを実行します。
 - [サンドボックスクライアント](clients.md): ローカル、Docker、ホスト型、マウントのオプションを選択します。
-- [エージェントメモリ](memory.md): 以前のサンドボックス実行から得た教訓を保持し、再利用します。
-- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成パターン。
+- [エージェントメモリ](memory.md): 以前のサンドボックス実行からの学びを保持し、再利用します。
+- [examples/sandbox/](https://github.com/openai/openai-agents-python/tree/main/examples/sandbox): 実行可能なローカル、コーディング、メモリ、ハンドオフ、エージェント構成のパターン。

docs/ja/sandbox/memory.md

@@ -4,23 +4,23 @@ search:
 ---
 # エージェントメモリ
 
-メモリを使うと、今後の sandbox-agent の実行が過去の実行から学習できるようになります。これは、メッセージ履歴を保存する SDK の会話用 [`Session`](../sessions/index.md) メモリとは別のものです。メモリは、過去の実行から得られた学びを sandbox ワークスペース内のファイルに要約します。
+メモリにより、今後の sandbox エージェントの実行は過去の実行から学習できます。これは、メッセージ履歴を保存する SDK の会話用 [`Session`](../sessions/index.md) メモリとは別のものです。メモリは、過去の実行から得た学びを sandbox ワークスペース内のファイルに要約します。
 
 !!! warning "ベータ機能"
 
-    Sandbox エージェントはベータ版です。一般提供までに API の詳細、デフォルト設定、サポートされる機能は変更される可能性があり、今後さらに高度な機能も追加される予定です。
+    Sandbox エージェントはベータ版です。一般提供までに API の詳細、デフォルト値、サポートされる機能が変更される可能性があり、時間とともにさらに高度な機能が追加されることも想定してください。
 
-メモリは、将来の実行における次の 3 種類のコストを削減できます。
+メモリは、今後の実行における 3 種類のコストを削減できます。
 
-1. エージェントコスト: エージェントがワークフローの完了に長い時間を要した場合、次回の実行では探索が少なくて済むはずです。これにより、トークン使用量と完了までの時間を削減できます。
-2. ユーザーコスト: ユーザーがエージェントを修正したり、好みを示したりした場合、今後の実行ではそのフィードバックを記憶できます。これにより、人手による介入を減らせます。
-3. コンテキストコスト: エージェントが以前にタスクを完了していて、ユーザーがそのタスクを引き継いで進めたい場合、ユーザーは以前のスレッドを探したり、すべてのコンテキストを再入力したりする必要がありません。これにより、タスクの説明を短くできます。
+1. エージェントのコスト: エージェントがワークフローの完了に長い時間を要した場合、次回の実行では探索が少なくて済むはずです。これにより、トークン使用量と完了までの時間を削減できます。
+2. ユーザーのコスト: ユーザーがエージェントを修正したり好みを表明したりした場合、今後の実行でそのフィードバックを記憶できます。これにより、人による介入を削減できます。
+3. コンテキストのコスト: エージェントが以前にタスクを完了していて、ユーザーがそのタスクを発展させたい場合、ユーザーは以前のスレッドを探したり、すべてのコンテキストを再入力したりする必要がないはずです。これにより、タスク説明を短くできます。
 
-バグを修正し、メモリを生成し、スナップショットを再開し、そのメモリを後続の verifier 実行で使用する 2 回実行の完全な例については、[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を参照してください。別々のメモリレイアウトを使ったマルチターン・マルチエージェントの例については、[examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py) を参照してください。
+バグを修正し、メモリを生成し、スナップショットを再開し、そのメモリを後続の検証実行で使用する、2 回の実行からなる完全なコード例については、[examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py) を参照してください。独立したメモリレイアウトを持つマルチターン、マルチエージェントのコード例については、[examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py) を参照してください。
 
 ## メモリの有効化
 
-sandbox エージェントの capability として `Memory()` を追加します。
+sandbox エージェントに機能として `Memory()` を追加します。
 
 ```python
 from pathlib import Path
@@ -42,28 +42,28 @@ with tempfile.TemporaryDirectory(prefix="sandbox-memory-example-") as snapshot_d
     )
 ```
 
-読み取りが有効な場合、`Memory()` には `Shell()` が必要です。これにより、注入された要約だけでは不十分なときに、エージェントがメモリファイルを読み取り、検索できます。ライブメモリ更新が有効な場合（デフォルト）、`Filesystem()` も必要です。これにより、エージェントが古いメモリを見つけた場合や、ユーザーがメモリの更新を求めた場合に、`memories/MEMORY.md` を更新できます。
+読み取りが有効な場合、`Memory()` には `Shell()` が必要です。これにより、挿入されたサマリーだけでは不十分なときに、エージェントがメモリファイルを読み取り、検索できます。ライブメモリ更新が有効な場合（デフォルト）、`Filesystem()` も必要です。これにより、エージェントが古くなったメモリを発見した場合や、ユーザーがメモリの更新を依頼した場合に、`memories/MEMORY.md` を更新できます。
 
-デフォルトでは、メモリアーティファクトは sandbox ワークスペースの `memories/` 以下に保存されます。後続の実行でそれらを再利用するには、同じライブ sandbox セッションを維持するか、永続化されたセッション状態またはスナップショットから再開することで、設定された memories ディレクトリー全体を保持して再利用してください。新しい空の sandbox は空のメモリで開始します。
+デフォルトでは、メモリアーティファクトは sandbox ワークスペースの `memories/` 配下に保存されます。後の実行で再利用するには、同じライブ sandbox セッションを維持するか、永続化されたセッション状態またはスナップショットから再開することで、設定済みのメモリディレクトリ全体を保持して再利用してください。新しい空の sandbox は空のメモリで開始されます。
 
-`Memory()` は、メモリの読み取りと生成の両方を有効にします。メモリを読み取るが新しいメモリを生成すべきではないエージェントには `Memory(generate=None)` を使用します。たとえば、内部エージェント、subagent、checker、またはシグナルをあまり追加しない単発のツールエージェントです。実行で後のためにメモリを生成すべきだが、既存のメモリの影響は受けたくない場合は、`Memory(read=None)` を使用します。
+`Memory()` は、メモリの読み取りと生成の両方を有効にします。メモリを読み取るが新しいメモリは生成すべきでないエージェントには、`Memory(generate=None)` を使用します。たとえば、内部エージェント、サブエージェント、チェッカー、または実行から得られるシグナルが多くない 1 回限りのツールエージェントです。後で使うメモリを生成する必要はあるものの、ユーザーが既存メモリによる影響を望まない場合は、`Memory(read=None)` を使用します。
 
 ## メモリの読み取り
 
-メモリの読み取りでは段階的開示を使用します。実行開始時に、SDK は一般的に有用なヒント、ユーザーの好み、利用可能なメモリの小さな要約（`memory_summary.md`）をエージェントの開発者プロンプトに注入します。これにより、過去の作業が関連しそうかどうかをエージェントが判断するための十分なコンテキストが与えられます。
+メモリ読み取りでは段階的開示を使用します。実行の開始時に、SDK は一般的に役立つヒント、ユーザーの好み、利用可能なメモリの小さなサマリー（`memory_summary.md`）を、エージェントの developer プロンプトに挿入します。これにより、エージェントは過去の作業が関連しそうかどうかを判断するのに十分なコンテキストを得られます。
 
-過去の作業が関連していそうな場合、エージェントは現在のタスクのキーワードを使って、設定されたメモリインデックス（`memories_dir` 配下の `MEMORY.md`）を検索します。さらに詳しい情報が必要な場合にのみ、設定された `rollout_summaries/` ディレクトリー配下の対応する過去の rollout 要約を開きます。
+過去の作業が関連しそうな場合、エージェントは現在のタスクからキーワードを抽出して、設定されたメモリインデックス（`memories_dir` 配下の `MEMORY.md`）を検索します。より詳細が必要な場合にのみ、設定された `rollout_summaries/` ディレクトリ配下にある対応する過去のロールアウトサマリーを開きます。
 
-メモリは古くなることがあります。エージェントには、メモリはあくまで参考情報として扱い、現在の環境を信頼するよう指示されています。デフォルトでは、メモリ読み取りでは `live_update` が有効になっているため、エージェントが古いメモリを見つけた場合、同じ実行内で設定された `MEMORY.md` を更新できます。たとえば、その実行がレイテンシーに敏感な場合など、エージェントがメモリを読み取るだけで実行中に変更すべきでない場合は、ライブ更新を無効にしてください。
+メモリは古くなることがあります。エージェントには、メモリをガイダンスとしてのみ扱い、現在の環境を信頼するよう指示されています。デフォルトでは、メモリ読み取りでは `live_update` が有効です。そのため、エージェントが古くなったメモリを発見した場合、同じ実行内で設定済みの `MEMORY.md` を更新できます。実行中にメモリを読み取るが変更してほしくない場合、たとえばレイテンシに敏感な実行では、ライブ更新を無効にしてください。
 
 ## メモリの生成
 
-実行が終了すると、sandbox ランタイムはその実行セグメントを会話ファイルに追記します。蓄積された会話ファイルは、sandbox セッションが閉じられるときに処理されます。
+実行が完了すると、sandbox ランタイムはその実行セグメントを会話ファイルに追記します。蓄積された会話ファイルは、sandbox セッションが閉じられるときに処理されます。
 
 メモリ生成には 2 つのフェーズがあります。
 
-1. フェーズ 1: 会話抽出。メモリ生成モデルが蓄積された 1 つの会話ファイルを処理し、会話要約を生成します。system、developer、および reasoning の内容は省略されます。会話が長すぎる場合は、先頭と末尾を保持したまま、コンテキストウィンドウに収まるように切り詰められます。また、フェーズ 2 で統合できるよう、会話からの簡潔なメモである raw メモリ抽出も生成されます。
-2. フェーズ 2: レイアウト統合。統合エージェントが 1 つのメモリレイアウトの raw メモリを読み取り、さらに証拠が必要な場合は会話要約を開き、パターンを `MEMORY.md` と `memory_summary.md` に抽出します。
+1. フェーズ 1: 会話の抽出。メモリ生成モデルが、蓄積された 1 つの会話ファイルを処理し、会話サマリーを生成します。system、developer、reasoning のコンテンツは省略されます。会話が長すぎる場合は、先頭と末尾を保持したうえで、コンテキストウィンドウに収まるよう切り詰められます。また、未加工のメモリ抽出も生成します。これは、フェーズ 2 が統合できる会話からの簡潔なメモです。
+2. フェーズ 2: レイアウトの統合。統合エージェントは、1 つのメモリレイアウトに対応する未加工のメモリを読み取り、より多くの根拠が必要な場合は会話サマリーを開き、パターンを `MEMORY.md` と `memory_summary.md` に抽出します。
 
 デフォルトのワークスペースレイアウトは次のとおりです。
 
@@ -83,7 +83,7 @@ workspace/
     └── skills/
 ```
 
-`MemoryGenerateConfig` を使ってメモリ生成を設定できます。
+`MemoryGenerateConfig` でメモリ生成を設定できます。
 
 ```python
 from agents.sandbox import MemoryGenerateConfig
@@ -97,13 +97,13 @@ memory = Memory(
 )
 ```
 
-`extra_prompt` を使うと、GTM エージェント向けの顧客情報や企業情報のように、どのシグナルがユースケースで最も重要かをメモリ生成器に伝えられます。
+`extra_prompt` を使用して、GTM エージェント向けの顧客や会社の詳細など、ユースケースで最も重要なシグナルをメモリ生成器に伝えます。
 
-最近の raw メモリが `max_raw_memories_for_consolidation`（デフォルトは 256）を超える場合、フェーズ 2 は最新の会話のメモリだけを保持し、古いものを削除します。新しさは、その会話が最後に更新された時刻に基づきます。この忘却メカニズムにより、メモリは最新の環境を反映しやすくなります。
+最近の未加工メモリが `max_raw_memories_for_consolidation`（デフォルトは 256）を超える場合、フェーズ 2 は最新の会話のメモリだけを保持し、古いものを削除します。新しさは、会話が最後に更新された時刻に基づきます。この忘却メカニズムにより、メモリが最新の環境を反映しやすくなります。
 
 ## マルチターン会話
 
-マルチターンの sandbox チャットでは、通常の SDK `Session` を同じライブ sandbox セッションと組み合わせて使用します。
+マルチターンの sandbox チャットでは、同じライブ sandbox セッションとともに通常の SDK `Session` を使用します。
 
 ```python
 from agents import Runner, SQLiteSession
@@ -132,20 +132,20 @@ async with sandbox:
     )
 ```
 
-両方の実行は同じメモリ会話ファイルに追記されます。これは、同じ SDK 会話セッション（`session=conversation_session`）を渡すことで、同じ `session.session_id` を共有するためです。これは、ライブワークスペースを識別する sandbox（`sandbox`）とは異なり、メモリ会話 ID としては使用されません。フェーズ 1 は sandbox セッションが閉じられたときに蓄積された会話を参照するため、分離された 2 つのターンではなく、やり取り全体からメモリを抽出できます。
+どちらの実行も、同じ SDK 会話セッション（`session=conversation_session`）を渡すため、1 つのメモリ会話ファイルに追記され、したがって同じ `session.session_id` を共有します。これはライブワークスペースを識別する sandbox（`sandbox`）とは異なります。`sandbox` はメモリ会話 ID としては使用されません。sandbox セッションが閉じられると、フェーズ 1 は蓄積された会話を参照するため、2 つの孤立したターンではなく、やり取り全体からメモリを抽出できます。
 
-複数の `Runner.run(...)` 呼び出しを 1 つのメモリ会話にしたい場合は、それらの呼び出しにまたがって安定した識別子を渡してください。メモリが実行を会話に関連付けるときは、次の順序で解決されます。
+複数の `Runner.run(...)` 呼び出しを 1 つのメモリ会話にしたい場合は、それらの呼び出し全体で安定した識別子を渡してください。メモリが実行を会話に関連付けるときは、次の順序で解決します。
 
-1. `Runner.run(...)` に渡した `conversation_id`
-2. `SQLiteSession` などの SDK `Session` を渡した場合の `session.session_id`
-3. 上記のいずれも存在しない場合の `RunConfig.group_id`
-4. 安定した識別子が存在しない場合の、実行ごとに生成される ID
+1. `conversation_id`（`Runner.run(...)` に渡した場合）
+2. `session.session_id`（`SQLiteSession` などの SDK `Session` を渡した場合）
+3. `RunConfig.group_id`（上記のどちらも存在しない場合）
+4. 生成された実行ごとの ID（安定した識別子が存在しない場合）
 
-## 異なるエージェント向けのメモリ分離用レイアウト
+## エージェントごとのメモリ分離における異なるレイアウトの利用
 
-メモリの分離は、エージェント名ではなく `MemoryLayoutConfig` に基づきます。同じレイアウトと同じメモリ会話 ID を持つエージェントは、1 つのメモリ会話と 1 つの統合メモリを共有します。異なるレイアウトを持つエージェントは、同じ sandbox ワークスペースを共有していても、別々の rollout ファイル、raw メモリ、`MEMORY.md`、および `memory_summary.md` を保持します。
+メモリの分離はエージェント名ではなく `MemoryLayoutConfig` に基づきます。同じレイアウトと同じメモリ会話 ID を持つエージェントは、1 つのメモリ会話と 1 つの統合済みメモリを共有します。異なるレイアウトを持つエージェントは、同じ sandbox ワークスペースを共有している場合でも、別々のロールアウトファイル、未加工メモリ、`MEMORY.md`、`memory_summary.md` を保持します。
 
-複数のエージェントが 1 つの sandbox を共有しているが、メモリを共有すべきでない場合は、別々のレイアウトを使用します。
+複数のエージェントが 1 つの sandbox を共有するものの、メモリは共有すべきでない場合は、別々のレイアウトを使用します。
 
 ```python
 from agents import SQLiteSession

docs/ja/sandbox_agents.md

@@ -6,17 +6,17 @@ search:
 
 !!! warning "ベータ機能"
 
-    Sandbox エージェントはベータ版です。API、デフォルト、およびサポートされる機能の詳細は一般提供前に変更される可能性があり、今後さらに高度な機能が追加される見込みです。
+    サンドボックスエージェントはベータ版です。一般提供前に API の詳細、デフォルト値、サポートされる機能が変更される可能性があり、今後より高度な機能が追加されることが想定されます。
 
-現代のエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果を発揮します。Agents SDK の **Sandbox Agents** は、大規模なドキュメントセットの検索、ファイル編集、コマンド実行、成果物の生成、保存された Sandbox 状態からの作業再開が可能な永続的なワークスペースをモデルに提供します。
+最新のエージェントは、ファイルシステム上の実際のファイルを操作できるときに最も効果を発揮します。Agents SDK の **サンドボックスエージェント** は、モデルに永続的なワークスペースを提供し、大規模なドキュメントセットの検索、ファイル編集、コマンド実行、成果物の生成、保存済みのサンドボックス状態からの作業再開を可能にします。
 
-SDK は、ファイルステージング、ファイルシステムツール、シェルアクセス、Sandbox ライフサイクル、スナップショット、プロバイダー固有の連携を自分でつなぎ合わせることなく、その実行基盤を提供します。通常の `Agent` と `Runner` のフローを維持したまま、ワークスペース用の `Manifest`、Sandbox ネイティブツール用の機能、作業の実行場所を指定する `SandboxRunConfig` を追加します。
+SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の連携を自分で組み合わせる必要なく、その実行ハーネスを提供します。通常の `Agent` と `Runner` のフローはそのままに、ワークスペース用の `Manifest`、サンドボックスネイティブツール用の機能、作業の実行場所を指定する `SandboxRunConfig` を追加します。
 
 ## 前提条件
 
 - Python 3.10 以上
-- OpenAI Agents SDK の基本的な知識
-- Sandbox クライアント。ローカル開発では、`UnixLocalSandboxClient` から始めてください。
+- OpenAI Agents SDK に関する基本的な理解
+- サンドボックスクライアント。ローカル開発では、`UnixLocalSandboxClient` から始めてください。
 
 ## インストール
 
@@ -26,15 +26,15 @@ SDK をまだインストールしていない場合:
 pip install openai-agents
 ```
 
-Docker ベースの Sandbox の場合:
+Docker ベースのサンドボックスの場合:
 
 ```bash
 pip install "openai-agents[docker]"
 ```
 
-## ローカル Sandbox エージェントの作成
+## ローカルサンドボックスエージェントの作成
 
-この例では、ローカルリポジトリを `repo/` 配下にステージングし、ローカルスキルを遅延読み込みし、Runner が実行用の Unix ローカル Sandbox セッションを作成できるようにします。
+この例では、ローカルリポジトリを `repo/` 配下にステージングし、ローカルスキルを遅延ロードし、ランナーが実行用の Unix ローカルサンドボックスセッションを作成できるようにします。
 
 ```python
 import asyncio
@@ -94,24 +94,24 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例では、小さなシェルベースのリポジトリを使用しているため、Unix ローカル実行間で決定論的に検証できます。
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py) を参照してください。この例は小さなシェルベースのリポジトリを使用しているため、Unix ローカル実行間で決定論的に検証できます。
 
 ## 主な選択肢
 
-基本的な実行が動作したら、多くの人が次に検討する選択肢は次のとおりです。
+基本的な実行が動作したら、次に多くの人が検討する選択肢は次のとおりです。
 
-- `default_manifest`: 新しい Sandbox セッション用のファイル、リポジトリ、ディレクトリ、マウント
-- `instructions`: プロンプト全体に適用すべき短いワークフロールール
-- `base_instructions`: SDK の Sandbox プロンプトを置き換えるための高度なエスケープハッチ
-- `capabilities`: ファイルシステム編集/画像検査、シェル、スキル、メモリ、圧縮などの Sandbox ネイティブツール
-- `run_as`: モデル向けツールの Sandbox ユーザー ID
-- `SandboxRunConfig.client`: Sandbox バックエンド
+- `default_manifest`: 新しいサンドボックスセッション用のファイル、リポジトリ、ディレクトリ、マウント
+- `instructions`: 複数のプロンプトにわたって適用すべき短いワークフロールール
+- `base_instructions`: SDK のサンドボックスプロンプトを置き換えるための高度なエスケープハッチ
+- `capabilities`: ファイルシステム編集 / 画像検査、シェル、スキル、メモリ、コンパクションなどのサンドボックスネイティブツール
+- `run_as`: モデル向けツールで使用するサンドボックスのユーザー ID
+- `SandboxRunConfig.client`: サンドボックスバックエンド
 - `SandboxRunConfig.session`、`session_state`、または `snapshot`: 後続の実行が以前の作業に再接続する方法
 
 ## 次のステップ
 
 - [概念](sandbox/guide.md): マニフェスト、機能、権限、スナップショット、実行設定、構成パターンを理解します。
-- [Sandbox クライアント](sandbox/clients.md): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。
-- [エージェントメモリ](sandbox/memory.md): 以前の Sandbox 実行から得た教訓を保持し、再利用します。
+- [サンドボックスクライアント](sandbox/clients.md): Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。
+- [エージェントメモリ](sandbox/memory.md): 以前のサンドボックス実行から得た知見を保存し、再利用します。
 
-シェルアクセスが時々使うツールの 1 つにすぎない場合は、[ツールガイド](tools.md) のホスト型シェルから始めてください。ワークスペースの分離、Sandbox クライアントの選択、または Sandbox セッションの再開動作が設計の一部である場合は、Sandbox エージェントを使用してください。
+シェルアクセスがたまに使うツールの 1 つにすぎない場合は、[ツールガイド](tools.md) のホスト型シェルから始めてください。ワークスペース分離、サンドボックスクライアントの選択、またはサンドボックスセッションの再開動作が設計に含まれる場合は、サンドボックスエージェントを選択してください。

docs/ja/sessions/advanced_sqlite_session.md

@@ -4,15 +4,15 @@ search:
 ---
 # 高度な SQLite セッション
 
-`AdvancedSQLiteSession` は、基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなどの高度な会話管理機能を提供します。
+`AdvancedSQLiteSession` は基本的な `SQLiteSession` の拡張版であり、会話の分岐、詳細な使用状況分析、構造化された会話クエリなど、高度な会話管理機能を提供します。
 
 ## 機能
 
-- **会話の分岐**: 任意のユーザーメッセージから代替の会話パスを作成
-- **使用状況トラッキング**: 各ターンごとの詳細なトークン使用状況分析（完全な JSON 内訳付き）
-- **構造化クエリ**: ターン単位の会話、ツール使用統計などを取得
-- **ブランチ管理**: 独立したブランチ切り替えと管理
-- **メッセージ構造メタデータ**: メッセージタイプ、ツール使用状況、会話フローを追跡
+- **会話の分岐**: 任意のユーザーメッセージから別の会話パスを作成します
+- **使用状況の追跡**: ターンごとの詳細なトークン使用状況分析を、完全な JSON 内訳付きで提供します
+- **構造化クエリ**: ターン別の会話、ツール使用状況の統計などを取得します
+- **ブランチ管理**: 独立したブランチ切り替えと管理を行います
+- **メッセージ構造メタデータ**: メッセージタイプ、ツール使用、会話フローを追跡します
 
 ## クイックスタート
 
@@ -84,16 +84,16 @@ session = AdvancedSQLiteSession(
 
 ### パラメーター
 
-- `session_id` (str): 会話セッションの一意な識別子
-- `db_path` (str | Path): SQLite データベースファイルへのパス。デフォルトはメモリ内ストレージ用の `:memory:`
-- `create_tables` (bool): 高度なテーブルを自動作成するかどうか。デフォルトは `False`
-- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガー
+- `session_id` (str): 会話セッションの一意の識別子
+- `db_path` (str | Path): SQLite データベースファイルへのパス。デフォルトはインメモリストレージ用の `:memory:` です
+- `create_tables` (bool): 高度なテーブルを自動的に作成するかどうか。デフォルトは `False` です
+- `logger` (logging.Logger | None): セッション用のカスタムロガー。デフォルトはモジュールロガーです
 
-## 使用状況トラッキング
+## 使用状況の追跡
 
-AdvancedSQLiteSession は、会話ターンごとのトークン使用データを保存することで、詳細な使用状況分析を提供します。**これは各エージェント実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。**
+AdvancedSQLiteSession は、会話ターンごとにトークン使用状況データを保存することで、詳細な使用状況分析を提供します。 **これは、各エージェント実行後に `store_run_usage` メソッドが呼び出されることに完全に依存します。**
 
-### 使用データの保存
+### 使用状況データの保存
 
 ```python
 # After each agent run, store the usage data
@@ -107,7 +107,7 @@ await session.store_run_usage(result)
 # - Detailed JSON token information (if available)
 ```
 
-### 使用統計の取得
+### 使用状況統計の取得
 
 ```python
 # Get session-level usage (all branches)
@@ -137,7 +137,7 @@ turn_2_usage = await session.get_turn_usage(user_turn_number=2)
 
 ## 会話の分岐
 
-AdvancedSQLiteSession の主要機能の 1 つは、任意のユーザーメッセージから会話ブランチを作成できることです。これにより、代替の会話パスを探索できます。
+AdvancedSQLiteSession の主要機能の 1 つは、任意のユーザーメッセージから会話ブランチを作成し、別の会話パスを探索できることです。
 
 ### ブランチの作成
 
@@ -245,17 +245,17 @@ for turn in matching_turns:
 
 ### メッセージ構造
 
-セッションは、以下を含むメッセージ構造を自動的に追跡します。
+セッションは、次を含むメッセージ構造を自動的に追跡します。
 
-- メッセージタイプ (user, assistant, tool_call など)
-- ツール呼び出し用のツール名
+- メッセージタイプ（ユーザー、assistant、tool_call など）
+- ツール呼び出しのツール名
 - ターン番号とシーケンス番号
-- ブランチ関連付け
+- ブランチとの関連付け
 - タイムスタンプ
 
 ## データベーススキーマ
 
-AdvancedSQLiteSession は、基本的な SQLite スキーマを次の 2 つの追加テーブルで拡張します。
+AdvancedSQLiteSession は、基本的な SQLite スキーマを 2 つの追加テーブルで拡張します。
 
 ### message_structure テーブル
 
@@ -298,7 +298,7 @@ CREATE TABLE turn_usage (
 
 ## 完全な例
 
-すべての機能を包括的に示すデモについては、[完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)をご確認ください。
+すべての機能を包括的に示す [完全な例](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py) を確認してください。
 
 
 ## API リファレンス

docs/ja/sessions/encrypted_session.md

@@ -4,18 +4,18 @@ search:
 ---
 # 暗号化セッション
 
-`EncryptedSession` は、あらゆるセッション実装に対して透過的な暗号化を提供し、古い項目の自動有効期限切れによって会話データを保護します。
+`EncryptedSession` は、任意のセッション実装に透過的な暗号化を提供し、古いアイテムの自動期限切れによって会話データを保護します。
 
 ## 機能
 
-- **透過的な暗号化**: あらゆるセッションを Fernet 暗号化でラップします
-- **セッションごとのキー**: HKDF 鍵導出を使用して、セッションごとに一意の暗号化を行います
-- **自動有効期限切れ**: TTL が期限切れになると、古い項目は自動的にスキップされます
-- **そのまま置き換え可能**: 既存のあらゆるセッション実装で動作します
+- **透過的な暗号化**: 任意のセッションを Fernet 暗号化でラップします
+- **セッションごとのキー**: HKDF キー導出を使用して、セッションごとに一意の暗号化を行います
+- **自動期限切れ**: TTL が期限切れになると、古いアイテムは取得時に黙ってスキップされます
+- **ドロップイン置換**: 既存の任意のセッション実装で動作します
 
 ## インストール
 
-暗号化セッションには `encrypt` 追加機能が必要です:
+暗号化セッションには `encrypt` extra が必要です。
 
 ```bash
 pip install openai-agents[encrypt]
@@ -57,7 +57,7 @@ if __name__ == "__main__":
 
 ### 暗号化キー
 
-暗号化キーには、Fernet キーまたは任意の文字列を使用できます:
+暗号化キーには、Fernet キーまたは任意の文字列を指定できます。
 
 ```python
 from agents.extensions.memory import EncryptedSession
@@ -81,7 +81,7 @@ session = EncryptedSession(
 
 ### TTL (有効期間)
 
-暗号化された項目を有効とする期間を設定します:
+暗号化されたアイテムが有効であり続ける期間を設定します。
 
 ```python
 # Items expire after 1 hour
@@ -101,7 +101,7 @@ session = EncryptedSession(
 )
 ```
 
-## 異なるセッションタイプでの使用
+## さまざまなセッションタイプでの使用
 
 ### SQLite セッションでの使用
 
@@ -140,30 +140,30 @@ session = EncryptedSession(
 
 !!! warning "高度なセッション機能"
 
-    `AdvancedSQLiteSession` のような高度なセッション実装で `EncryptedSession` を使用する場合は、次の点に注意してください:
+    `EncryptedSession` を `AdvancedSQLiteSession` のような高度なセッション実装と使用する場合は、次の点に注意してください。
 
-    - メッセージ内容は暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に機能しません
-    - コンテンツベースの検索は暗号化データに対して実行されるため、有効性が制限されます
+    - メッセージ内容が暗号化されるため、`find_turns_by_content()` のようなメソッドは効果的に動作しません
+    - コンテンツベースの検索は暗号化されたデータに対して実行されるため、有効性が制限されます
 
 
 
-## 鍵導出
+## キー導出
 
-EncryptedSession は HKDF (HMAC-based Key Derivation Function) を使用して、セッションごとに一意の暗号化キーを導出します:
+EncryptedSession は HKDF (HMAC-based Key Derivation Function) を使用して、セッションごとに一意の暗号化キーを導出します。
 
-- **マスターキー**: 提供した暗号化キー
+- **マスターキー**: 提供された暗号化キー
 - **セッションソルト**: セッション ID
-- **Info 文字列**: `"agents.session-store.hkdf.v1"`
+- **情報文字列**: `"agents.session-store.hkdf.v1"`
 - **出力**: 32 バイトの Fernet キー
 
-これにより、次が保証されます:
-- 各セッションが一意の暗号化キーを持つこと
-- マスターキーなしではキーを導出できないこと
-- セッションデータを異なるセッション間で復号できないこと
+これにより、次のことが保証されます。
+- 各セッションに一意の暗号化キーがあります
+- マスターキーがなければキーを導出できません
+- セッションデータを異なるセッション間で復号できません
 
-## 自動有効期限切れ
+## 自動期限切れ
 
-項目が TTL を超えると、取得時に自動的にスキップされます:
+アイテムが TTL を超えると、取得時に自動的にスキップされます。
 
 ```python
 # Items older than TTL are silently ignored

docs/ja/sessions/index.md

@@ -6,9 +6,9 @@ search:
 
 Agents SDK は、複数のエージェント実行にまたがって会話履歴を自動的に維持する組み込みのセッションメモリを提供し、ターン間で `.to_input_list()` を手動で扱う必要をなくします。
 
-セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずにエージェントがコンテキストを維持できるようにします。これは、チャットアプリケーションや、エージェントに以前のやり取りを記憶させたいマルチターン会話を構築する場合に特に有用です。
+セッションは特定のセッションの会話履歴を保存し、明示的な手動メモリ管理を必要とせずに、エージェントがコンテキストを維持できるようにします。これは、エージェントに以前のやり取りを覚えておいてほしいチャットアプリケーションや複数ターンの会話を構築する場合に特に便利です。
 
-SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI サーバー管理の継続を使いたい場合は、セッションを重ねるのではなく、それらの仕組みのいずれかを選択してください。
+SDK にクライアント側メモリを管理させたい場合は、セッションを使用します。セッションは、同じ実行内で `conversation_id`、`previous_response_id`、または `auto_previous_response_id` と組み合わせることはできません。代わりに OpenAI のサーバー管理による継続を使用したい場合は、セッションを重ねて使うのではなく、それらの仕組みのいずれかを選択してください。
 
 ## クイックスタート
 
@@ -49,9 +49,9 @@ result = Runner.run_sync(
 print(result.final_output)  # "Approximately 39 million"
 ```
 
-## 同じセッションでの中断された実行の再開
+## 同じセッションによる中断された実行の再開
 
-実行が承認待ちで一時停止した場合は、再開後のターンが同じ保存済み会話履歴を引き継ぐように、同じセッションインスタンス（または同じバッキングストアを指す別のセッションインスタンス）で再開してください。
+実行が承認待ちで一時停止した場合は、同じセッションインスタンス（または同じバッキングストアを指す別のセッションインスタンス）で再開し、再開されたターンが同じ保存済み会話履歴を継続するようにします。
 
 ```python
 result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -67,27 +67,27 @@ if result.interruptions:
 
 セッションメモリが有効な場合:
 
-1. **各実行前**: runner はセッションの会話履歴を自動的に取得し、それを入力アイテムの先頭に追加します。
-2. **各実行後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、assistant 応答、ツール呼び出しなど）がセッションに自動的に保存されます。
-3. **コンテキスト保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。
+1. **各実行の前**: ランナーはセッションの会話履歴を自動的に取得し、入力アイテムの前に追加します。
+2. **各実行の後**: 実行中に生成されたすべての新しいアイテム（ユーザー入力、アシスタントの応答、ツール呼び出しなど）がセッションに自動的に保存されます。
+3. **コンテキストの保持**: 同じセッションでの後続の各実行には完全な会話履歴が含まれるため、エージェントはコンテキストを維持できます。
 
-これにより、`.to_input_list()` を手動で呼び出し、実行間の会話状態を管理する必要がなくなります。
+これにより、`.to_input_list()` を手動で呼び出したり、実行間の会話状態を管理したりする必要がなくなります。
 
-## 履歴と新しい入力のマージ制御
+## 履歴と新しい入力のマージ方法の制御
 
-セッションを渡すと、runner は通常、モデル入力を次のように準備します。
+セッションを渡すと、ランナーは通常、モデル入力を次のように準備します。
 
 1. セッション履歴（`session.get_items(...)` から取得）
-2. 新しいターンの入力
+2. 新しいターン入力
 
-モデル呼び出しの前にそのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは 2 つのリストを受け取ります。
+モデル呼び出しの前にこのマージ手順をカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。コールバックは次の 2 つのリストを受け取ります。
 
 -   `history`: 取得されたセッション履歴（すでに入力アイテム形式に正規化済み）
 -   `new_input`: 現在のターンの新しい入力アイテム
 
 モデルに送信する最終的な入力アイテムのリストを返します。
 
-コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK が永続化するのは新しいターンに属するアイテムのみです。そのため、古い履歴を並べ替えたりフィルターしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。
+コールバックは両方のリストのコピーを受け取るため、安全に変更できます。返されたリストはそのターンのモデル入力を制御しますが、SDK は新しいターンに属するアイテムのみを永続化します。そのため、古い履歴を並べ替えたりフィルタリングしたりしても、古いセッションアイテムが新しい入力として再度保存されることはありません。
 
 ```python
 from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -109,16 +109,16 @@ result = await Runner.run(
 )
 ```
 
-セッションがアイテムを保存する方法を変えずに、カスタムの刈り込み、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終パスが必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。
+セッションがアイテムを保存する方法を変更せずに、カスタムの枝刈り、並べ替え、または履歴の選択的な取り込みが必要な場合に使用します。モデル呼び出しの直前にさらに最終的な処理が必要な場合は、[エージェント実行ガイド](../running_agents.md)の [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] を使用してください。
 
-## 取得履歴の制限
+## 取得する履歴の制限
 
-各実行前に取得する履歴量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。
+各実行の前に取得する履歴の量を制御するには、[`SessionSettings`][agents.memory.SessionSettings] を使用します。
 
 -   `SessionSettings(limit=None)`（デフォルト）: 利用可能なすべてのセッションアイテムを取得します
--   `SessionSettings(limit=N)`: 直近の `N` 個のアイテムのみを取得します
+-   `SessionSettings(limit=N)`: 直近の `N` アイテムのみを取得します
 
-これは [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を通じて実行ごとに適用できます。
+これは、[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] を介して実行ごとに適用できます。
 
 ```python
 from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
@@ -134,13 +134,13 @@ result = await Runner.run(
 )
 ```
 
-セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行に対して `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズに上限を設けたい長い会話で有用です。
+セッション実装がデフォルトのセッション設定を公開している場合、`RunConfig.session_settings` はその実行について `None` ではない値を上書きします。これは、セッションのデフォルト動作を変更せずに取得サイズを上限設定したい長い会話で便利です。
 
 ## メモリ操作
 
 ### 基本操作
 
-セッションは会話履歴を管理するためのいくつかの操作をサポートしています。
+セッションは、会話履歴を管理するためのいくつかの操作をサポートしています。
 
 ```python
 from agents import SQLiteSession
@@ -165,9 +165,9 @@ print(last_item)  # {"role": "assistant", "content": "Hi there!"}
 await session.clear_session()
 ```
 
-### 修正での pop_item の使用
+### 修正のための pop_item の使用
 
-`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したりしたい場合に特に有用です。
+`pop_item` メソッドは、会話内の最後のアイテムを取り消したり変更したりしたい場合に特に便利です。
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -204,26 +204,26 @@ SDK は、さまざまなユースケース向けに複数のセッション実
 
 以下の詳細な例を読む前に、開始点を選ぶためにこの表を使用してください。
 
-| セッションタイプ | 最適な用途 | 備考 |
+| セッションタイプ | 最適な用途 | 注記 |
 | --- | --- | --- |
 | `SQLiteSession` | ローカル開発とシンプルなアプリ | 組み込み、軽量、ファイルバックまたはインメモリ |
-| `AsyncSQLiteSession` | `aiosqlite` を使う非同期 SQLite | 非同期ドライバーサポートを備えた拡張バックエンド |
-| `RedisSession` | ワーカー/サービス間で共有されるメモリ | 低レイテンシの分散デプロイに適しています |
-| `SQLAlchemySession` | 既存データベースを持つ本番アプリ | SQLAlchemy がサポートするデータベースで動作します |
-| `MongoDBSession` | すでに MongoDB を使用している、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo。順序付け用のアトミックシーケンスカウンター |
-| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数の状態ストアに加えて TTL と整合性制御をサポート |
-| `OpenAIConversationsSession` | OpenAI 内のサーバー管理ストレージ | OpenAI Conversations API ベースの履歴 |
-| `OpenAIResponsesCompactionSession` | 自動コンパクションを伴う長い会話 | 別のセッションバックエンドのラッパー |
-| `AdvancedSQLiteSession` | SQLite と分岐/分析 | 機能セットはより重めです。専用ページを参照してください |
-| `EncryptedSession` | 別のセッション上の暗号化 + TTL | ラッパーです。まず基盤となるバックエンドを選択してください |
+| `AsyncSQLiteSession` | `aiosqlite` を使用した非同期 SQLite | 非同期ドライバー対応の拡張バックエンド |
+| `RedisSession` | ワーカーやサービス間で共有するメモリ | 低レイテンシの分散デプロイに適しています |
+| `SQLAlchemySession` | 既存データベースを使用する本番アプリ | SQLAlchemy がサポートするデータベースで動作します |
+| `MongoDBSession` | すでに MongoDB を使用しているアプリ、またはマルチプロセスストレージが必要なアプリ | 非同期 pymongo；順序付け用のアトミックシーケンスカウンター |
+| `DaprSession` | Dapr サイドカーを使用するクラウドネイティブデプロイ | 複数のステートストアに加え、TTL と整合性制御をサポートします |
+| `OpenAIConversationsSession` | OpenAI でのサーバー管理ストレージ | OpenAI Conversations API をバックエンドとする履歴 |
+| `OpenAIResponsesCompactionSession` | 自動圧縮を伴う長い会話 | 別のセッションバックエンドをラップします |
+| `AdvancedSQLiteSession` | SQLite に加えて分岐や分析 | より多機能です。専用ページを参照してください |
+| `EncryptedSession` | 別のセッション上での暗号化と TTL | ラッパーです。まず基盤となるバックエンドを選択してください |
 
-一部の実装には追加の詳細を含む専用ページがあり、それぞれの小節内でインラインにリンクされています。
+一部の実装には、追加の詳細を含む専用ページがあります。それらは各サブセクション内でリンクされています。
 
-ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドおよびアイテム永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置換ではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。
+ChatKit 用の Python サーバーを実装している場合は、ChatKit のスレッドとアイテムの永続化に `chatkit.store.Store` 実装を使用してください。`SQLAlchemySession` などの Agents SDK セッションは SDK 側の会話履歴を管理しますが、ChatKit のストアのドロップイン置き換えではありません。[ChatKit データストアの実装に関する `chatkit-python` ガイド](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)を参照してください。
 
 ### OpenAI Conversations API セッション
 
-`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations) を使用します。
+`OpenAIConversationsSession` を通じて [OpenAI の Conversations API](https://platform.openai.com/docs/api-reference/conversations)を使用します。
 
 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -257,11 +257,11 @@ result = await Runner.run(
 print(result.final_output)  # "California"
 ```
 
-### OpenAI Responses コンパクションセッション
+### OpenAI Responses 圧縮セッション
 
-Responses API（`responses.compact`）で保存済み会話履歴をコンパクト化するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターン後に自動的にコンパクションできます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。
+Responses API（`responses.compact`）で保存済みの会話履歴を圧縮するには、`OpenAIResponsesCompactionSession` を使用します。これは基盤となるセッションをラップし、`should_trigger_compaction` に基づいて各ターンの後に自動的に圧縮できます。`OpenAIConversationsSession` をこれでラップしないでください。この 2 つの機能は異なる方法で履歴を管理します。
 
-#### 典型的な使用法（自動コンパクション）
+#### 一般的な使用方法（自動圧縮）
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```
 
-デフォルトでは、候補しきい値に達すると、各ターン後にコンパクションが実行されます。
+デフォルトでは、候補しきい値に達すると各ターンの後に圧縮が実行されます。
 
-`compaction_mode="previous_response_id"` は、Responses API の応答 ID を使ってすでにターンをチェーンしている場合に最適です。`compaction_mode="input"` は代わりに現在のセッションアイテムからコンパクションリクエストを再構築します。これは応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に有用です。デフォルトの `"auto"` は、利用可能な中で最も安全なオプションを選択します。
+`compaction_mode="previous_response_id"` は、Responses API の応答 ID でターンをすでに連鎖させている場合に最も適しています。`compaction_mode="input"` は、代わりに現在のセッションアイテムから圧縮リクエストを再構築します。これは、応答チェーンが利用できない場合や、セッション内容を信頼できる情報源にしたい場合に便利です。デフォルトの `"auto"` は、利用可能な中で最も安全な選択肢を選びます。
 
-エージェントが `ModelSettings(store=False)` で実行されている場合、Responses API は後で参照するために最後の応答を保持しません。このステートレスな設定では、デフォルトの `"auto"` モードは `previous_response_id` に依存する代わりに、入力ベースのコンパクションにフォールバックします。完全な例については [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。
+エージェントが `ModelSettings(store=False)` で実行される場合、Responses API は後で検索するための最後の応答を保持しません。このステートレスな構成では、デフォルトの `"auto"` モードは `previous_response_id` に依存するのではなく、入力ベースの圧縮にフォールバックします。完全な例については、[`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py) を参照してください。
 
-#### 自動コンパクションがストリーミングをブロックする可能性
+#### auto-compaction によるストリーミングのブロック
 
-コンパクションはセッション履歴をクリアして書き直すため、SDK は実行が完了したとみなす前にコンパクションの終了を待ちます。ストリーミングモードでは、コンパクションが重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになる可能性があります。
+圧縮はセッション履歴をクリアして書き換えるため、SDK は実行完了とみなす前に圧縮の完了を待ちます。ストリーミングモードでは、圧縮が重い場合、最後の出力トークンの後も `run.stream_events()` が数秒間開いたままになることがあります。
 
-低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動コンパクションを無効にし、ターン間（またはアイドル時間中）に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ強制的にコンパクションするかを決定できます。
+低レイテンシのストリーミングや高速なターン処理が必要な場合は、自動圧縮を無効にし、ターン間（またはアイドル時間中）に自分で `run_compaction()` を呼び出してください。独自の基準に基づいて、いつ圧縮を強制するかを決めることができます。
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -332,7 +332,7 @@ result = await Runner.run(
 
 ### 非同期 SQLite セッション
 
-`aiosqlite` による SQLite 永続化を使いたい場合は、`AsyncSQLiteSession` を使用します。
+`aiosqlite` をバックエンドとする SQLite の永続化が必要な場合は、`AsyncSQLiteSession` を使用します。
 
 ```bash
 pip install aiosqlite
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### Redis セッション
 
-複数のワーカーまたはサービス間で共有セッションメモリを使うには、`RedisSession` を使用します。
+複数のワーカーまたはサービス間で共有セッションメモリを使用するには、`RedisSession` を使用します。
 
 ```bash
 pip install openai-agents[redis]
@@ -387,11 +387,11 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
 session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 ```
 
-詳細なドキュメントについては [SQLAlchemy セッション](sqlalchemy_session.md)を参照してください。
+詳細なドキュメントについては、[SQLAlchemy セッション](sqlalchemy_session.md)を参照してください。
 
 ### Dapr セッション
 
-すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なる状態ストアバックエンド間を移動できるセッションストレージが必要な場合は、`DaprSession` を使用します。
+すでに Dapr サイドカーを実行している場合、またはエージェントコードを変更せずに異なるステートストアバックエンドへ移行できるセッションストレージが必要な場合は、`DaprSession` を使用します。
 
 ```bash
 pip install openai-agents[dapr]
@@ -412,18 +412,18 @@ async with DaprSession.from_address(
     print(result.final_output)
 ```
 
-備考:
+注記:
 
--   `from_address(...)` は Dapr クライアントを作成し、その所有権を持ちます。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。
--   バッキング状態ストアが TTL をサポートしている場合に、古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。
+-   `from_address(...)` は Dapr クライアントを作成し、所有します。アプリがすでにクライアントを管理している場合は、`dapr_client=...` を指定して `DaprSession(...)` を直接構築してください。
+-   基盤となるステートストアが TTL をサポートしている場合に古いセッションデータを自動的に期限切れにするには、`ttl=...` を渡します。
 -   より強い read-after-write 保証が必要な場合は、`consistency=DAPR_CONSISTENCY_STRONG` を渡します。
--   Dapr Python SDK は HTTP サイドカーエンドポイントも確認します。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。
+-   Dapr Python SDK は HTTP サイドカーエンドポイントもチェックします。ローカル開発では、`dapr_address` で使用する gRPC ポートに加えて、`--dapr-http-port 3500` でも Dapr を起動してください。
 -   ローカルコンポーネントやトラブルシューティングを含む完全なセットアップ手順については、[`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) を参照してください。
 
 
 ### MongoDB セッション
 
-すでに MongoDB を使用しているアプリケーションや、水平スケーラブルなマルチプロセスセッションストレージが必要なアプリケーションでは、`MongoDBSession` を使用します。
+すでに MongoDB を使用しているアプリケーション、または水平スケーラブルでマルチプロセス対応のセッションストレージが必要なアプリケーションには、`MongoDBSession` を使用します。
 
 ```bash
 pip install openai-agents[mongodb]
@@ -446,16 +446,16 @@ print(result.final_output)
 await session.close()
 ```
 
-備考:
+注記:
 
--   `from_uri(...)` は `AsyncMongoClient` を作成して所有し、`session.close()` 時に閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op になり、ライフサイクルは呼び出し元に残ります。
--   そのほかの変更なしに、`mongodb+srv://user:password@cluster.example.mongodb.net` URI を `from_uri(...)` に渡すことで、[MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。
--   2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルト `agent_sessions`）および `messages_collection=`（デフォルト `agent_messages`）で構成できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントには、同時書き込み元やプロセス間で順序を保持する単調増加の `seq` カウンターが含まれます。
+-   `from_uri(...)` は `AsyncMongoClient` を作成し、所有し、`session.close()` で閉じます。アプリケーションがすでにクライアントを管理している場合は、`client=...` を指定して `MongoDBSession(...)` を直接構築してください。その場合、`session.close()` は no-op となり、ライフサイクルは呼び出し元が保持します。
+-   ほかの変更なしに、`from_uri(...)` に `mongodb+srv://user:password@cluster.example.mongodb.net` URI を渡すことで [MongoDB Atlas](https://www.mongodb.com/products/platform) に接続できます。
+-   2 つのコレクションが使用され、どちらの名前も `sessions_collection=`（デフォルトは `agent_sessions`）と `messages_collection=`（デフォルトは `agent_messages`）で設定できます。インデックスは初回使用時に自動的に作成されます。各メッセージドキュメントは、同時実行の書き込み元やプロセスをまたいで順序を保持する単調増加の `seq` カウンターを持ちます。
 -   最初の実行前に接続性を確認するには、`await session.ping()` を使用します。
 
-### Advanced SQLite セッション
+### 高度な SQLite セッション
 
-会話の分岐、利用状況分析、構造化クエリを備えた拡張 SQLite セッションです。
+会話の分岐、使用状況分析、構造化クエリを備えた拡張 SQLite セッションです。
 
 ```python
 from agents.extensions.memory import AdvancedSQLiteSession
@@ -475,7 +475,7 @@ await session.store_run_usage(result)  # Track token usage
 await session.create_branch_from_turn(2)  # Branch from turn 2
 ```
 
-詳細なドキュメントについては [Advanced SQLite セッション](advanced_sqlite_session.md)を参照してください。
+詳細なドキュメントについては、[高度な SQLite セッション](advanced_sqlite_session.md)を参照してください。
 
 ### 暗号化セッション
 
@@ -502,34 +502,34 @@ session = EncryptedSession(
 result = await Runner.run(agent, "Hello", session=session)
 ```
 
-詳細なドキュメントについては [暗号化セッション](encrypted_session.md)を参照してください。
+詳細なドキュメントについては、[暗号化セッション](encrypted_session.md)を参照してください。
 
 ### その他のセッションタイプ
 
-組み込みオプションはさらにいくつかあります。`examples/memory/` および `extensions/memory/` 配下のソースコードを参照してください。
+組み込みの選択肢はほかにもいくつかあります。`examples/memory/` と `extensions/memory/` 以下のソースコードを参照してください。
 
 ## 運用パターン
 
 ### セッション ID の命名
 
-会話を整理しやすくする意味のあるセッション ID を使用してください。
+会話を整理しやすい、意味のあるセッション ID を使用してください。
 
 -   ユーザーベース: `"user_12345"`
 -   スレッドベース: `"thread_abc123"`
 -   コンテキストベース: `"support_ticket_456"`
 
-### メモリ永続化
+### メモリの永続化
 
 -   一時的な会話にはインメモリ SQLite（`SQLiteSession("session_id")`）を使用します
 -   永続的な会話にはファイルベース SQLite（`SQLiteSession("session_id", "path/to/db.sqlite")`）を使用します
--   `aiosqlite` ベースの実装が必要な場合は非同期 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）を使用します
--   共有された低レイテンシのセッションメモリには Redis バックのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します
--   SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy によるセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`）を使用します
--   すでに MongoDB を使用している、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します
--   組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドに対応する本番クラウドネイティブデプロイには、Dapr 状態ストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します
--   履歴を OpenAI Conversations API に保存したい場合は、OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します
--   任意のセッションを透過的な暗号化と TTL ベースの有効期限切れでラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します
--   より高度なユースケースでは、他の本番システム（たとえば Django）向けのカスタムセッションバックエンドの実装を検討してください
+-   `aiosqlite` ベースの実装が必要な場合は、非同期 SQLite（`AsyncSQLiteSession("session_id", db_path="...")`）を使用します
+-   共有された低レイテンシのセッションメモリには、Redis バックのセッション（`RedisSession.from_url("session_id", url="redis://...")`）を使用します
+-   SQLAlchemy がサポートする既存データベースを持つ本番システムには、SQLAlchemy を利用したセッション（`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) を使用します
+-   すでに MongoDB を使用しているアプリケーション、またはマルチプロセスで水平スケーラブルなセッションストレージが必要なアプリケーションには、MongoDB セッション（`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`）を使用します
+-   組み込みのテレメトリ、トレーシング、データ分離を備えた 30 以上のデータベースバックエンドをサポートする本番クラウドネイティブデプロイには、Dapr ステートストアセッション（`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`）を使用します
+-   OpenAI Conversations API に履歴を保存したい場合は、OpenAI がホストするストレージ（`OpenAIConversationsSession()`）を使用します
+-   透過的な暗号化と TTL ベースの有効期限で任意のセッションをラップするには、暗号化セッション（`EncryptedSession(session_id, underlying_session, encryption_key)`）を使用します
+-   より高度なユースケースでは、ほかの本番システム（たとえば Django）向けのカスタムセッションバックエンドの実装を検討してください
 
 ### 複数セッション
 
@@ -684,15 +684,15 @@ result = await Runner.run(
 )
 ```
 
-## コミュニティセッション実装
+## コミュニティによるセッション実装
 
 コミュニティは追加のセッション実装を開発しています。
 
 | パッケージ | 説明 |
 |---------|-------------|
-| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django がサポートする任意のデータベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション |
+| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | 任意の Django 対応データベース（PostgreSQL、MySQL、SQLite など）向けの Django ORM ベースのセッション |
 
-セッション実装を構築した場合は、ここに追加するためのドキュメント PR をぜひ提出してください。
+セッション実装を構築した場合は、ぜひドキュメント PR を送ってここに追加してください。
 
 ## API リファレンス
 
@@ -700,12 +700,12 @@ result = await Runner.run(
 
 -   [`Session`][agents.memory.session.Session] - プロトコルインターフェイス
 -   [`OpenAIConversationsSession`][agents.memory.OpenAIConversationsSession] - OpenAI Conversations API 実装
--   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API コンパクションラッパー
+-   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 圧縮ラッパー
 -   [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 基本的な SQLite 実装
 -   [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` に基づく非同期 SQLite 実装
 -   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis バックのセッション実装
--   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy による実装
+-   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy を利用した実装
 -   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB バックのセッション実装
--   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 状態ストア実装
+-   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr ステートストア実装
 -   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 分岐と分析を備えた拡張 SQLite
 -   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 任意のセッション向けの暗号化ラッパー

docs/ja/sessions/sqlalchemy_session.md

@@ -4,11 +4,11 @@ search:
 ---
 # SQLAlchemy セッション
 
-`SQLAlchemySession` は SQLAlchemy を使用して本番運用対応のセッション実装を提供し、セッションストレージに SQLAlchemy がサポートする任意のデータベース ( PostgreSQL 、 MySQL 、 SQLite など ) を使用できます。
+`SQLAlchemySession` は SQLAlchemy を使用して、本番環境に対応したセッション実装を提供します。これにより、セッションストレージとして SQLAlchemy がサポートする任意のデータベース (PostgreSQL、MySQL、SQLite など) を使用できます。
 
 ## インストール
 
-SQLAlchemy セッションには `sqlalchemy` extra が必要です。
+SQLAlchemy セッションには `sqlalchemy` extra が必要です:
 
 ```bash
 pip install openai-agents[sqlalchemy]
@@ -18,7 +18,7 @@ pip install openai-agents[sqlalchemy]
 
 ### データベース URL の使用
 
-開始する最も簡単な方法です。
+始めるための最も簡単な方法です:
 
 ```python
 import asyncio
@@ -42,9 +42,9 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### 既存 engine の使用
+### 既存エンジンの使用
 
-既存の SQLAlchemy engine があるアプリケーション向けです。
+既存の SQLAlchemy エンジンを持つアプリケーション向けです:
 
 ```python
 import asyncio
@@ -77,4 +77,4 @@ if __name__ == "__main__":
 ## API リファレンス
 
 - [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - メインクラス
-- [`Session`][agents.memory.session.Session] - ベースセッションプロトコル
+- [`Session`][agents.memory.session.Session] - 基本セッションプロトコル

docs/ja/streaming.md

@@ -4,17 +4,17 @@ search:
 ---
 # ストリーミング
 
-ストリーミングを使うと、エージェントの実行が進むにつれて更新を購読できます。これは、エンドユーザーに進捗更新や部分的な応答を表示するのに役立ちます。
+ストリーミングにより、エージェントの実行が進むにつれて更新を購読できます。これは、エンドユーザーに進捗状況の更新や部分的なレスポンスを表示する場合に役立ちます。
 
-ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出すことができ、[`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。
+ストリーミングするには、[`Runner.run_streamed()`][agents.run.Runner.run_streamed] を呼び出します。これにより [`RunResultStreaming`][agents.result.RunResultStreaming] が返されます。`result.stream_events()` を呼び出すと、以下で説明する [`StreamEvent`][agents.stream_events.StreamEvent] オブジェクトの非同期ストリームが得られます。
 
-非同期イテレーターが終了するまで、`result.stream_events()` を消費し続けてください。イテレーターが終了するまで、ストリーミング実行は完了しません。また、セッション永続化、承認の記録管理、履歴の圧縮といった後処理は、最後の可視トークンが到着した後に完了する場合があります。ループを抜けると、`result.is_complete` は最終的な実行状態を反映します。
+非同期イテレーターが終了するまで、`result.stream_events()` を消費し続けてください。ストリーミング実行は、イテレーターが終了するまで完了しません。また、セッションの永続化、承認の記録管理、履歴の圧縮などの後処理は、最後の可視トークンが到着した後に完了する場合があります。ループが終了すると、`result.is_complete` は最終的な実行状態を反映します。
 
-## Raw 応答イベント
+## raw レスポンスイベント
 
-[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントには `response.created`、`response.output_text.delta` などの type とデータがあります。これらのイベントは、応答メッセージが生成され次第ユーザーへストリーミングしたい場合に便利です。
+[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent] は、LLM から直接渡される raw イベントです。これらは OpenAI Responses API 形式であり、各イベントには型（`response.created`、`response.output_text.delta` など）とデータがあります。これらのイベントは、レスポンスメッセージが生成され次第、ユーザーにストリーミングしたい場合に役立ちます。
 
-コンピュータツールの raw イベントは、保存された結果と同じプレビュー版と GA 版の区別を維持します。プレビューのフローでは、1 つの `action` を持つ `computer_call` アイテムをストリーミングします。一方、`gpt-5.5` では、バッチ化された `actions[]` を持つ `computer_call` アイテムをストリーミングできます。より高レベルの [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] サーフェスでは、これに対してコンピュータ専用の特別なイベント名は追加されません。どちらの形も `tool_called` として表面化し、スクリーンショットの結果は `computer_call_output` アイテムをラップする `tool_output` として返されます。
+コンピュータツールの raw イベントは、保存された実行結果と同じ preview と GA の区別を維持します。Preview フローでは、1 つの `action` を持つ `computer_call` アイテムをストリーミングします。一方、`gpt-5.5` では、バッチ化された `actions[]` を持つ `computer_call` アイテムをストリーミングできます。高レベルの [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] サーフェスは、このために特別なコンピュータ専用イベント名を追加しません。どちらの形式も引き続き `tool_called` として表面化し、スクリーンショットの実行結果は `computer_call_output` アイテムをラップする `tool_output` として返されます。
 
 たとえば、これは LLM によって生成されたテキストをトークンごとに出力します。
 
@@ -41,7 +41,7 @@ if __name__ == "__main__":
 
 ## ストリーミングと承認
 
-ストリーミングは、ツール承認のために一時停止する実行と互換性があります。ツールが承認を必要とする場合、`result.stream_events()` は終了し、保留中の承認は [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] に公開されます。`result.to_state()` で結果を [`RunState`][agents.run_state.RunState] に変換し、割り込みを承認または拒否してから、`Runner.run_streamed(...)` で再開します。
+ストリーミングは、ツール承認のために一時停止する実行と互換性があります。ツールに承認が必要な場合、`result.stream_events()` は終了し、保留中の承認は [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions] で公開されます。`result.to_state()` を使って実行結果を [`RunState`][agents.run_state.RunState] に変換し、中断を承認または拒否してから、`Runner.run_streamed(...)` で再開します。
 
 ```python
 result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.")
@@ -57,25 +57,25 @@ if result.interruptions:
         pass
 ```
 
-一時停止と再開の完全なウォークスルーについては、[human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。
+一時停止/再開の完全なウォークスルーについては、[human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。
 
 ## 現在のターン後のストリーミングのキャンセル
 
-途中でストリーミング実行を停止する必要がある場合は、[`result.cancel()`][agents.result.RunResultStreaming.cancel] を呼び出します。デフォルトでは、これにより実行は即座に停止します。停止する前に現在のターンをきれいに完了させるには、代わりに `result.cancel(mode="after_turn")` を呼び出します。
+途中でストリーミング実行を停止する必要がある場合は、[`result.cancel()`][agents.result.RunResultStreaming.cancel] を呼び出します。デフォルトでは、これにより実行はすぐに停止します。停止する前に現在のターンを正常に完了させるには、代わりに `result.cancel(mode="after_turn")` を呼び出します。
 
-`result.stream_events()` が終了するまで、ストリーミング実行は完了しません。SDK は、最後の可視トークンの後も、セッション項目の永続化、承認状態の確定、履歴の圧縮をまだ行っている可能性があります。
+ストリーミング実行は、`result.stream_events()` が終了するまで完了しません。最後の可視トークンの後も、SDK がセッションアイテムを永続化したり、承認状態を確定したり、履歴を圧縮したりしている場合があります。
 
-[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] から手動で続行していて、`cancel(mode="after_turn")` がツールターン後に停止した場合は、すぐに新しいユーザーターンを追加するのではなく、その正規化された入力で `result.last_agent` を再実行して、その未完了のターンを続行してください。
--   ストリーミング実行がツール承認のために停止した場合、それを新しいターンとして扱わないでください。ストリームの読み出しを最後まで行い、`result.interruptions` を確認し、代わりに `result.to_state()` から再開してください。
--   次のモデル呼び出しの前に、取得したセッション履歴と新しいユーザー入力をどのようにマージするかをカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。そこで新規ターンの項目を書き換えた場合、その書き換え後のバージョンがそのターンで永続化されます。
+[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list] から手動で継続しており、`cancel(mode="after_turn")` がツールターンの後で停止した場合は、すぐに新しいユーザーターンを追加するのではなく、その正規化された入力で `result.last_agent` を再実行して、未完了のターンを継続してください。
+-   ストリーミング実行がツール承認のために停止した場合、それを新しいターンとして扱わないでください。ストリームの読み出しを最後まで完了し、`result.interruptions` を確認して、代わりに `result.to_state()` から再開してください。
+-   次のモデル呼び出しの前に、取得したセッション履歴と新しいユーザー入力をどのようにマージするかをカスタマイズするには、[`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] を使用します。そこで新しいターンのアイテムを書き換えた場合、その書き換え後のバージョンがそのターンとして永続化されます。
 
-## 実行項目イベントとエージェントイベント
+## 実行アイテムイベントとエージェントイベント
 
-[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。これらは、項目が完全に生成されたときに通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を送信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変わったとき（例: ハンドオフの結果として）に更新を提供します。
+[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] は、より高レベルのイベントです。アイテムが完全に生成されたタイミングを通知します。これにより、各トークン単位ではなく、「メッセージが生成された」「ツールが実行された」などのレベルで進捗更新を送信できます。同様に、[`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] は、現在のエージェントが変更されたとき（例: ハンドオフの結果として）に更新を提供します。
 
-### 実行項目イベント名
+### 実行アイテムイベント名
 
-`RunItemStreamEvent.name` は、固定されたセマンティックなイベント名のセットを使用します。
+`RunItemStreamEvent.name` は、固定された一連のセマンティックなイベント名を使用します。
 
 -   `message_output_created`
 -   `handoff_requested`
@@ -89,9 +89,9 @@ if result.interruptions:
 -   `mcp_approval_response`
 -   `mcp_list_tools`
 
-`handoff_occured` は、後方互換性のために意図的にスペルミスされています。
+`handoff_occured` は、後方互換性のため意図的にスペルミスのままになっています。
 
-ホスト型ツール検索を使用する場合、モデルがツール検索リクエストを発行すると `tool_search_called` が発行され、Responses API が読み込まれたサブセットを返すと `tool_search_output_created` が発行されます。
+ホストされたツール検索を使用する場合、モデルがツール検索リクエストを発行すると `tool_search_called` が送出され、Responses API が読み込まれたサブセットを返すと `tool_search_output_created` が送出されます。
 
 たとえば、これは raw イベントを無視し、更新をユーザーにストリーミングします。
 

docs/ja/tools.md

@@ -4,37 +4,37 @@ search:
 ---
 # ツール
 
-ツールにより、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。
+ツールにより、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータの操作といったアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。
 
 -   OpenAI がホストするツール: OpenAI サーバー上でモデルと並行して実行されます。
--   ローカル/ランタイム実行ツール: `ComputerTool` と `ApplyPatchTool` は常にお使いの環境で実行され、`ShellTool` はローカルまたはホストされたコンテナーで実行できます。
--   Function Calling: 任意の Python 関数をツールとしてラップします。
+-   ローカル/ランタイム実行ツール: `ComputerTool` と `ApplyPatchTool` は常にユーザーの環境で実行され、`ShellTool` はローカルまたはホスト型コンテナーで実行できます。
+-   Function calling: 任意の Python 関数をツールとしてラップします。
 -   Agents as tools: 完全なハンドオフなしで、エージェントを呼び出し可能なツールとして公開します。
--   実験的: Codex ツール: ツール呼び出しからワークスペーススコープの Codex タスクを実行します。
+-   実験的機能: Codex ツール: ツール呼び出しから、ワークスペーススコープの Codex タスクを実行します。
 
-## ツール種別の選択
+## ツールタイプの選択
 
-このページをカタログとして使い、その後、管理するランタイムに合ったセクションへ進んでください。
+このページをカタログとして使い、制御するランタイムに一致するセクションに移動してください。
 
-| 実現したいこと | 参照先 |
+| やりたいこと | 開始先 |
 | --- | --- |
-| OpenAI 管理のツール（Web 検索、ファイル検索、コードインタープリター、ホストされた MCP、画像生成）を使用する | [ホストされたツール](#hosted-tools) |
-| ツール検索で大規模なツールサーフェスをランタイムまで遅延させる | [ホストされたツール検索](#hosted-tool-search) |
-| 自分のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) |
+| OpenAI 管理のツール（Web 検索、ファイル検索、code interpreter、ホスト型 MCP、画像生成）を使用する | [ホスト型ツール](#hosted-tools) |
+| ツール検索で大規模なツールサーフェスをランタイムまで遅延させる | [ホスト型ツール検索](#hosted-tool-search) |
+| 自身のプロセスまたは環境でツールを実行する | [ローカルランタイムツール](#local-runtime-tools) |
 | Python 関数をツールとしてラップする | [関数ツール](#function-tools) |
-| あるエージェントがハンドオフなしで別のエージェントを呼び出せるようにする | [Agents as tools](#agents-as-tools) |
-| エージェントからワークスペーススコープの Codex タスクを実行する | [実験的: Codex ツール](#experimental-codex-tool) |
+| ハンドオフなしで、あるエージェントが別のエージェントを呼び出せるようにする | [Agents as tools](#agents-as-tools) |
+| エージェントからワークスペーススコープの Codex タスクを実行する | [実験的機能: Codex ツール](#experimental-codex-tool) |
 
-## ホストされたツール
+## ホスト型ツール
 
 OpenAI は [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] を使用する場合に、いくつかの組み込みツールを提供しています。
 
--   [`WebSearchTool`][agents.tool.WebSearchTool] は、エージェントが Web を検索できるようにします。
--   [`FileSearchTool`][agents.tool.FileSearchTool] は、OpenAI Vector Stores から情報を取得できるようにします。
--   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] は、LLM がサンドボックス環境でコードを実行できるようにします。
+-   [`WebSearchTool`][agents.tool.WebSearchTool] により、エージェントは Web を検索できます。
+-   [`FileSearchTool`][agents.tool.FileSearchTool] により、OpenAI ベクトルストアから情報を取得できます。
+-   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool] により、LLM はサンドボックス化された環境でコードを実行できます。
 -   [`HostedMCPTool`][agents.tool.HostedMCPTool] は、リモート MCP サーバーのツールをモデルに公開します。
 -   [`ImageGenerationTool`][agents.tool.ImageGenerationTool] は、プロンプトから画像を生成します。
--   [`ToolSearchTool`][agents.tool.ToolSearchTool] は、モデルが遅延されたツール、名前空間、またはホストされた MCP サーバーを必要に応じて読み込めるようにします。
+-   [`ToolSearchTool`][agents.tool.ToolSearchTool] により、モデルは遅延されたツール、名前空間、またはホスト型 MCP サーバーを必要に応じて読み込めます。
 
 高度なホスト型検索オプション:
 
@@ -60,11 +60,11 @@ async def main():
     print(result.final_output)
 ```
 
-### ホストされたツール検索
+### ホスト型ツール検索
 
-ツール検索により、OpenAI Responses モデルは大規模なツールサーフェスをランタイムまで遅延できるため、モデルは現在のターンに必要なサブセットだけを読み込みます。多数の関数ツール、名前空間グループ、またはホストされた MCP サーバーがあり、すべてのツールを最初から公開せずにツールスキーマのトークンを削減したい場合に便利です。
+ツール検索により、OpenAI Responses モデルは大規模なツールサーフェスをランタイムまで遅延できるため、モデルは現在のターンに必要なサブセットのみを読み込みます。これは、多数の関数ツール、名前空間グループ、またはホスト型 MCP サーバーがあり、すべてのツールを事前に公開せずにツールスキーマのトークンを削減したい場合に便利です。
 
-候補となるツールがエージェントを構築する時点ですでに分かっている場合は、ホストされたツール検索から始めてください。アプリケーションが何を読み込むかを動的に決める必要がある場合、Responses API はクライアント実行のツール検索もサポートしていますが、標準の `Runner` はそのモードを自動実行しません。
+エージェントを構築する時点で候補ツールがすでに分かっている場合は、ホスト型ツール検索から始めてください。アプリケーションが何を読み込むかを動的に決定する必要がある場合、Responses API はクライアント実行型ツール検索もサポートしていますが、標準の `Runner` はそのモードを自動実行しません。
 
 ```python
 from typing import Annotated
@@ -108,24 +108,24 @@ print(result.final_output)
 
 知っておくべきこと:
 
--   ホストされたツール検索は OpenAI Responses モデルでのみ利用できます。現在の Python SDK サポートは `openai>=2.25.0` に依存します。
--   エージェントで遅延読み込みサーフェスを設定する場合は、`ToolSearchTool()` を正確に 1 つ追加してください。
+-   ホスト型ツール検索は、OpenAI Responses モデルでのみ利用できます。現在の Python SDK のサポートは `openai>=2.25.0` に依存します。
+-   エージェントで遅延読み込みサーフェスを構成するときは、`ToolSearchTool()` を正確に 1 つ追加してください。
 -   検索可能なサーフェスには、`@function_tool(defer_loading=True)`、`tool_namespace(name=..., description=..., tools=[...])`、`HostedMCPTool(tool_config={..., "defer_loading": True})` が含まれます。
--   遅延読み込みの関数ツールは `ToolSearchTool()` と組み合わせる必要があります。名前空間のみの構成でも、モデルが必要に応じて適切なグループを読み込めるように `ToolSearchTool()` を使用できます。
+-   遅延読み込みの関数ツールは、`ToolSearchTool()` と組み合わせる必要があります。名前空間のみの構成でも、モデルが必要に応じて適切なグループを読み込めるようにするために `ToolSearchTool()` を使用できます。
 -   `tool_namespace()` は、`FunctionTool` インスタンスを共有の名前空間名と説明の下にグループ化します。これは通常、`crm`、`billing`、`shipping` など、関連するツールが多数ある場合に最適です。
--   OpenAI の公式ベストプラクティスガイダンスは [可能な場合は名前空間を使用する](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible) です。
--   可能な場合は、多数の個別に遅延された関数よりも、名前空間またはホストされた MCP サーバーを優先してください。通常、モデルにより良い高レベルの検索サーフェスと、より良いトークン節約を提供します。
--   名前空間では、即時ツールと遅延ツールを混在させることができます。`defer_loading=True` がないツールは即座に呼び出し可能なままで、同じ名前空間内の遅延ツールはツール検索を通じて読み込まれます。
+-   OpenAI の公式ベストプラクティスガイダンスは、[可能な場合は名前空間を使用する](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)です。
+-   可能な場合は、多数の個別に遅延された関数よりも、名前空間またはホスト型 MCP サーバーを優先してください。通常、これらはモデルに対してより優れた高レベルの検索サーフェスと、より大きなトークン節約を提供します。
+-   名前空間では、即時ツールと遅延ツールを混在させることができます。`defer_loading=True` のないツールはすぐに呼び出し可能なままで、同じ名前空間内の遅延ツールはツール検索を通じて読み込まれます。
 -   目安として、各名前空間はかなり小さく保ち、理想的には 10 個未満の関数にしてください。
--   名前付き `tool_choice` は、裸の名前空間名や遅延のみのツールを対象にできません。`auto`、`required`、または実際のトップレベルで呼び出し可能なツール名を優先してください。
--   `ToolSearchTool(execution="client")` は手動の Responses オーケストレーション用です。モデルがクライアント実行の `tool_search_call` を出力した場合、標準の `Runner` はそれを実行する代わりに例外を発生させます。
--   ツール検索のアクティビティは、専用のアイテムタイプとイベントタイプで [`RunResult.new_items`](results.md#new-items) および [`RunItemStreamEvent`](streaming.md#run-item-event-names) に表示されます。
--   名前空間による読み込みとトップレベルの遅延ツールの両方を網羅した、完全に実行可能なコード例については `examples/tools/tool_search.py` を参照してください。
+-   名前付きの `tool_choice` は、裸の名前空間名や遅延のみのツールを対象にできません。`auto`、`required`、または実際のトップレベルの呼び出し可能なツール名を優先してください。
+-   `ToolSearchTool(execution="client")` は、手動の Responses オーケストレーション用です。モデルがクライアント実行型の `tool_search_call` を発行した場合、標準の `Runner` はそれを実行せずに例外を送出します。
+-   ツール検索アクティビティは、[`RunResult.new_items`](results.md#new-items) と [`RunItemStreamEvent`](streaming.md#run-item-event-names) に、専用の項目タイプとイベントタイプで表示されます。
+-   名前空間付き読み込みとトップレベルの遅延ツールの両方を扱う、完全に実行可能なコード例については、`examples/tools/tool_search.py` を参照してください。
 -   公式プラットフォームガイド: [ツール検索](https://developers.openai.com/api/docs/guides/tools-tool-search)。
 
-### ホストされたコンテナーシェル + スキル
+### ホスト型コンテナーシェル + スキル
 
-`ShellTool` は OpenAI がホストするコンテナー実行もサポートしています。ローカルランタイムではなく、管理されたコンテナー内でモデルにシェルコマンドを実行させたい場合は、このモードを使用してください。
+`ShellTool` は、OpenAI がホストするコンテナー実行もサポートしています。ローカルランタイムではなく、管理されたコンテナー内でモデルにシェルコマンドを実行させたい場合は、このモードを使用します。
 
 ```python
 from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -158,52 +158,52 @@ result = await Runner.run(
 print(result.final_output)
 ```
 
-後続の実行で既存のコンテナーを再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。
+以降の実行で既存のコンテナーを再利用するには、`environment={"type": "container_reference", "container_id": "cntr_..."}` を設定します。
 
 知っておくべきこと:
 
--   ホストされたシェルは Responses API のシェルツールを通じて利用できます。
--   `container_auto` はリクエスト用にコンテナーをプロビジョニングし、`container_reference` は既存のコンテナーを再利用します。
+-   ホスト型シェルは、Responses API シェルツールを通じて利用できます。
+-   `container_auto` は、リクエスト用のコンテナーをプロビジョニングします。`container_reference` は既存のコンテナーを再利用します。
 -   `container_auto` には `file_ids` と `memory_limit` も含めることができます。
--   `environment.skills` はスキル参照とインラインスキルバンドルを受け付けます。
--   ホストされた環境では、`ShellTool` に `executor`、`needs_approval`、`on_approval` を設定しないでください。
--   `network_policy` は `disabled` モードと `allowlist` モードをサポートします。
--   allowlist モードでは、`network_policy.domain_secrets` が名前でドメインスコープのシークレットを注入できます。
--   完全な例については `examples/tools/container_shell_skill_reference.py` と `examples/tools/container_shell_inline_skill.py` を参照してください。
--   OpenAI プラットフォームガイド: [Shell](https://platform.openai.com/docs/guides/tools-shell) および [Skills](https://platform.openai.com/docs/guides/tools-skills)。
+-   `environment.skills` は、スキル参照とインラインスキルバンドルを受け取ります。
+-   ホスト型環境では、`ShellTool` に `executor`、`needs_approval`、`on_approval` を設定しないでください。
+-   `network_policy` は、`disabled` モードと `allowlist` モードをサポートします。
+-   `allowlist` モードでは、`network_policy.domain_secrets` により、名前でドメインスコープのシークレットを注入できます。
+-   完全なコード例については、`examples/tools/container_shell_skill_reference.py` と `examples/tools/container_shell_inline_skill.py` を参照してください。
+-   OpenAI プラットフォームガイド: [シェル](https://platform.openai.com/docs/guides/tools-shell) と [スキル](https://platform.openai.com/docs/guides/tools-skills)。
 
 ## ローカルランタイムツール
 
-ローカルランタイムツールは、モデル応答自体の外部で実行されます。モデルは依然としていつ呼び出すかを決定しますが、実際の処理はアプリケーションまたは設定された実行環境が行います。
+ローカルランタイムツールは、モデル応答自体の外で実行されます。モデルは引き続きいつ呼び出すかを決定しますが、実際の作業はアプリケーションまたは構成された実行環境が実行します。
 
-`ComputerTool` と `ApplyPatchTool` は、常にユーザーが提供するローカル実装を必要とします。`ShellTool` は両方のモードにまたがります。管理された実行を行いたい場合は上記のホストされたコンテナー設定を使用し、自分のプロセスでコマンドを実行したい場合は以下のローカルランタイム設定を使用してください。
+`ComputerTool` と `ApplyPatchTool` には、常にユーザーが提供するローカル実装が必要です。`ShellTool` は両方のモードにまたがっています。管理された実行が必要な場合は上記のホスト型コンテナー構成を使用し、自身のプロセスでコマンドを実行したい場合は下記のローカルランタイム構成を使用してください。
 
 ローカルランタイムツールでは、実装を提供する必要があります。
 
 -   [`ComputerTool`][agents.tool.ComputerTool]: GUI/ブラウザー自動化を有効にするために、[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] インターフェイスを実装します。
--   [`ShellTool`][agents.tool.ShellTool]: ローカル実行とホストされたコンテナー実行の両方に対応する最新のシェルツールです。
--   [`LocalShellTool`][agents.tool.LocalShellTool]: 従来のローカルシェル統合です。
+-   [`ShellTool`][agents.tool.ShellTool]: ローカル実行とホスト型コンテナー実行の両方に対応する最新のシェルツールです。
+-   [`LocalShellTool`][agents.tool.LocalShellTool]: レガシーなローカルシェル連携です。
 -   [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: diff をローカルに適用するために [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor] を実装します。
--   ローカルシェルスキルは `ShellTool(environment={"type": "local", "skills": [...]})` で利用できます。
+-   ローカルシェルスキルは、`ShellTool(environment={"type": "local", "skills": [...]})` で利用できます。
 
 ### ComputerTool と Responses コンピュータツール
 
-`ComputerTool` は引き続きローカルハーネスです。[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] 実装を提供し、SDK がそのハーネスを OpenAI Responses API のコンピュータサーフェスにマッピングします。
+`ComputerTool` は引き続きローカルハーネスです。[`Computer`][agents.computer.Computer] または [`AsyncComputer`][agents.computer.AsyncComputer] の実装を提供すると、SDK はそのハーネスを OpenAI Responses API のコンピュータサーフェスにマッピングします。
 
-明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストでは、SDK は GA 組み込みツールペイロード `{"type": "computer"}` を送信します。古い `computer-use-preview` モデルは、プレビュー用ペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` のままです。これは OpenAI の [コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/) で説明されているプラットフォーム移行を反映しています。
+明示的な [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) リクエストでは、SDK は GA 組み込みツールペイロード `{"type": "computer"}` を送信します。古い `computer-use-preview` モデルでは、プレビューペイロード `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}` が維持されます。これは、OpenAI の [コンピュータ操作ガイド](https://developers.openai.com/api/docs/guides/tools-computer-use/)で説明されているプラットフォーム移行を反映しています。
 
 -   モデル: `computer-use-preview` -> `gpt-5.5`
 -   ツールセレクター: `computer_use_preview` -> `computer`
 -   コンピュータ呼び出しの形状: `computer_call` ごとに 1 つの `action` -> `computer_call` 上のバッチ化された `actions[]`
--   切り詰め: プレビューパスでは `ModelSettings(truncation="auto")` が必要 -> GA パスでは不要
+-   切り捨て: プレビューパスでは `ModelSettings(truncation="auto")` が必須 -> GA パスでは不要
 
-SDK は、実際の Responses リクエストで有効なモデルから、そのワイヤー形式を選択します。プロンプトテンプレートを使用し、プロンプト側がモデルを所有しているためリクエストで `model` を省略する場合、`model="gpt-5.5"` を明示したままにするか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。
+SDK は、実際の Responses リクエスト上の有効なモデルから、そのワイヤ形式を選択します。プロンプトテンプレートを使用し、プロンプトがモデルを保持しているためリクエストが `model` を省略する場合、`model="gpt-5.5"` を明示的に保持するか、`ModelSettings(tool_choice="computer")` または `ModelSettings(tool_choice="computer_use")` で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。
 
-[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け付けられ、有効なリクエストモデルに一致する組み込みセレクターへ正規化されます。`ComputerTool` がない場合、これらの文字列は引き続き通常の関数名のように動作します。
+[`ComputerTool`][agents.tool.ComputerTool] が存在する場合、`tool_choice="computer"`、`"computer_use"`、`"computer_use_preview"` はすべて受け入れられ、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。`ComputerTool` がない場合、これらの文字列は引き続き通常の関数名のように動作します。
 
-この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリによって支えられている場合に重要です。GA の `computer` ペイロードはシリアライズ時に `environment` や寸法を必要としないため、未解決のファクトリでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるように、解決済みの `Computer` または `AsyncComputer` インスタンスが必要です。
+この違いは、`ComputerTool` が [`ComputerProvider`][agents.tool.ComputerProvider] ファクトリーによって支えられている場合に重要です。GA の `computer` ペイロードはシリアライズ時に `environment` や寸法を必要としないため、未解決のファクトリーでも問題ありません。プレビュー互換のシリアライズでは、SDK が `environment`、`display_width`、`display_height` を送信できるように、解決済みの `Computer` または `AsyncComputer` インスタンスが引き続き必要です。
 
-ランタイムでは、どちらのパスも同じローカルハーネスを使用します。プレビュー応答は単一の `action` を持つ `computer_call` アイテムを出力します。`gpt-5.5` はバッチ化された `actions[]` を出力でき、SDK は `computer_call_output` スクリーンショットアイテムを生成する前に、それらを順番に実行します。実行可能な Playwright ベースのハーネスについては `examples/tools/computer_use.py` を参照してください。
+ランタイムでは、どちらのパスも同じローカルハーネスを使用します。プレビュー応答は単一の `action` を持つ `computer_call` 項目を発行します。`gpt-5.5` はバッチ化された `actions[]` を発行でき、SDK は `computer_call_output` スクリーンショット項目を生成する前にそれらを順番に実行します。実行可能な Playwright ベースのハーネスについては、`examples/tools/computer_use.py` を参照してください。
 
 ```python
 from agents import Agent, ApplyPatchTool, ShellTool
@@ -247,16 +247,16 @@ agent = Agent(
 
 ## 関数ツール
 
-任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的にセットアップします。
+任意の Python 関数をツールとして使用できます。Agents SDK はツールを自動的に設定します。
 
--   ツール名は Python 関数の名前になります（または名前を指定できます）
+-   ツールの名前は Python 関数の名前になります（または名前を指定できます）
 -   ツールの説明は関数の docstring から取得されます（または説明を指定できます）
 -   関数入力のスキーマは、関数の引数から自動的に作成されます
--   無効にしない限り、各入力の説明は関数の docstring から取得されます
+-   各入力の説明は、無効化されていない限り、関数の docstring から取得されます
 
 関数シグネチャの抽出には Python の `inspect` モジュールを使用し、docstring の解析には [`griffe`](https://mkdocstrings.github.io/griffe/) を、スキーマ作成には `pydantic` を使用します。
 
-OpenAI Responses モデルを使用している場合、`@function_tool(defer_loading=True)` は `ToolSearchTool()` が読み込むまで関数ツールを隠します。関連する関数ツールを [`tool_namespace()`][agents.tool.tool_namespace] でグループ化することもできます。完全なセットアップと制約については [ホストされたツール検索](#hosted-tool-search) を参照してください。
+OpenAI Responses モデルを使用している場合、`@function_tool(defer_loading=True)` は `ToolSearchTool()` が読み込むまで関数ツールを隠します。[`tool_namespace()`][agents.tool.tool_namespace] を使用して、関連する関数ツールをグループ化することもできます。詳細な設定と制約については、[ホスト型ツール検索](#hosted-tool-search)を参照してください。
 
 ```python
 import json
@@ -310,7 +310,7 @@ for tool in agent.tools:
 
 1.  関数の引数には任意の Python 型を使用でき、関数は同期でも非同期でもかまいません。
 2.  Docstring が存在する場合、説明と引数の説明を取得するために使用されます
-3.  関数は任意で `context` を受け取ることができます（最初の引数でなければなりません）。ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。
+3.  関数は任意で `context` を受け取れます（最初の引数である必要があります）。ツール名、説明、使用する docstring スタイルなどのオーバーライドも設定できます。
 4.  デコレートされた関数をツールのリストに渡すことができます。
 
 ??? note "出力を表示するには展開してください"
@@ -385,20 +385,20 @@ for tool in agent.tools:
 
 ### 関数ツールからの画像またはファイルの返却
 
-テキスト出力の返却に加えて、関数ツールの出力として 1 つ以上の画像またはファイルを返すことができます。そのためには、次のいずれかを返せます。
+テキスト出力を返すことに加えて、関数ツールの出力として 1 つまたは複数の画像やファイルを返すことができます。そのためには、次のいずれかを返せます。
 
 -   画像: [`ToolOutputImage`][agents.tool.ToolOutputImage]（または TypedDict 版の [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict]）
 -   ファイル: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent]（または TypedDict 版の [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict]）
--   テキスト: 文字列または文字列化できるオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
+-   テキスト: 文字列または文字列化可能なオブジェクト、または [`ToolOutputText`][agents.tool.ToolOutputText]（または TypedDict 版の [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict]）
 
 ### カスタム関数ツール
 
-Python 関数をツールとして使用したくない場合もあります。その場合は、必要に応じて [`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次を提供する必要があります。
+Python 関数をツールとして使いたくない場合があります。希望する場合は、[`FunctionTool`][agents.tool.FunctionTool] を直接作成できます。次のものを提供する必要があります。
 
 -   `name`
 -   `description`
--   `params_json_schema`: 引数用の JSON スキーマ
--   `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] と JSON 文字列としての引数を受け取り、ツール出力（たとえば、テキスト、structured tool output オブジェクト、または出力のリスト）を返す非同期関数
+-   `params_json_schema`: 引数用の JSON スキーマです
+-   `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext] と引数を JSON 文字列として受け取り、ツール出力（たとえば、テキスト、構造化ツール出力オブジェクト、または出力のリスト）を返す非同期関数です。
 
 ```python
 from typing import Any
@@ -433,16 +433,16 @@ tool = FunctionTool(
 
 ### 引数と docstring の自動解析
 
-前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動的に解析し、ツールと個々の引数の説明を抽出するために docstring を解析します。これに関するいくつかの注記です。
+前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動的に解析し、ツールと個々の引数の説明を抽出するために docstring を解析します。これについての注意点は次のとおりです。
 
-1. シグネチャ解析は `inspect` モジュールを通じて行われます。型アノテーションを使用して引数の型を理解し、スキーマ全体を表す Pydantic モデルを動的に構築します。Python の基本コンポーネント、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。
-2. Docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますが、これはベストエフォートであり、`function_tool` を呼び出すときに明示的に設定できます。`use_docstring_info` を `False` に設定して、docstring 解析を無効にすることもできます。
+1. シグネチャ解析は `inspect` モジュールを介して行われます。引数の型を理解するために型アノテーションを使用し、全体のスキーマを表す Pydantic モデルを動的に構築します。Python のプリミティブ型、Pydantic モデル、TypedDict など、ほとんどの型をサポートします。
+2. Docstring の解析には `griffe` を使用します。サポートされる docstring 形式は `google`、`sphinx`、`numpy` です。docstring 形式の自動検出を試みますが、これはベストエフォートであり、`function_tool` を呼び出すときに明示的に設定できます。`use_docstring_info` を `False` に設定することで、docstring 解析を無効化することもできます。
 
 スキーマ抽出のコードは [`agents.function_schema`][] にあります。
 
 ### Pydantic Field による引数の制約と説明
 
-Pydantic の [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) を使用して、ツール引数に制約（例: 数値の最小/最大、文字列の長さやパターン）と説明を追加できます。Pydantic と同様に、デフォルトベース（`arg: int = Field(..., ge=1)`）と `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）の両方の形式がサポートされます。生成される JSON スキーマと検証には、これらの制約が含まれます。
+Pydantic の [`Field`](https://docs.pydantic.dev/latest/concepts/fields/) を使用して、ツール引数に制約（例: 数値の最小/最大、文字列の長さまたはパターン）と説明を追加できます。Pydantic と同様に、デフォルトベース（`arg: int = Field(..., ge=1)`）と `Annotated`（`arg: Annotated[int, Field(..., ge=1)]`）の両方の形式がサポートされます。生成される JSON スキーマと検証には、これらの制約が含まれます。
 
 ```python
 from typing import Annotated
@@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr
 
 ### 関数ツールのタイムアウト
 
-非同期関数ツールに対して、`@function_tool(timeout=...)` で呼び出しごとのタイムアウトを設定できます。
+`@function_tool(timeout=...)` を使用して、非同期関数ツールに呼び出し単位のタイムアウトを設定できます。
 
 ```python
 import asyncio
@@ -482,12 +482,12 @@ agent = Agent(
 )
 ```
 
-タイムアウトに達すると、デフォルトの動作は `timeout_behavior="error_as_result"` で、モデルに見えるタイムアウトメッセージ（例: `Tool 'slow_lookup' timed out after 2 seconds.`）を送信します。
+タイムアウトに達した場合、デフォルトの動作は `timeout_behavior="error_as_result"` で、モデルに表示されるタイムアウトメッセージ（例: `Tool 'slow_lookup' timed out after 2 seconds.`）を送信します。
 
-タイムアウト処理は制御できます。
+タイムアウト処理を制御できます。
 
--   `timeout_behavior="error_as_result"`（デフォルト）: モデルが回復できるようにタイムアウトメッセージを返します。
--   `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] を発生させ、実行を失敗させます。
+-   `timeout_behavior="error_as_result"`（デフォルト）: モデルが回復できるように、タイムアウトメッセージをモデルに返します。
+-   `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError] を送出し、実行を失敗させます。
 -   `timeout_error_function=...`: `error_as_result` を使用する場合のタイムアウトメッセージをカスタマイズします。
 
 ```python
@@ -511,15 +511,15 @@ except ToolTimeoutError as e:
 
 !!! note
 
-    タイムアウト設定は、非同期の `@function_tool` ハンドラーでのみサポートされます。
+    タイムアウト構成は、非同期の `@function_tool` ハンドラーでのみサポートされます。
 
-### 関数ツールでのエラー処理
+### 関数ツールのエラー処理
 
-`@function_tool` を通じて関数ツールを作成するとき、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。
+`@function_tool` を介して関数ツールを作成する場合、`failure_error_function` を渡すことができます。これは、ツール呼び出しがクラッシュした場合に LLM へエラー応答を提供する関数です。
 
--   デフォルトでは（つまり何も渡さない場合）、エラーが発生したことを LLM に伝える `default_tool_error_function` が実行されます。
--   独自のエラー関数を渡した場合は、代わりにそれが実行され、応答が LLM に送信されます。
--   明示的に `None` を渡した場合、ツール呼び出しエラーは再送出され、ユーザー側で処理できます。これは、モデルが無効な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などである可能性があります。
+-   デフォルトでは（つまり何も渡さない場合）、LLM にエラーが発生したことを伝える `default_tool_error_function` が実行されます。
+-   独自のエラー関数を渡した場合は、それが代わりに実行され、その応答が LLM に送信されます。
+-   明示的に `None` を渡した場合、任意のツール呼び出しエラーが再送出され、呼び出し側で処理できます。これは、モデルが無効な JSON を生成した場合の `ModelBehaviorError` や、コードがクラッシュした場合の `UserError` などになり得ます。
 
 ```python
 from agents import function_tool, RunContextWrapper
@@ -546,7 +546,7 @@ def get_user_profile(user_id: str) -> str:
 
 ## Agents as tools
 
-一部のワークフローでは、制御をハンドオフするのではなく、中央のエージェントが専門エージェントのネットワークをオーケストレーションするようにしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。
+一部のワークフローでは、制御をハンドオフする代わりに、中央エージェントに専門特化したエージェントのネットワークをオーケストレーションさせたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。
 
 ```python
 from agents import Agent, Runner
@@ -587,7 +587,7 @@ async def main():
 
 ### ツールエージェントのカスタマイズ
 
-`agent.as_tool` 関数は、エージェントをツールに変換しやすくするための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による structured input もサポートします。高度なオーケストレーション（たとえば、条件付きリトライ、フォールバック動作、複数のエージェント呼び出しのチェーン）には、ツール実装内で `Runner.run` を直接使用してください。
+`agent.as_tool` 関数は、エージェントをツールに簡単に変換するための便利なメソッドです。`max_turns`、`run_config`、`hooks`、`previous_response_id`、`conversation_id`、`session`、`needs_approval` などの一般的なランタイムオプションをサポートします。また、`parameters`、`input_builder`、`include_input_schema` による構造化入力もサポートします。高度なオーケストレーション（たとえば、条件付きリトライ、フォールバック動作、複数のエージェント呼び出しのチェーン）の場合は、ツール実装内で `Runner.run` を直接使用してください。
 
 ```python
 @function_tool
@@ -606,29 +606,47 @@ async def run_my_agent() -> str:
     return str(result.final_output)
 ```
 
-### ツールエージェントの structured input
+### ツールエージェントの構造化入力
 
-デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたは dataclass 型）を渡すことで structured schema を公開できます。
+デフォルトでは、`Agent.as_tool()` は単一の文字列入力（`{"input": "..."}`）を想定しますが、`parameters`（Pydantic モデルまたは dataclass 型）を渡すことで構造化スキーマを公開できます。
 
 追加オプション:
 
-- `include_input_schema=True` は、生成されるネストされた入力に完全な JSON Schema を含めます。
-- `input_builder=...` により、structured tool 引数をネストされたエージェント入力に変換する方法を完全にカスタマイズできます。
-- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内の解析済み structured payload が含まれます。
+- `include_input_schema=True` は、生成されるネストされた入力に完全な JSON スキーマを含めます。
+- `input_builder=...` により、構造化ツール引数がネストされたエージェント入力になる方法を完全にカスタマイズできます。
+- `RunContextWrapper.tool_input` には、ネストされた実行コンテキスト内の解析済み構造化ペイロードが含まれます。
 
-完全に実行可能な例については `examples/agent_patterns/agents_as_tools_structured.py` を参照してください。
+```python
+from pydantic import BaseModel, Field
+
+
+class TranslationInput(BaseModel):
+    text: str = Field(description="Text to translate.")
+    source: str = Field(description="Source language.")
+    target: str = Field(description="Target language.")
+
+
+translator_tool = translator_agent.as_tool(
+    tool_name="translate_text",
+    tool_description="Translate text between languages.",
+    parameters=TranslationInput,
+    include_input_schema=True,
+)
+```
+
+完全に実行可能な例については、`examples/agent_patterns/agents_as_tools_structured.py` を参照してください。
 
 ### ツールエージェントの承認ゲート
 
-`Agent.as_tool(..., needs_approval=...)` は `function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中のアイテムが `result.interruptions` に表示されます。その後、`result.to_state()` を使用し、`state.approve(...)` または `state.reject(...)` を呼び出した後に再開します。完全な一時停止/再開パターンについては、[ヒューマンインザループガイド](human_in_the_loop.md) を参照してください。
+`Agent.as_tool(..., needs_approval=...)` は、`function_tool` と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中の項目が `result.interruptions` に表示されます。その後、`result.to_state()` を使い、`state.approve(...)` または `state.reject(...)` を呼び出した後に再開します。完全な一時停止/再開パターンについては、[Human-in-the-loop ガイド](human_in_the_loop.md)を参照してください。
 
 ### カスタム出力抽出
 
-特定のケースでは、中央エージェントへ返す前にツールエージェントの出力を変更したい場合があります。これは、次のような場合に役立ちます。
+場合によっては、中央エージェントに返す前に、ツールエージェントの出力を変更したいことがあります。これは、次のような場合に便利です。
 
 -   サブエージェントのチャット履歴から特定の情報（例: JSON ペイロード）を抽出する。
 -   エージェントの最終回答を変換または再フォーマットする（例: Markdown をプレーンテキストまたは CSV に変換する）。
--   出力を検証する、またはエージェントの応答が欠落しているか不正な形式の場合にフォールバック値を提供する。
+-   エージェントの応答が欠落している、または不正な形式の場合に、出力を検証するかフォールバック値を提供する。
 
 これは、`as_tool` メソッドに `custom_output_extractor` 引数を指定することで実行できます。
 
@@ -650,12 +668,13 @@ json_tool = data_agent.as_tool(
 ```
 
 カスタム抽出器内では、ネストされた [`RunResult`][agents.result.RunResult] も
-[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] を公開します。これは、ネストされた実行結果を後処理するときに、外側のツール名、呼び出し ID、または raw 引数が必要な場合に便利です。
-[Results ガイド](results.md#agent-as-tool-metadata) を参照してください。
+[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] を公開します。これは、ネストされた実行結果を後処理する際に、
+外側のツール名、呼び出し ID、または生の引数が必要な場合に便利です。
+[実行結果ガイド](results.md#agent-as-tool-metadata)を参照してください。
 
 ### ネストされたエージェント実行のストリーミング
 
-ネストされたエージェントが出力するストリーミングイベントをリッスンしつつ、ストリーム完了後に最終出力を返すには、`as_tool` に `on_stream` コールバックを渡します。
+`as_tool` に `on_stream` コールバックを渡すと、ネストされたエージェントが発行するストリーミングイベントをリッスンしつつ、ストリーム完了後にその最終出力を返せます。
 
 ```python
 from agents import AgentToolStreamEvent
@@ -676,14 +695,14 @@ billing_agent_tool = billing_agent.as_tool(
 想定されること:
 
 - イベントタイプは `StreamEvent["type"]` を反映します: `raw_response_event`、`run_item_stream_event`、`agent_updated_stream_event`。
-- `on_stream` を指定すると、ネストされたエージェントがストリーミングモードで自動的に実行され、最終出力を返す前にストリームが排出されます。
-- ハンドラーは同期または非同期のどちらでもよく、各イベントは到着順に配信されます。
-- ツールがモデルのツール呼び出し経由で起動された場合は `tool_call` が存在します。直接呼び出しでは `None` のままになる場合があります。
-- 完全に実行可能なサンプルについては `examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。
+- `on_stream` を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームが読み切られます。
+- ハンドラーは同期または非同期にできます。各イベントは到着した順に配信されます。
+- モデルツール呼び出しを介してツールが呼び出された場合、`tool_call` が存在します。直接呼び出しでは `None` のままになる場合があります。
+- 完全に実行可能なサンプルについては、`examples/agent_patterns/agents_as_tools_streaming.py` を参照してください。
 
 ### 条件付きツール有効化
 
-`is_enabled` パラメーターを使用すると、ランタイムでエージェントツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザー設定、またはランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。
+`is_enabled` パラメーターを使用して、ランタイムでエージェントツールを条件付きで有効化または無効化できます。これにより、コンテキスト、ユーザー設定、またはランタイム条件に基づいて、LLM が利用できるツールを動的にフィルタリングできます。
 
 ```python
 import asyncio
@@ -742,20 +761,20 @@ asyncio.run(main())
 
 -   **ブール値**: `True`（常に有効）または `False`（常に無効）
 -   **呼び出し可能関数**: `(context, agent)` を受け取り、ブール値を返す関数
--   **非同期関数**: 複雑な条件ロジックのための非同期関数
+-   **非同期関数**: 複雑な条件ロジック用の非同期関数
 
-無効化されたツールはランタイムで LLM から完全に隠されるため、次の用途に役立ちます。
+無効化されたツールは、ランタイムで LLM から完全に隠されるため、次のような用途に便利です。
 
 -   ユーザー権限に基づく機能ゲーティング
 -   環境固有のツール可用性（dev と prod）
 -   異なるツール構成の A/B テスト
 -   ランタイム状態に基づく動的なツールフィルタリング
 
-## 実験的: Codex ツール
+## 実験的機能: Codex ツール
 
 `codex_tool` は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペーススコープのタスク（シェル、ファイル編集、MCP ツール）を実行できるようにします。このサーフェスは実験的であり、変更される可能性があります。
 
-メインエージェントが現在の実行から離れずに、範囲が限定されたワークスペースタスクを Codex に委任したい場合に使用します。デフォルトでは、ツール名は `codex` です。カスタム名を設定する場合は、`codex` であるか、`codex_` で始まる必要があります。エージェントに複数の Codex ツールを含める場合、それぞれ一意の名前を使用する必要があります。
+メインエージェントが現在の実行を離れることなく、範囲を限定したワークスペースタスクを Codex に委任したい場合に使用します。デフォルトでは、ツール名は `codex` です。カスタム名を設定する場合、それは `codex` であるか、`codex_` で始まる必要があります。エージェントに複数の Codex ツールが含まれる場合、それぞれが一意の名前を使用する必要があります。
 
 ```python
 from agents import Agent
@@ -784,33 +803,33 @@ agent = Agent(
 )
 ```
 
-まず、次のオプショングループから始めてください。
+次のオプショングループから始めてください。
 
--   実行サーフェス: `sandbox_mode` と `working_directory` は Codex が操作できる場所を定義します。これらを組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定します。
--   スレッドのデフォルト: `default_thread_options=ThreadOptions(...)` は、モデル、推論エフォート、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを設定します。従来の `web_search_enabled` よりも `web_search_mode` を優先してください。
--   ターンのデフォルト: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` や任意のキャンセル `signal` など、ターンごとの動作を設定します。
--   ツール I/O: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` アイテムを少なくとも 1 つ含める必要があります。`output_schema` により、structured Codex レスポンスを要求できます。
+-   実行サーフェス: `sandbox_mode` と `working_directory` は、Codex が操作できる場所を定義します。これらは組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は `skip_git_repo_check=True` を設定してください。
+-   スレッドデフォルト: `default_thread_options=ThreadOptions(...)` は、モデル、推論エフォート、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを構成します。レガシーな `web_search_enabled` よりも `web_search_mode` を優先してください。
+-   ターンデフォルト: `default_turn_options=TurnOptions(...)` は、`idle_timeout_seconds` や任意のキャンセル `signal` など、ターンごとの動作を構成します。
+-   ツール I/O: ツール呼び出しには、`{ "type": "text", "text": ... }` または `{ "type": "local_image", "path": ... }` を持つ `inputs` 項目が少なくとも 1 つ含まれている必要があります。`output_schema` により、構造化された Codex 応答を要求できます。
 
-スレッドの再利用と永続化は別々の制御です。
+スレッド再利用と永続化は別々の制御です。
 
--   `persist_session=True` は、同じツールインスタンスへの繰り返し呼び出しに対して 1 つの Codex スレッドを再利用します。
--   `use_run_context_thread_id=True` は、同じ可変コンテキストオブジェクトを共有する実行間で、実行コンテキストにスレッド ID を保存して再利用します。
--   スレッド ID の優先順位は、呼び出しごとの `thread_id`、次に実行コンテキストのスレッド ID（有効な場合）、次に設定された `thread_id` オプションです。
+-   `persist_session=True` は、同じツールインスタンスへの繰り返し呼び出しに 1 つの Codex スレッドを再利用します。
+-   `use_run_context_thread_id=True` は、同じ可変コンテキストオブジェクトを共有する実行間で、実行コンテキスト内にスレッド ID を保存して再利用します。
+-   スレッド ID の優先順位は、呼び出しごとの `thread_id`、次に実行コンテキストのスレッド ID（有効な場合）、次に構成済みの `thread_id` オプションです。
 -   デフォルトの実行コンテキストキーは、`name="codex"` の場合は `codex_thread_id`、`name="codex_<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` を解決し、その後バンドルされたベンダーバイナリへフォールバックします。
--   環境: `codex_options.env` はサブプロセス環境を完全に制御します。指定された場合、サブプロセスは `os.environ` を継承しません。
--   ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes`（または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）は stdout/stderr リーダーの制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。
--   ストリーミング: `on_stream` はスレッド/ターンのライフサイクルイベントとアイテムイベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、および `error` アイテム更新）を受け取ります。
+-   バイナリ解決: CLI パスを固定するには、`codex_options.codex_path_override`（または `CODEX_PATH`）を設定します。そうでない場合、SDK は `PATH` から `codex` を解決し、その後、同梱のベンダーバイナリにフォールバックします。
+-   環境: `codex_options.env` はサブプロセス環境を完全に制御します。これが指定された場合、サブプロセスは `os.environ` を継承しません。
+-   ストリーム制限: `codex_options.codex_subprocess_stream_limit_bytes`（または `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`）は stdout/stderr リーダー制限を制御します。有効範囲は `65536` から `67108864` で、デフォルトは `8388608` です。
+-   ストリーミング: `on_stream` はスレッド/ターンのライフサイクルイベントと項目イベント（`reasoning`、`command_execution`、`mcp_tool_call`、`file_change`、`web_search`、`todo_list`、`error` の項目更新）を受け取ります。
 -   出力: 実行結果には `response`、`usage`、`thread_id` が含まれます。usage は `RunContextWrapper.usage` に追加されます。
 
-参考:
+リファレンス:
 
 -   [Codex ツール API リファレンス](ref/extensions/experimental/codex/codex_tool.md)
 -   [ThreadOptions リファレンス](ref/extensions/experimental/codex/thread_options.md)
 -   [TurnOptions リファレンス](ref/extensions/experimental/codex/turn_options.md)
--   完全に実行可能なサンプルについては `examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。
+-   完全に実行可能なサンプルについては、`examples/tools/codex.py` と `examples/tools/codex_same_thread.py` を参照してください。

docs/ja/tracing.md

@@ -4,55 +4,58 @@ search:
 ---
 # トレーシング
 
-Agents SDK には組み込みのトレーシングが含まれており、エージェント実行中のイベントを包括的に記録します。これには、LLM の生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。
+Agents SDK には組み込みのトレーシングが含まれており、エージェント実行中のイベントの包括的な記録を収集します。これには、LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらには発生するカスタムイベントまで含まれます。[Traces ダッシュボード](https://platform.openai.com/traces)を使用すると、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。
 
 !!!note
 
-    トレーシングはデフォルトで有効です。無効にする一般的な方法は 3 つあります。
+    トレーシングはデフォルトで有効になっています。一般的には、次の 3 つの方法で無効にできます。
 
-    1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます
-    2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード内でグローバルにトレーシングを無効化できます
-    3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行に対してトレーシングを無効化できます
+    1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定することで、トレーシングをグローバルに無効化できます
+    2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード内でトレーシングをグローバルに無効化できます
+    3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定することで、単一の実行についてトレーシングを無効化できます
 
-***OpenAI の API を使用し、Zero Data Retention ( ZDR ) ポリシーのもとで運用している組織では、トレーシングは利用できません。***
+***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシー下で運用している組織では、トレーシングは利用できません。***
 
 ## トレースとスパン
 
--   **トレース** は、1 つの「ワークフロー」における単一のエンドツーエンド操作を表します。トレースは Span で構成されます。トレースには次のプロパティがあります。
-    -   `workflow_name`: 論理的なワークフローまたはアプリです。たとえば、「Code generation」や「Customer service」などです。
-    -   `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。
-    -   `group_id`: オプションのグループ ID で、同じ会話内の複数のトレースを関連付けるために使用します。たとえば、チャットスレッド ID を使用できます。
+-   **トレース** は、「ワークフロー」の単一のエンドツーエンド操作を表します。これらはスパンで構成されます。トレースには以下のプロパティがあります:
+    -   `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「コード生成」や「カスタマーサービス」です。
+    -   `trace_id`: トレースの一意の ID です。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` でなければなりません。
+    -   `group_id`: 任意のグループ ID で、同じ会話からの複数のトレースを関連付けるために使用します。たとえば、チャットスレッド ID を使用できます。
     -   `disabled`: True の場合、トレースは記録されません。
-    -   `metadata`: トレースのオプションのメタデータです。
--   **スパン** は、開始時刻と終了時刻を持つ操作を表します。スパンには次のものがあります。
+    -   `metadata`: トレースの任意のメタデータです。
+-   **スパン** は、開始時刻と終了時刻を持つ操作を表します。スパンには以下があります:
     -   `started_at` と `ended_at` のタイムスタンプ。
     -   `trace_id`: そのスパンが属するトレースを表します
-    -   `parent_id`: このスパンの親 Span を指します（存在する場合）
-    -   `span_data`: Span に関する情報です。たとえば、`AgentSpanData` には Agent に関する情報が、`GenerationSpanData` には LLM 生成に関する情報が含まれます。
+    -   `parent_id`: このスパンの親スパン (存在する場合) を指します
+    -   `span_data`: スパンに関する情報です。たとえば、`AgentSpanData` にはエージェントに関する情報が含まれ、`GenerationSpanData` には LLM 生成に関する情報が含まれる、などです。
 
 ## デフォルトのトレーシング
 
-デフォルトでは、SDK は次のものをトレースします。
+デフォルトでは、SDK は以下をトレースします:
 
 -   `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。
 -   エージェントが実行されるたびに、`agent_span()` でラップされます
--   LLM の生成は `generation_span()` でラップされます
--   関数ツールの各呼び出しは `function_span()` でラップされます
+-   LLM 生成は `generation_span()` でラップされます
+-   関数ツール呼び出しはそれぞれ `function_span()` でラップされます
 -   ガードレールは `guardrail_span()` でラップされます
 -   ハンドオフは `handoff_span()` でラップされます
--   音声入力（ speech-to-text ）は `transcription_span()` でラップされます
--   音声出力（ text-to-speech ）は `speech_span()` でラップされます
--   関連する音声スパンは `speech_group_span()` の配下になる場合があります
+-   音声入力 (音声テキスト変換) は `transcription_span()` でラップされます
+-   音声出力 (テキスト音声変換) は `speech_span()` でラップされます
+-   関連する音声スパンは `speech_group_span()` の下に親子関係として配置される場合があります
 
-デフォルトでは、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] を使って名前やその他のプロパティを設定することもできます。
+デフォルトでは、トレース名は "Agent workflow" です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを構成できます。
 
-さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へ送ることもできます（置き換え先または補助的な送信先として）。
+さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors)を設定して、トレースを他の送信先へ送信することもできます (置き換え、または副次的な送信先として)。
 
 ## 長時間実行ワーカーと即時エクスポート
 
-デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごとにバックグラウンドでトレースをエクスポートします。あるいは、インメモリキューがサイズのしきい値に達した場合はそれより早くエクスポートし、さらにプロセス終了時には最終フラッシュも実行します。Celery、RQ、Dramatiq、FastAPI のバックグラウンドタスクなどの長時間実行ワーカーでは、通常は追加コードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後には Traces ダッシュボードに表示されないことがあります。
+デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごとにバックグラウンドでトレースをエクスポートします。
+または、メモリ内キューがサイズトリガーに達した場合はそれより早くエクスポートし、
+プロセス終了時にも最終的なフラッシュを実行します。Celery、RQ、Dramatiq、FastAPI バックグラウンドタスクのような長時間実行ワーカーでは、通常、追加コードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後に Traces ダッシュボードへ表示されない場合があります。
 
-作業単位の終了時に即時配信を保証したい場合は、トレースコンテキストを抜けた後で [`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。
+作業単位の終了時に即時配信の保証が必要な場合は、トレースコンテキストが終了した後に
+[`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。
 
 ```python
 from agents import Runner, flush_traces, trace
@@ -89,11 +92,12 @@ async def run(prompt: str, background_tasks: BackgroundTasks):
     return {"status": "queued"}
 ```
 
-[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファされているトレースとスパンがエクスポートされるまでブロックするため、不完全なトレースをフラッシュしないよう、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で問題ない場合は、この呼び出しは省略できます。
+[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファリングされているトレースとスパンが
+エクスポートされるまでブロックします。そのため、部分的に構築されたトレースをフラッシュしないように、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で許容できる場合は、この呼び出しを省略できます。
 
 ## 上位レベルのトレース
 
-複数の `run()` 呼び出しを 1 つのトレースに含めたい場合があります。その場合は、コード全体を `trace()` でラップできます。
+場合によっては、`run()` への複数回の呼び出しを 1 つのトレースの一部にしたいことがあります。コード全体を `trace()` でラップすることで実現できます。
 
 ```python
 from agents import Agent, Runner, trace
@@ -108,49 +112,49 @@ async def main():
         print(f"Rating: {second_result.final_output}")
 ```
 
-1. 2 回の `Runner.run` 呼び出しは `with trace()` でラップされているため、個別に 2 つのトレースを作成するのではなく、全体のトレースの一部になります。
+1. 2 つの `Runner.run` 呼び出しは `with trace()` でラップされているため、個別の実行は 2 つのトレースを作成するのではなく、全体のトレースの一部になります。
 
 ## トレースの作成
 
-[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。その方法は 2 つあります。
+[`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始および終了する必要があります。これには 2 つの方法があります:
 
-1. **推奨**: トレースをコンテキストマネージャーとして使用します。つまり、`with trace(...) as my_trace` のように使います。これにより、適切なタイミングでトレースが自動的に開始および終了されます。
+1. **推奨**: トレースをコンテキストマネージャーとして使用します。つまり、`with trace(...) as my_trace` とします。これにより、適切なタイミングでトレースが自動的に開始および終了されます。
 2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。
 
-現在のトレースは、Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これは、並行実行でも自動的に動作することを意味します。トレースを手動で開始または終了する場合は、現在のトレースを更新するために `start()` / `finish()` に `mark_as_current` と `reset_current` を渡す必要があります。
+現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。これにより、並行処理でも自動的に機能します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。
 
 ## スパンの作成
 
-各種 [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムのスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。
+各種 [`*_span()`][agents.tracing.create] メソッドを使用してスパンを作成できます。一般に、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数が利用できます。
 
-スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの配下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。
+スパンは自動的に現在のトレースの一部となり、現在の最も近いスパンの下にネストされます。この現在のスパンは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) によって追跡されます。
 
-## 機微データ
+## 機密データ
 
-一部のスパンでは、機微データとなり得る情報を取得する場合があります。
+一部のスパンは、機密性の高い可能性があるデータをキャプチャする場合があります。
 
-`generation_span()` は LLM 生成の入出力を保存し、`function_span()` は関数呼び出しの入出力を保存します。これらには機微データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] によってそのデータの取得を無効化できます。
+`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使ってそのデータのキャプチャを無効化できます。
 
-同様に、音声スパンにはデフォルトで入力音声と出力音声の base64 エンコード済み PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。
+同様に、音声スパンには、デフォルトで入力および出力音声の base64 エンコードされた PCM データが含まれます。この音声データのキャプチャは、[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を構成することで無効化できます。
 
-デフォルトでは、`trace_include_sensitive_data` は `True` です。コードを書かずにデフォルト値を設定するには、アプリの実行前に環境変数 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` を `true/1` または `false/0` に設定してください。
+デフォルトでは、`trace_include_sensitive_data` は `True` です。アプリを実行する前に `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 環境変数を `true/1` または `false/0` にエクスポートすることで、コードなしでデフォルトを設定できます。
 
 ## カスタムトレーシングプロセッサー
 
-トレーシングの高レベルなアーキテクチャは次のとおりです。
+トレーシングの高レベルアーキテクチャは次のとおりです:
 
 -   初期化時に、トレースの作成を担当するグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。
--   `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で設定します。このプロセッサーは、トレース / スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、これがスパンとトレースをバッチで OpenAI バックエンドへエクスポートします。
+-   `TraceProvider` は、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信する [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成します。`BackendSpanExporter` は、スパンとトレースをバッチで OpenAI バックエンドにエクスポートします。
 
-このデフォルト設定をカスタマイズして、別のバックエンドまたは追加のバックエンドにトレースを送信したり、エクスポーターの動作を変更したりするには、2 つの方法があります。
+このデフォルト設定をカスタマイズして、代替または追加のバックエンドへトレースを送信したり、エクスポーターの動作を変更したりするには、2 つの選択肢があります:
 
-1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使うと、準備が整ったトレースとスパンを受け取る **追加の** トレースプロセッサーを追加できます。これにより、トレースを OpenAI のバックエンドへ送信することに加えて、独自の処理も行えます。
-2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使うと、デフォルトのプロセッサーを独自のトレースプロセッサーで **置き換え** できます。これは、そうした処理を行う `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。
+1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使用すると、利用可能になったトレースとスパンを受け取る **追加** のトレーシングプロセッサーを追加できます。これにより、トレースを OpenAI バックエンドに送信することに加えて、独自の処理を実行できます。
+2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使用すると、デフォルトのプロセッサーを独自のトレーシングプロセッサーで **置き換える** ことができます。これは、それを行う `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。
 
 
-## non-OpenAI モデルでのトレーシング
+## 非 OpenAI モデルでのトレーシング
 
-OpenAI 以外のモデルでも、OpenAI API キーを使用することで、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。アダプターの選択と設定上の注意点については、Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションを参照してください。
+非 OpenAI モデルで OpenAI API キーを使用すると、トレーシングを無効にする必要なく、OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。アダプターの選択とセットアップ時の注意点については、モデルガイドの[サードパーティアダプター](models/index.md#third-party-adapters)セクションを参照してください。
 
 ```python
 import os
@@ -171,7 +175,7 @@ agent = Agent(
 )
 ```
 
-単一の実行に対してのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更するのではなく、`RunConfig` 経由で渡してください。
+単一の実行で異なるトレーシングキーだけが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。
 
 ```python
 from agents import Runner, RunConfig
@@ -183,21 +187,21 @@ await Runner.run(
 )
 ```
 
-## 追加の注記
-- Openai Traces ダッシュボードで無料トレースを表示できます。
+## 補足事項
+- Openai Traces ダッシュボードで無料のトレースを表示できます。
 
 
 ## エコシステム統合
 
-以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシング機能をサポートしています。
+以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシングインターフェイスに対応しています。
 
 ### 外部トレーシングプロセッサー一覧
 
 -   [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
 -   [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
 -   [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents)
--   [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
--   [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
+-   [MLflow (セルフホスト/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
+-   [MLflow (Databricks ホスト)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
 -   [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
 -   [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
 -   [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)

docs/ja/usage.md

@@ -2,24 +2,24 @@
 search:
   exclude: true
 ---
-# 使用方法
+# 使用量
 
-Agents SDK は、すべての実行についてトークン使用量を自動的に追跡します。実行コンテキストからこれにアクセスし、コストの監視、制限の適用、または分析の記録に使用できます。
+Agents SDK は、各実行のトークン使用量を自動的に追跡します。実行コンテキストからアクセスでき、コストの監視、上限の適用、分析情報の記録に利用できます。
 
 ## 追跡対象
 
-- **requests**: 実行された LLM API 呼び出し回数
+- **requests**: 実行された LLM API 呼び出しの数
 - **input_tokens**: 送信された入力トークンの合計
-- **output_tokens**: 受信した出力トークンの合計
+- **output_tokens**: 受信された出力トークンの合計
 - **total_tokens**: 入力 + 出力
-- **request_usage_entries**: リクエストごとの使用量内訳の一覧
+- **request_usage_entries**: リクエストごとの使用量内訳のリスト
 - **details**:
   - `input_tokens_details.cached_tokens`
   - `output_tokens_details.reasoning_tokens`
 
-## 実行からの使用量アクセス
+## 実行からの使用量へのアクセス
 
-`Runner.run(...)` の後、`result.context_wrapper.usage` 経由で使用量にアクセスします。
+`Runner.run(...)` の後に、`result.context_wrapper.usage` 経由で使用量にアクセスします。
 
 ```python
 result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -31,20 +31,20 @@ print("Output tokens:", usage.output_tokens)
 print("Total tokens:", usage.total_tokens)
 ```
 
-使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しとハンドオフを含む）にわたって集計されます。
+使用量は、実行中のすべてのモデル呼び出し（ツール呼び出しやハンドオフを含む）にわたって集計されます。
 
-### サードパーティアダプターでの使用量有効化
+### サードパーティアダプターでの使用量の有効化
 
-使用量レポートは、サードパーティアダプターおよびプロバイダーバックエンドによって異なります。アダプター経由のモデルに依存し、正確な `result.context_wrapper.usage` の値が必要な場合:
+使用量レポートは、サードパーティアダプターやプロバイダーのバックエンドによって異なります。アダプター経由のモデルに依存しており、正確な `result.context_wrapper.usage` 値が必要な場合は、次の点に注意してください。
 
-- `AnyLLMModel` では、上流プロバイダーが使用量を返すと自動的に伝播されます。ストリーミング Chat Completions バックエンドでは、使用量チャンクが出力される前に `ModelSettings(include_usage=True)` が必要な場合があります。
-- `LitellmModel` では、一部のプロバイダーバックエンドは既定で使用量をレポートしないため、`ModelSettings(include_usage=True)` が必要になることがよくあります。
+- `AnyLLMModel` では、上流プロバイダーが使用量を返す場合、使用量は自動的に伝播されます。ストリーミングされた Chat Completions バックエンドでは、使用量チャンクが出力される前に `ModelSettings(include_usage=True)` が必要になる場合があります。
+- `LitellmModel` では、一部のプロバイダーのバックエンドがデフォルトで使用量をレポートしないため、`ModelSettings(include_usage=True)` が必要になることがよくあります。
 
-Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションにあるアダプター固有の注意事項を確認し、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
+Models ガイドの [サードパーティアダプター](models/index.md#third-party-adapters) セクションにあるアダプター固有の注記を確認し、デプロイ予定の正確なプロバイダーバックエンドを検証してください。
 
 ## リクエストごとの使用量追跡
 
-SDK は、各 API リクエストの使用量を `request_usage_entries` で自動追跡します。これは、詳細なコスト計算やコンテキストウィンドウ消費の監視に役立ちます。
+SDK は、各 API リクエストの使用量を `request_usage_entries` で自動的に追跡します。これは詳細なコスト計算やコンテキストウィンドウ消費量の監視に役立ちます。
 
 ```python
 result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -53,9 +53,9 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries):
     print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out")
 ```
 
-## セッションでの使用量アクセス
+## セッションでの使用量へのアクセス
 
-`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行の使用量を返します。セッションはコンテキスト用に会話履歴を維持しますが、各実行の使用量は独立しています。
+`Session`（例: `SQLiteSession`）を使用する場合、`Runner.run(...)` の各呼び出しは、その特定の実行の使用量を返します。セッションはコンテキスト用に会話履歴を保持しますが、各実行の使用量は独立しています。
 
 ```python
 session = SQLiteSession("my_conversation")
@@ -67,11 +67,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session)
 print(second.context_wrapper.usage.total_tokens)  # Usage for second run
 ```
 
-セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用量メトリクスは、その特定の実行のみを表す点に注意してください。セッションでは、前のメッセージが各実行の入力として再投入される場合があり、これが後続ターンの入力トークン数に影響します。
+セッションは実行間で会話コンテキストを保持しますが、各 `Runner.run()` 呼び出しで返される使用量メトリクスは、その特定の実行のみを表すことに注意してください。セッションでは、以前のメッセージが各実行の入力として再投入される場合があり、その結果、以降のターンで入力トークン数に影響します。
 
-## フックでの使用量活用
+## フックでの使用量の利用
 
-`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、ライフサイクルの重要なタイミングで使用量をログ記録できます。
+`RunHooks` を使用している場合、各フックに渡される `context` オブジェクトには `usage` が含まれます。これにより、主要なライフサイクルのタイミングで使用量をログに記録できます。
 
 ```python
 class MyHooks(RunHooks):
@@ -82,9 +82,9 @@ class MyHooks(RunHooks):
 
 ## API リファレンス
 
-詳細な API ドキュメントは以下を参照してください。
+詳細な API ドキュメントについては、以下を参照してください。
 
 -   [`Usage`][agents.usage.Usage] - 使用量追跡データ構造
 -   [`RequestUsage`][agents.usage.RequestUsage] - リクエストごとの使用量詳細
 -   [`RunContextWrapper`][agents.run.RunContextWrapper] - 実行コンテキストから使用量にアクセス
--   [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフック
+-   [`RunHooks`][agents.run.RunHooks] - 使用量追跡ライフサイクルへのフックイン

docs/ja/visualization.md

@@ -2,26 +2,26 @@
 search:
   exclude: true
 ---
-# エージェント可視化
+# エージェントの可視化
 
-エージェント可視化では、 **Graphviz** を使用して、エージェントとその関係を構造化されたグラフィカル表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。
+エージェントの可視化では、**Graphviz** を使用して、エージェントとその関係を構造化されたグラフィカルな表現として生成できます。これは、アプリケーション内でエージェント、ツール、ハンドオフがどのように相互作用するかを理解するのに役立ちます。
 
 ## インストール
 
-オプションの `viz` 依存関係グループをインストールします。
+任意の `viz` 依存関係グループをインストールします。
 
 ```bash
 pip install "openai-agents[viz]"
 ```
 
-## グラフ生成
+## グラフの生成
 
-`draw_graph` 関数を使用してエージェント可視化を生成できます。この関数は、以下の構成を持つ有向グラフを作成します。
+`draw_graph` 関数を使用して、エージェントの可視化を生成できます。この関数は、以下のような有向グラフを作成します。
 
-- **エージェント** は黄色のボックスとして表現されます。
-- **MCP サーバー** は灰色のボックスとして表現されます。
-- **ツール** は緑色の楕円として表現されます。
-- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジです。
+- **エージェント** は黄色のボックスで表されます。
+- **MCP サーバー** は灰色のボックスで表されます。
+- **ツール** は緑色の楕円で表されます。
+- **ハンドオフ** は、あるエージェントから別のエージェントへの有向エッジとして表されます。
 
 ### 使用例
 
@@ -67,37 +67,40 @@ triage_agent = Agent(
 draw_graph(triage_agent)
 ```
 
-![Agent Graph](../assets/images/graph.png)
+![エージェントグラフ](../assets/images/graph.png)
+
+これにより、**トリアージエージェント** の構造と、サブエージェントおよびツールとの接続を視覚的に表すグラフが生成されます。
 
-これにより、 **triage agent** の構造と、サブエージェントおよびツールへの接続を視覚的に表すグラフが生成されます。
 
 ## 可視化の理解
 
-生成されるグラフには以下が含まれます。
+生成されるグラフには、以下が含まれます。
 
 - エントリーポイントを示す **開始ノード** (`__start__`)。
-- 黄色で塗りつぶされた **長方形** として表現されるエージェント。
-- 緑色で塗りつぶされた **楕円** として表現されるツール。
-- 灰色で塗りつぶされた **長方形** として表現される MCP サーバー。
+- 黄色で塗りつぶされた **長方形** として表されるエージェント。
+- 緑色で塗りつぶされた **楕円** として表されるツール。
+- 灰色で塗りつぶされた **長方形** として表される MCP サーバー。
 - 相互作用を示す有向エッジ:
-  - エージェント間ハンドオフには **実線矢印**。
-  - ツール呼び出しには **点線矢印**。
-  - MCP サーバー呼び出しには **破線矢印**。
-- 実行が終了する位置を示す **終了ノード** (`__end__`)。
+  - エージェント間のハンドオフを表す **実線矢印**。
+  - ツール呼び出しを表す **点線矢印**。
+  - MCP サーバー呼び出しを表す **破線矢印**。
+- 実行が終了する場所を示す **終了ノード** (`__end__`)。
 
-**注:** MCP サーバーは `agents` パッケージの最近のバージョン ( **v0.2.8** で確認済み ) で描画されます。可視化に MCP ボックスが表示されない場合は、最新リリースにアップグレードしてください。
+**注:** MCP サーバーは、最近のバージョンの
+`agents` パッケージで描画されます（**v0.2.8** で確認済み）。可視化で MCP ボックスが表示されない場合は、
+最新リリースにアップグレードしてください。
 
 ## グラフのカスタマイズ
 
-### グラフ表示
-デフォルトでは、 `draw_graph` はグラフをインライン表示します。グラフを別ウィンドウで表示するには、次のように記述します。
+### グラフの表示
+デフォルトでは、`draw_graph` はグラフをインラインで表示します。グラフを別ウィンドウで表示するには、次のように記述します。
 
 ```python
 draw_graph(triage_agent).view()
 ```
 
-### グラフ保存
-デフォルトでは、 `draw_graph` はグラフをインライン表示します。ファイルとして保存するには、ファイル名を指定します。
+### グラフの保存
+デフォルトでは、`draw_graph` はグラフをインラインで表示します。ファイルとして保存するには、ファイル名を指定します。
 
 ```python
 draw_graph(triage_agent, filename="agent_graph")

docs/ja/voice/pipeline.md

@@ -4,7 +4,7 @@ search:
 ---
 # パイプラインとワークフロー
 
-[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントオーケストレーションを音声アプリに簡単に変換できるクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声終了の検出、適切なタイミングでのワークフロー呼び出し、そしてワークフロー出力の音声への変換を処理します。
+[`VoicePipeline`][agents.voice.pipeline.VoicePipeline] は、エージェントを活用したワークフローを音声アプリに変換しやすくするクラスです。実行するワークフローを渡すと、パイプラインが入力音声の文字起こし、音声の終了検出、適切なタイミングでのワークフロー呼び出し、ワークフローの出力を音声に戻す処理を担います。
 
 ```mermaid
 graph LR
@@ -34,25 +34,25 @@ graph LR
 
 ## パイプラインの設定
 
-パイプラインを作成する際には、いくつかの項目を設定できます。
+パイプラインを作成する際に、いくつかの項目を設定できます。
 
 1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]。新しい音声が文字起こしされるたびに実行されるコードです。
-2. 使用する [`speech-to-text`][agents.voice.model.STTModel] および [`text-to-speech`][agents.voice.model.TTSModel] モデル
-3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。以下のような項目を設定できます。
-    - モデル名をモデルにマッピングできるモデルプロバイダー
-    - トレーシング。トレーシングを無効にするかどうか、音声ファイルをアップロードするかどうか、ワークフロー名、トレース ID などを含みます。
-    - プロンプト、言語、使用するデータ型など、 TTS および STT モデルの設定
+2. 使用する [`speech-to-text`][agents.voice.model.STTModel] モデルと [`text-to-speech`][agents.voice.model.TTSModel] モデル
+3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]。次のような項目を設定できます。
+    - モデル名をモデルに対応付けられるモデルプロバイダー
+    - トレーシング。トレーシングを無効にするか、音声ファイルをアップロードするか、ワークフロー名、トレース ID などを含みます。
+    - TTS モデルと STT モデルの設定。プロンプト、言語、使用するデータ型などです。
 
 ## パイプラインの実行
 
-パイプラインは [`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドで実行でき、音声入力は 2 つの形式で渡せます。
+[`run()`][agents.voice.pipeline.VoicePipeline.run] メソッドを使ってパイプラインを実行できます。このメソッドでは、次の 2 つの形式で音声入力を渡せます。
 
-1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声文字起こしがあり、それに対する結果だけを生成したい場合に使用します。これは、話者が話し終えたタイミングを検出する必要がないケースで有用です。たとえば、事前録音された音声がある場合や、ユーザーが話し終えたことが明確な push-to-talk アプリなどです。
-2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたかどうかを検出する必要がある場合に使用します。検出された音声チャンクを随時プッシュでき、音声パイプラインは "activity detection" と呼ばれるプロセスを通じて、適切なタイミングで自動的にエージェントのワークフローを実行します。
+1. [`AudioInput`][agents.voice.input.AudioInput] は、完全な音声文字起こしがあり、それに対する実行結果だけを生成したい場合に使用します。話者が話し終えたタイミングを検出する必要がない場合に便利です。たとえば、事前録音された音声がある場合や、ユーザーが話し終えたことが明確なプッシュ・トゥ・トークアプリなどです。
+2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] は、ユーザーが話し終えたタイミングを検出する必要がある可能性がある場合に使用します。検出された音声チャンクを送信でき、音声パイプラインは「アクティビティ検出」と呼ばれるプロセスを通じて、適切なタイミングでエージェントワークフローを自動的に実行します。
 
-## 結果
+## 実行結果
 
-音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングできるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] にはいくつかの種類があります。
+音声パイプライン実行の結果は [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult] です。これは、発生したイベントをストリーミングできるオブジェクトです。[`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent] には、次のようないくつかの種類があります。
 
 1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]。音声チャンクを含みます。
 2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]。ターンの開始や終了などのライフサイクルイベントを通知します。
@@ -76,4 +76,4 @@ async for event in result.stream():
 
 ### 割り込み
 
-現在、 Agents SDK は [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み処理を提供していません。代わりに、検出された各ターンごとにワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを処理したい場合は、 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントを監視できます。`turn_started` は、新しいターンが文字起こしされ、処理が開始されることを示します。`turn_ended` は、対応するターンに対するすべての音声が送出された後にトリガーされます。これらのイベントを使用して、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連する音声をすべてフラッシュした後でミュートを解除できます。
+Agents SDK は現在、[`StreamedAudioInput`][agents.voice.input.StreamedAudioInput] に対する組み込みの割り込み処理を提供していません。代わりに、検出された各ターンごとに、ワークフローの個別の実行がトリガーされます。アプリケーション内で割り込みを処理したい場合は、[`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] イベントをリッスンできます。`turn_started` は、新しいターンが文字起こしされ、処理が開始されたことを示します。`turn_ended` は、該当するターンのすべての音声がディスパッチされた後にトリガーされます。これらのイベントを使用して、モデルがターンを開始したときに話者のマイクをミュートし、そのターンに関連するすべての音声をフラッシュした後にミュートを解除できます。

docs/ja/voice/quickstart.md

@@ -6,7 +6,7 @@ search:
 
 ## 前提条件
 
-Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップ済みであることを確認してください。次に、SDK からオプションの音声依存関係をインストールします。
+Agents SDK の基本の [クイックスタート手順](../quickstart.md) に従い、仮想環境をセットアップしていることを確認してください。次に、SDK から任意の音声依存関係をインストールします。
 
 ```bash
 pip install 'openai-agents[voice]'
@@ -16,9 +16,9 @@ pip install 'openai-agents[voice]'
 
 知っておくべき主な概念は [`VoicePipeline`][agents.voice.pipeline.VoicePipeline] です。これは 3 ステップのプロセスです。
 
-1. 音声をテキストに変換するために speech-to-text モデルを実行します。
-2. 結果を生成するために、通常はエージェント型ワークフローであるあなたのコードを実行します。
-3. 結果テキストを音声に戻すために text-to-speech モデルを実行します。
+1. 音声認識モデルを実行して、音声をテキストに変換します。
+2. 通常はエージェント的なワークフローであるコードを実行して、結果を生成します。
+3. テキスト読み上げモデルを実行して、結果のテキストを音声に戻します。
 
 ```mermaid
 graph LR
@@ -48,7 +48,7 @@ graph LR
 
 ## エージェント
 
-まず、いくつかのエージェントを設定しましょう。この SDK でエージェントを構築したことがあれば、おなじみの内容です。いくつかのエージェント、ハンドオフ、ツールを用意します。
+まず、いくつかのエージェントをセットアップしましょう。この SDK でエージェントを構築したことがあれば、なじみのある内容です。ここでは、複数のエージェント、ハンドオフ、ツールを用意します。
 
 ```python
 import asyncio
@@ -92,7 +92,7 @@ agent = Agent(
 
 ## 音声パイプライン
 
-ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用して、シンプルな音声パイプラインを設定します。
+ワークフローとして [`SingleAgentVoiceWorkflow`][agents.voice.workflow.SingleAgentVoiceWorkflow] を使用し、シンプルな音声パイプラインをセットアップします。
 
 ```python
 from agents.voice import SingleAgentVoiceWorkflow, VoicePipeline
@@ -124,7 +124,7 @@ async for event in result.stream():
 
 ```
 
-## すべての統合
+## 全体の統合
 
 ```python
 import asyncio
@@ -195,4 +195,4 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-この例を実行すると、エージェントがあなたに話しかけます！エージェントに自分で話しかけられるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例をご覧ください。
+この例を実行すると、エージェントがあなたに話しかけます！エージェントに自分で話しかけられるデモについては、[examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static) の例を確認してください。

docs/ja/voice/tracing.md

@@ -4,15 +4,15 @@ search:
 ---
 # トレーシング
 
-[エージェントがトレーシングされる](../tracing.md)のと同様に、音声パイプラインも自動的にトレーシングされます。
+[エージェントのトレーシング](../tracing.md)と同様に、音声パイプラインも自動的にトレーシングされます。
 
-基本的なトレーシング情報については上記のトレーシングドキュメントを参照できますが、[`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を介してパイプラインのトレーシングを追加で設定することもできます。
+基本的なトレーシング情報については上記のトレーシングドキュメントを参照できますが、さらに [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig] を通じてパイプラインのトレーシングを設定できます。
 
-トレーシングに関連する主要なフィールドは次のとおりです。
+トレーシングに関連する主なフィールドは次のとおりです。
 
--   [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効化するかどうかを制御します。デフォルトでは、トレーシングは有効です。
--   [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに、音声文字起こしのような潜在的に機微なデータを含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われるものには適用されません。
+-   [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: トレーシングを無効にするかどうかを制御します。デフォルトでは、トレーシングは有効です。
+-   [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: トレースに音声文字起こしなど、潜在的に機微なデータを含めるかどうかを制御します。これは音声パイプライン専用であり、Workflow 内で行われる処理には適用されません。
 -   [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: トレースに音声データを含めるかどうかを制御します。
--   [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレース Workflow の名前です。
--   [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` で、複数のトレースを関連付けられます。
+-   [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: トレースワークフローの名前です。
+-   [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: トレースの `group_id` で、複数のトレースを関連付けることができます。
 -   [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.trace_metadata]: トレースに含める追加のメタデータです。

docs/ko/agents.md

@@ -4,49 +4,49 @@ search:
 ---
 # 에이전트
 
-에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다.
+에이전트는 앱의 핵심 구성 요소입니다. 에이전트는 instructions, tools, 그리고 핸드오프, 가드레일, structured outputs와 같은 선택적 런타임 동작으로 구성된 대규모 언어 모델(LLM)입니다.
 
-단일 일반 `Agent`를 정의하거나 사용자 지정하려는 경우 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 매니페스트로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 안에서 실행되어야 한다면 [샌드박스 에이전트 개념](sandbox/guide.md)을 읽어보세요.
+단일 일반 `Agent`를 정의하거나 사용자 지정하려면 이 페이지를 사용하세요. 여러 에이전트가 어떻게 협업해야 할지 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요. 에이전트가 매니페스트로 정의된 파일과 샌드박스 네이티브 기능을 갖춘 격리된 워크스페이스 안에서 실행되어야 한다면 [샌드박스 에이전트 개념](sandbox/guide.md)을 읽어보세요.
 
-SDK는 OpenAI 모델에 대해 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다. `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 제어하려면 대신 Responses API를 직접 사용하세요.
+SDK는 OpenAI 모델에 기본적으로 Responses API를 사용하지만, 여기서의 차이는 오케스트레이션입니다. `Agent`와 `Runner`를 함께 사용하면 SDK가 턴, 도구, 가드레일, 핸드오프, 세션을 대신 관리합니다. 이 루프를 직접 소유하고 싶다면 대신 Responses API를 직접 사용하세요.
 
 ## 다음 가이드 선택
 
-이 페이지를 에이전트 정의를 위한 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요.
+이 페이지를 에이전트 정의의 허브로 사용하세요. 다음에 내려야 할 결정에 맞는 인접 가이드로 이동하세요.
 
-| 원하는 작업 | 다음 읽을 문서 |
+| 원하는 작업 | 다음 읽을 내용 |
 | --- | --- |
-| 모델 또는 프로바이더 설정 선택 | [모델](models/index.md) |
+| 모델 또는 공급자 설정 선택 | [모델](models/index.md) |
 | 에이전트에 기능 추가 | [도구](tools.md) |
-| 실제 리포지토리, 문서 번들 또는 격리된 워크스페이스에 대해 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) |
-| 매니저 방식 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) |
+| 실제 리포지토리, 문서 번들 또는 격리된 워크스페이스에서 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) |
+| 관리자 방식 오케스트레이션과 핸드오프 중 선택 | [에이전트 오케스트레이션](multi_agent.md) |
 | 핸드오프 동작 구성 | [핸드오프](handoffs.md) |
 | 턴 실행, 이벤트 스트리밍 또는 대화 상태 관리 | [에이전트 실행](running_agents.md) |
-| 최종 출력, 실행 항목 또는 재개 가능한 상태 검사 | [결과](results.md) |
-| 로컬 종속성 및 런타임 상태 공유 | [컨텍스트 관리](context.md) |
+| 최종 출력, 실행 항목 또는 재개 가능 상태 검사 | [결과](results.md) |
+| 로컬 의존성과 런타임 상태 공유 | [컨텍스트 관리](context.md) |
 
-## 기본 구성
+## 기본 설정
 
 에이전트의 가장 일반적인 속성은 다음과 같습니다.
 
 | 속성 | 필수 여부 | 설명 |
 | --- | --- | --- |
-| `name` | 예 | 사람이 읽을 수 있는 에이전트 이름입니다. |
-| `instructions` | 예 | 시스템 프롬프트 또는 동적 instructions 콜백입니다. [동적 instructions](#dynamic-instructions)를 참조하세요. |
+| `name` | 예 | 사람이 읽기 쉬운 에이전트 이름입니다. |
+| `instructions` | 아니요 | 시스템 프롬프트 또는 동적 instructions 콜백입니다. 강력히 권장됩니다. [동적 instructions](#dynamic-instructions)를 참조하세요. |
 | `prompt` | 아니요 | OpenAI Responses API 프롬프트 구성입니다. 정적 프롬프트 객체 또는 함수를 허용합니다. [프롬프트 템플릿](#prompt-templates)을 참조하세요. |
 | `handoff_description` | 아니요 | 이 에이전트가 핸드오프 대상으로 제공될 때 노출되는 짧은 설명입니다. |
-| `handoffs` | 아니요 | 대화를 전문 에이전트에 위임합니다. [핸드오프](handoffs.md)를 참조하세요. |
+| `handoffs` | 아니요 | 대화를 전문 에이전트에게 위임합니다. [핸드오프](handoffs.md)를 참조하세요. |
 | `model` | 아니요 | 사용할 LLM입니다. [모델](models/index.md)을 참조하세요. |
-| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice` 같은 모델 튜닝 매개변수입니다. |
+| `model_settings` | 아니요 | `temperature`, `top_p`, `tool_choice`와 같은 모델 튜닝 매개변수입니다. |
 | `tools` | 아니요 | 에이전트가 호출할 수 있는 도구입니다. [도구](tools.md)를 참조하세요. |
 | `mcp_servers` | 아니요 | 에이전트를 위한 MCP 기반 도구입니다. [MCP 가이드](mcp.md)를 참조하세요. |
-| `mcp_config` | 아니요 | 엄격한 스키마 변환 및 MCP 실패 형식화와 같이 MCP 도구가 준비되는 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration)를 참조하세요. |
-| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 사용자 입력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
-| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에서 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
-| `output_type` | 아니요 | 일반 텍스트 대신 structured outputs 타입입니다. [출력 타입](#output-types)을 참조하세요. |
-| `hooks` | 아니요 | 에이전트 범위의 라이프사이클 콜백입니다. [라이프사이클 이벤트(훅)](#lifecycle-events-hooks)을 참조하세요. |
-| `tool_use_behavior` | 아니요 | 도구 결과가 모델로 다시 전달될지, 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior)을 참조하세요. |
-| `reset_tool_choice` | 아니요 | 도구 사용 루프를 피하기 위해 도구 호출 후 `tool_choice`를 재설정합니다(기본값: `True`). [도구 사용 강제](#forcing-tool-use)를 참조하세요. |
+| `mcp_config` | 아니요 | 엄격한 스키마 변환, MCP 실패 포매팅 등 MCP 도구가 준비되는 방식을 세부 조정합니다. [MCP 가이드](mcp.md#agent-level-mcp-configuration)를 참조하세요. |
+| `input_guardrails` | 아니요 | 이 에이전트 체인의 첫 번째 사용자 입력에 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
+| `output_guardrails` | 아니요 | 이 에이전트의 최종 출력에 실행되는 가드레일입니다. [가드레일](guardrails.md)을 참조하세요. |
+| `output_type` | 아니요 | 일반 텍스트 대신 사용할 구조화된 출력 타입입니다. [출력 타입](#output-types)을 참조하세요. |
+| `hooks` | 아니요 | 에이전트 범위의 수명 주기 콜백입니다. [수명 주기 이벤트(훅)](#lifecycle-events-hooks)을 참조하세요. |
+| `tool_use_behavior` | 아니요 | 도구 결과를 모델로 다시 보낼지, 실행을 종료할지 제어합니다. [도구 사용 동작](#tool-use-behavior)을 참조하세요. |
+| `reset_tool_choice` | 아니요 | 도구 사용 루프를 방지하기 위해 도구 호출 후 `tool_choice`를 재설정합니다(기본값: `True`). [도구 사용 강제](#forcing-tool-use)를 참조하세요. |
 
 ```python
 from agents import Agent, ModelSettings, function_tool
@@ -64,17 +64,17 @@ agent = Agent(
 )
 ```
 
-이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 동일한 아이디어를 기반으로 하며, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [샌드박스 에이전트 개념](sandbox/guide.md)을 참조하세요.
+이 섹션의 모든 내용은 `Agent`에 적용됩니다. `SandboxAgent`는 같은 아이디어를 기반으로 하며, 워크스페이스 범위 실행을 위해 `default_manifest`, `base_instructions`, `capabilities`, `run_as`를 추가합니다. [샌드박스 에이전트 개념](sandbox/guide.md)을 참조하세요.
 
 ## 프롬프트 템플릿
 
-`prompt`를 설정하여 OpenAI 플랫폼에서 생성한 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 작동합니다.
+`prompt`를 설정하여 OpenAI 플랫폼에서 만든 프롬프트 템플릿을 참조할 수 있습니다. 이는 Responses API를 사용하는 OpenAI 모델에서 동작합니다.
 
 사용하려면 다음을 수행하세요.
 
 1. https://platform.openai.com/playground/prompts 로 이동합니다
 2. 새 프롬프트 변수 `poem_style`을 만듭니다.
-3. 다음 내용으로 시스템 프롬프트를 만듭니다.
+3. 다음 콘텐츠로 시스템 프롬프트를 만듭니다.
 
     ```
     Write a poem in {{poem_style}}
@@ -127,9 +127,9 @@ result = await Runner.run(
 
 ## 컨텍스트
 
-에이전트는 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다. 사용자가 생성하여 `Runner.run()`에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되고, 에이전트 실행을 위한 의존성과 상태를 담는 모음 역할을 합니다. 컨텍스트로는 어떤 Python 객체든 제공할 수 있습니다.
+에이전트는 자체 `context` 타입에 대해 제네릭입니다. 컨텍스트는 의존성 주입 도구입니다. 사용자가 만들어 `Runner.run()`에 전달하는 객체이며, 모든 에이전트, 도구, 핸드오프 등에 전달되고 에이전트 실행에 필요한 의존성과 상태를 담는 컨테이너 역할을 합니다. 어떤 Python 객체든 컨텍스트로 제공할 수 있습니다.
 
-전체 `RunContextWrapper` 표면, 공유 사용량 추적, 중첩된 `tool_input`, 직렬화 시 주의 사항은 [컨텍스트 가이드](context.md)를 읽어보세요.
+전체 `RunContextWrapper` 인터페이스, 공유 사용량 추적, 중첩된 `tool_input`, 직렬화 관련 주의 사항은 [컨텍스트 가이드](context.md)를 읽어보세요.
 
 ```python
 @dataclass
@@ -148,7 +148,7 @@ agent = Agent[UserContext](
 
 ## 출력 타입
 
-기본적으로 에이전트는 일반 텍스트(즉 `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 래핑할 수 있는 모든 타입을 지원합니다. dataclasses, lists, TypedDict 등이 포함됩니다.
+기본적으로 에이전트는 일반 텍스트(즉, `str`) 출력을 생성합니다. 에이전트가 특정 타입의 출력을 생성하도록 하려면 `output_type` 매개변수를 사용할 수 있습니다. 일반적인 선택은 [Pydantic](https://docs.pydantic.dev/) 객체를 사용하는 것이지만, Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/)로 감쌀 수 있는 모든 타입(dataclasses, lists, TypedDict 등)을 지원합니다.
 
 ```python
 from pydantic import BaseModel
@@ -169,20 +169,20 @@ agent = Agent(
 
 !!! note
 
-    `output_type`을 전달하면, 이는 모델에 일반 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하라고 지시합니다.
+    `output_type`을 전달하면 모델에 일반적인 일반 텍스트 응답 대신 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용하라고 지시하는 것입니다.
 
 ## 멀티 에이전트 시스템 설계 패턴
 
-멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 폭넓게 적용 가능한 두 가지 패턴을 자주 볼 수 있습니다.
+멀티 에이전트 시스템을 설계하는 방법은 많지만, 일반적으로 널리 적용 가능한 두 가지 패턴을 자주 볼 수 있습니다.
 
-1. 매니저(Agents as tools): 중앙 매니저/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화 제어를 유지합니다.
-2. 핸드오프: 동등한 에이전트가 대화 제어를 이를 이어받는 전문 에이전트에게 넘깁니다. 이는 분산형 방식입니다.
+1. 관리자(agents as tools): 중앙 관리자/오케스트레이터가 전문 하위 에이전트를 도구로 호출하고 대화에 대한 제어를 유지합니다.
+2. 핸드오프: 동등한 에이전트가 대화를 이어받는 전문 에이전트에게 제어를 핸드오프합니다. 이는 분산형 방식입니다.
 
 자세한 내용은 [에이전트 구축을 위한 실용 가이드](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)를 참조하세요.
 
-### 매니저(Agents as tools)
+### 관리자(agents as tools)
 
-`customer_facing_agent`는 모든 사용자 상호작용을 처리하고, 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 읽어보세요.
+`customer_facing_agent`는 사용자와의 모든 상호작용을 처리하고 도구로 노출된 전문 하위 에이전트를 호출합니다. 자세한 내용은 [도구](tools.md#agents-as-tools) 문서를 읽어보세요.
 
 ```python
 from agents import Agent
@@ -232,7 +232,7 @@ triage_agent = Agent(
 
 ## 동적 instructions
 
-대부분의 경우 에이전트를 만들 때 instructions를 제공할 수 있습니다. 그러나 함수를 통해 동적 instructions를 제공할 수도 있습니다. 함수는 에이전트와 컨텍스트를 받으며 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수가 모두 허용됩니다.
+대부분의 경우 에이전트를 만들 때 instructions를 제공할 수 있습니다. 하지만 함수를 통해 동적 instructions를 제공할 수도 있습니다. 이 함수는 에이전트와 컨텍스트를 받고 프롬프트를 반환해야 합니다. 일반 함수와 `async` 함수 모두 허용됩니다.
 
 ```python
 def dynamic_instructions(
@@ -247,29 +247,29 @@ agent = Agent[UserContext](
 )
 ```
 
-## 라이프사이클 이벤트(훅)
+## 수명 주기 이벤트(훅)
 
-때로는 에이전트의 라이프사이클을 관찰하고 싶을 수 있습니다. 예를 들어 특정 이벤트가 발생할 때 이벤트를 로깅하거나, 데이터를 미리 가져오거나, 사용량을 기록할 수 있습니다.
+때로는 에이전트의 수명 주기를 관찰하고 싶을 수 있습니다. 예를 들어 특정 이벤트가 발생할 때 이벤트를 로깅하거나, 데이터를 미리 가져오거나, 사용량을 기록하고 싶을 수 있습니다.
 
-두 가지 훅 범위가 있습니다.
+훅 범위는 두 가지입니다.
 
 -   [`RunHooks`][agents.lifecycle.RunHooks]는 다른 에이전트로의 핸드오프를 포함하여 전체 `Runner.run(...)` 호출을 관찰합니다.
 -   [`AgentHooks`][agents.lifecycle.AgentHooks]는 `agent.hooks`를 통해 특정 에이전트 인스턴스에 연결됩니다.
 
 콜백 컨텍스트도 이벤트에 따라 달라집니다.
 
--   에이전트 시작/종료 훅은 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받으며, 이는 원래 컨텍스트를 래핑하고 공유 실행 사용량 상태를 포함합니다.
+-   에이전트 시작/종료 훅은 원래 컨텍스트를 감싸고 공유 실행 사용량 상태를 전달하는 [`AgentHookContext`][agents.run_context.AgentHookContext]를 받습니다.
 -   LLM, 도구, 핸드오프 훅은 [`RunContextWrapper`][agents.run_context.RunContextWrapper]를 받습니다.
 
 일반적인 훅 타이밍은 다음과 같습니다.
 
--   `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 완료할 때입니다.
--   `on_llm_start` / `on_llm_end`: 각 모델 호출의 바로 전후입니다.
--   `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출의 전후입니다.
-    함수 도구의 경우 훅 `context`는 일반적으로 `ToolContext`이므로 `tool_call_id` 같은 도구 호출 메타데이터를 검사할 수 있습니다.
--   `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때입니다.
+-   `on_agent_start` / `on_agent_end`: 특정 에이전트가 최종 출력을 생성하기 시작하거나 완료할 때
+-   `on_llm_start` / `on_llm_end`: 각 모델 호출 직전과 직후
+-   `on_tool_start` / `on_tool_end`: 각 로컬 도구 호출 전후
+    함수 도구의 경우, 훅 `context`는 일반적으로 `ToolContext`이므로 `tool_call_id`와 같은 도구 호출 메타데이터를 검사할 수 있습니다.
+-   `on_handoff`: 제어가 한 에이전트에서 다른 에이전트로 이동할 때
 
-전체 워크플로를 위한 단일 관찰자가 필요하면 `RunHooks`를 사용하고, 한 에이전트에 사용자 지정 부수 효과가 필요하면 `AgentHooks`를 사용하세요.
+전체 워크플로를 위한 단일 관찰자가 필요할 때는 `RunHooks`를 사용하고, 한 에이전트에 사용자 지정 사이드 이펙트가 필요할 때는 `AgentHooks`를 사용하세요.
 
 ```python
 from agents import Agent, RunHooks, Runner
@@ -291,15 +291,15 @@ result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
 print(result.final_output)
 ```
 
-전체 콜백 표면은 [라이프사이클 API 참조](ref/lifecycle.md)를 참조하세요.
+전체 콜백 인터페이스는 [수명 주기 API 참조](ref/lifecycle.md)를 참조하세요.
 
 ## 가드레일
 
-가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대해 병렬로 검사/검증을 실행하고, 에이전트 출력이 생성된 후 그 출력에 대해서도 검사/검증을 실행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 검사할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 읽어보세요.
+가드레일을 사용하면 에이전트가 실행되는 동안 사용자 입력에 대한 검사/검증을 병렬로 실행하고, 에이전트 출력이 생성된 후 그 출력에 대해서도 검사/검증을 실행할 수 있습니다. 예를 들어 사용자 입력과 에이전트 출력의 관련성을 선별할 수 있습니다. 자세한 내용은 [가드레일](guardrails.md) 문서를 읽어보세요.
 
 ## 에이전트 복제/복사
 
-에이전트의 `clone()` 메서드를 사용하면 Agent를 복제하고, 원하는 속성을 선택적으로 변경할 수 있습니다.
+에이전트에서 `clone()` 메서드를 사용하면 에이전트를 복제하고, 선택적으로 원하는 속성을 변경할 수 있습니다.
 
 ```python
 pirate_agent = Agent(
@@ -318,12 +318,12 @@ robot_agent = pirate_agent.clone(
 
 도구 목록을 제공한다고 해서 LLM이 항상 도구를 사용하는 것은 아닙니다. [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice]를 설정하여 도구 사용을 강제할 수 있습니다. 유효한 값은 다음과 같습니다.
 
-1. `auto`: LLM이 도구 사용 여부를 결정할 수 있게 합니다.
-2. `required`: LLM이 도구를 사용해야 합니다(하지만 어떤 도구를 사용할지는 지능적으로 결정할 수 있습니다).
+1. `auto`: LLM이 도구 사용 여부를 결정하도록 허용합니다.
+2. `required`: LLM이 도구를 사용하도록 요구합니다(하지만 어떤 도구를 사용할지는 지능적으로 결정할 수 있습니다).
 3. `none`: LLM이 도구를 _사용하지 않도록_ 요구합니다.
-4. 특정 문자열(예: `my_tool`)을 설정하면 LLM이 해당 특정 도구를 사용해야 합니다.
+4. 특정 문자열(예: `my_tool`)을 설정하면 LLM이 해당 특정 도구를 사용하도록 요구합니다.
 
-OpenAI Responses 도구 검색을 사용하는 경우 명명된 도구 선택은 더 제한됩니다. `tool_choice`로 단순 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없으며, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 지정하지 않습니다. 이러한 경우에는 `auto` 또는 `required`를 선호하세요. Responses 관련 제약 조건은 [호스티드 도구 검색](tools.md#hosted-tool-search)을 참조하세요.
+OpenAI Responses 도구 검색을 사용하는 경우, 이름이 지정된 도구 선택은 더 제한됩니다. `tool_choice`로 순수 네임스페이스 이름이나 deferred 전용 도구를 대상으로 지정할 수 없으며, `tool_choice="tool_search"`는 [`ToolSearchTool`][agents.tool.ToolSearchTool]을 대상으로 하지 않습니다. 이러한 경우 `auto` 또는 `required`를 권장합니다. Responses 고유의 제약 사항은 [호스티드 툴 검색](tools.md#hosted-tool-search)을 참조하세요.
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -346,7 +346,7 @@ agent = Agent(
 `Agent` 구성의 `tool_use_behavior` 매개변수는 도구 출력이 처리되는 방식을 제어합니다.
 
 - `"run_llm_again"`: 기본값입니다. 도구가 실행되고, LLM이 결과를 처리하여 최종 응답을 생성합니다.
-- `"stop_on_first_tool"`: 첫 번째 도구 호출의 출력이 추가 LLM 처리 없이 최종 응답으로 사용됩니다.
+- `"stop_on_first_tool"`: 추가 LLM 처리 없이 첫 번째 도구 호출의 출력이 최종 응답으로 사용됩니다.
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -364,7 +364,7 @@ agent = Agent(
 )
 ```
 
-- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고, 그 출력을 최종 응답으로 사용합니다.
+- `StopAtTools(stop_at_tool_names=[...])`: 지정된 도구 중 하나라도 호출되면 중지하고, 해당 출력을 최종 응답으로 사용합니다.
 
 ```python
 from agents import Agent, Runner, function_tool
@@ -426,4 +426,4 @@ agent = Agent(
 
 !!! note
 
-    무한 루프를 방지하기 위해, 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]를 통해 구성할 수 있습니다. 무한 루프가 발생하는 이유는 도구 결과가 LLM으로 전송되고, 그러면 LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 일이 무한히 반복되기 때문입니다.
+    무한 루프를 방지하기 위해 프레임워크는 도구 호출 후 `tool_choice`를 자동으로 "auto"로 재설정합니다. 이 동작은 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]를 통해 구성할 수 있습니다. 무한 루프가 발생하는 이유는 도구 결과가 LLM으로 전송되고, LLM이 `tool_choice` 때문에 또 다른 도구 호출을 생성하는 과정이 끝없이 반복되기 때문입니다.

docs/ko/config.md

@@ -4,21 +4,21 @@ search:
 ---
 # 구성
 
-이 페이지에서는 기본 OpenAI 키 또는 클라이언트, 기본 OpenAI API 형태, 트레이싱 내보내기 기본값, 로깅 동작처럼 보통 애플리케이션 시작 시 한 번 설정하는 SDK 전역 기본값을 다룹니다
+이 페이지에서는 기본 OpenAI 키 또는 클라이언트, 기본 OpenAI API 형태, 트레이싱 내보내기 기본값, 로깅 동작처럼 일반적으로 애플리케이션 시작 시 한 번 설정하는 SDK 전체 기본값을 다룹니다.
 
-이러한 기본값은 샌드박스 기반 워크플로에도 계속 적용되지만, 샌드박스 워크스페이스, 샌드박스 클라이언트, 세션 재사용은 별도로 구성합니다
+이러한 기본값은 샌드박스 기반 워크플로에도 계속 적용되지만, 샌드박스 워크스페이스, 샌드박스 클라이언트, 세션 재사용은 별도로 구성합니다.
 
-대신 특정 에이전트 또는 실행을 구성해야 한다면, 다음부터 시작하세요:
+대신 특정 에이전트 또는 실행을 구성해야 한다면 다음부터 시작하세요.
 
--   일반 `Agent`의 instructions, tools, 출력 타입, 핸드오프, 가드레일은 [Agents](agents.md)
+-   일반 `Agent`의 instructions, tools, 출력 유형, 핸드오프, 가드레일은 [에이전트](agents.md)
 -   `RunConfig`, 세션, 대화 상태 옵션은 [에이전트 실행](running_agents.md)
--   `SandboxRunConfig`, 매니페스트, 기능, 샌드박스 클라이언트 전용 워크스페이스 설정은 [샌드박스 에이전트](sandbox/guide.md)
--   모델 선택 및 프로바이더 구성은 [모델](models/index.md)
--   실행별 트레이싱 메타데이터와 사용자 지정 트레이스 프로세서는 [트레이싱](tracing.md)
+-   `SandboxRunConfig`, 매니페스트, 기능, 샌드박스 클라이언트별 워크스페이스 설정은 [샌드박스 에이전트](sandbox/guide.md)
+-   모델 선택 및 공급자 구성은 [모델](models/index.md)
+-   실행별 트레이싱 메타데이터 및 사용자 지정 트레이스 프로세서는 [트레이싱](tracing.md)
 
-## API 키와 클라이언트
+## API 키 및 클라이언트
 
-기본적으로 SDK는 LLM 요청과 트레이싱에 `OPENAI_API_KEY` 환경 변수를 사용합니다. 이 키는 SDK가 처음 OpenAI 클라이언트를 생성할 때(지연 초기화) 확인되므로, 첫 모델 호출 전에 환경 변수를 설정하세요. 앱 시작 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다.
+기본적으로 SDK는 LLM 요청과 트레이싱에 `OPENAI_API_KEY` 환경 변수를 사용합니다. 키는 SDK가 처음 OpenAI 클라이언트를 생성할 때 확인되므로(지연 초기화), 첫 모델 호출 전에 환경 변수를 설정하세요. 앱이 시작되기 전에 해당 환경 변수를 설정할 수 없다면 [set_default_openai_key()][agents.set_default_openai_key] 함수를 사용해 키를 설정할 수 있습니다.
 
 ```python
 from agents import set_default_openai_key
@@ -26,7 +26,7 @@ from agents import set_default_openai_key
 set_default_openai_key("sk-...")
 ```
 
-또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용해 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다.
+또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용하여 `AsyncOpenAI` 인스턴스를 생성합니다. [set_default_openai_client()][agents.set_default_openai_client] 함수를 사용해 이를 변경할 수 있습니다.
 
 ```python
 from openai import AsyncOpenAI
@@ -36,14 +36,14 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
 set_default_openai_client(custom_client)
 ```
 
-환경 기반 엔드포인트 구성을 선호한다면, 기본 OpenAI 프로바이더는 `OPENAI_BASE_URL`도 읽습니다. Responses websocket 전송을 활성화하면 websocket `/responses` 엔드포인트에 `OPENAI_WEBSOCKET_BASE_URL`도 읽습니다.
+환경 기반 엔드포인트 구성을 선호한다면 기본 OpenAI 공급자는 `OPENAI_BASE_URL`도 읽습니다. Responses 웹소켓 전송을 활성화하면 웹소켓 `/responses` 엔드포인트에 대해 `OPENAI_WEBSOCKET_BASE_URL`도 읽습니다.
 
 ```bash
 export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1"
 export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1"
 ```
 
-마지막으로, 사용되는 OpenAI API를 사용자 지정할 수도 있습니다. 기본적으로는 OpenAI Responses API를 사용합니다. [set_default_openai_api()][agents.set_default_openai_api] 함수를 사용하면 이를 재정의해 Chat Completions API를 사용할 수 있습니다.
+마지막으로 사용되는 OpenAI API도 사용자 지정할 수 있습니다. 기본적으로 OpenAI Responses API를 사용합니다. [set_default_openai_api()][agents.set_default_openai_api] 함수를 사용해 Chat Completions API를 사용하도록 재정의할 수 있습니다.
 
 ```python
 from agents import set_default_openai_api
@@ -53,7 +53,7 @@ set_default_openai_api("chat_completions")
 
 ## 트레이싱
 
-트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 모델 요청과 동일한 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용해 트레이싱에 사용할 API 키를 별도로 설정할 수 있습니다.
+트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 모델 요청과 동일한 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 함수를 사용해 트레이싱에 사용되는 API 키를 별도로 설정할 수 있습니다.
 
 ```python
 from agents import set_tracing_export_api_key
@@ -61,7 +61,7 @@ from agents import set_tracing_export_api_key
 set_tracing_export_api_key("sk-...")
 ```
 
-모델 트래픽은 하나의 키 또는 클라이언트를 사용하지만 트레이싱은 다른 OpenAI 키를 사용해야 한다면, 기본 키 또는 클라이언트를 설정할 때 `use_for_tracing=False`를 전달한 다음 트레이싱을 별도로 구성하세요. 사용자 지정 클라이언트를 사용하지 않는 경우 [`set_default_openai_key()`][agents.set_default_openai_key]에도 같은 패턴을 적용할 수 있습니다.
+모델 트래픽은 하나의 키 또는 클라이언트를 사용하지만 트레이싱에는 다른 OpenAI 키를 사용해야 한다면, 기본 키 또는 클라이언트를 설정할 때 `use_for_tracing=False`를 전달한 다음 트레이싱을 별도로 구성하세요. 사용자 지정 클라이언트를 사용하지 않는 경우에도 [`set_default_openai_key()`][agents.set_default_openai_key]로 동일한 패턴을 사용할 수 있습니다.
 
 ```python
 from openai import AsyncOpenAI
@@ -76,7 +76,7 @@ set_default_openai_client(custom_client, use_for_tracing=False)
 set_tracing_export_api_key("sk-tracing")
 ```
 
-기본 내보내기를 사용할 때 트레이스를 특정 조직 또는 프로젝트에 귀속해야 한다면, 앱 시작 전에 다음 환경 변수를 설정하세요:
+기본 내보내기를 사용할 때 트레이스를 특정 조직 또는 프로젝트에 귀속해야 한다면 앱이 시작되기 전에 다음 환경 변수를 설정하세요.
 
 ```bash
 export OPENAI_ORG_ID="org_..."
@@ -103,7 +103,7 @@ from agents import set_tracing_disabled
 set_tracing_disabled(True)
 ```
 
-트레이싱은 활성화한 채로 유지하되 트레이스 페이로드에서 잠재적으로 민감한 입력/출력을 제외하려면 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 `False`로 설정하세요:
+트레이싱은 활성화한 상태로 유지하되 트레이스 페이로드에서 민감할 수 있는 입력/출력을 제외하려면 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 `False`로 설정하세요.
 
 ```python
 from agents import Runner, RunConfig
@@ -115,19 +115,19 @@ await Runner.run(
 )
 ```
 
-코드 없이 기본값을 변경하려면 앱 시작 전에 이 환경 변수를 설정할 수도 있습니다:
+앱이 시작되기 전에 다음 환경 변수를 설정하여 코드 없이 기본값을 변경할 수도 있습니다.
 
 ```bash
 export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0
 ```
 
-전체 트레이싱 제어는 [트레이싱 가이드](tracing.md)를 참고하세요.
+전체 트레이싱 제어는 [트레이싱 가이드](tracing.md)를 참조하세요.
 
 ## 디버그 로깅
 
-SDK는 두 개의 Python 로거(`openai.agents` 및 `openai.agents.tracing`)를 정의하며 기본적으로 핸들러를 연결하지 않습니다. 로그는 애플리케이션의 Python 로깅 구성 설정을 따릅니다.
+SDK는 두 개의 Python 로거(`openai.agents` 및 `openai.agents.tracing`)를 정의하며 기본적으로 핸들러를 연결하지 않습니다. 로그는 애플리케이션의 Python 로깅 구성을 따릅니다.
 
-상세 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요.
+자세한 로깅을 활성화하려면 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 함수를 사용하세요.
 
 ```python
 from agents import enable_verbose_stdout_logging
@@ -135,7 +135,7 @@ from agents import enable_verbose_stdout_logging
 enable_verbose_stdout_logging()
 ```
 
-또는 핸들러, 필터, 포매터 등을 추가해 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요.
+또는 핸들러, 필터, 포매터 등을 추가하여 로그를 사용자 지정할 수 있습니다. 자세한 내용은 [Python 로깅 가이드](https://docs.python.org/3/howto/logging.html)를 참고하세요.
 
 ```python
 import logging
@@ -156,16 +156,16 @@ logger.addHandler(logging.StreamHandler())
 
 ### 로그의 민감한 데이터
 
-일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다.
+특정 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다.
 
-기본적으로 SDK는 LLM 입력/출력이나 도구 입력/출력을 로깅하지 **않습니다**. 이러한 보호는 다음으로 제어됩니다:
+기본적으로 SDK는 LLM 입력/출력 또는 도구 입력/출력을 로깅하지 **않습니다**. 이러한 보호는 다음으로 제어됩니다.
 
 ```bash
 OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
 OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
 ```
 
-디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱 시작 전에 변수 중 하나를 `0`(또는 `false`)으로 설정하세요:
+디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱이 시작되기 전에 두 변수 중 하나를 `0`(또는 `false`)으로 설정하세요.
 
 ```bash
 export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0

docs/ko/context.md

@@ -4,49 +4,49 @@ search:
 ---
 # 컨텍스트 관리
 
-컨텍스트는 중의적으로 사용되는 용어입니다. 보통 신경 써야 할 컨텍스트는 두 가지 주요 범주가 있습니다
+컨텍스트는 여러 의미로 쓰이는 용어입니다. 주로 고려해야 할 컨텍스트에는 두 가지 주요 유형이 있습니다.
 
-1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수 실행 시, `on_handoff` 같은 콜백, 라이프사이클 훅 등에서 필요할 수 있는 데이터와 의존성입니다
-2. LLM에서 사용할 수 있는 컨텍스트: LLM이 응답을 생성할 때 보는 데이터입니다
+1. 코드에서 로컬로 사용할 수 있는 컨텍스트: 도구 함수가 실행될 때, `on_handoff` 같은 콜백 중에, 생명주기 훅 등에서 필요할 수 있는 데이터와 의존성입니다.
+2. LLM이 사용할 수 있는 컨텍스트: LLM이 응답을 생성할 때 보는 데이터입니다.
 
 ## 로컬 컨텍스트
 
-이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 동작 방식은 다음과 같습니다
+이는 [`RunContextWrapper`][agents.run_context.RunContextWrapper] 클래스와 그 안의 [`context`][agents.run_context.RunContextWrapper.context] 속성으로 표현됩니다. 작동 방식은 다음과 같습니다.
 
-1. 원하는 Python 객체를 생성합니다. 일반적으로 dataclass 또는 Pydantic 객체를 사용합니다
-2. 해당 객체를 다양한 run 메서드에 전달합니다(예: `Runner.run(..., context=whatever)`)
-3. 모든 도구 호출, 라이프사이클 훅 등은 `RunContextWrapper[T]` 래퍼 객체를 전달받으며, 여기서 `T`는 `wrapper.context`로 접근 가능한 컨텍스트 객체 타입입니다
+1. 원하는 Python 객체를 만듭니다. 일반적인 패턴은 dataclass나 Pydantic 객체를 사용하는 것입니다.
+2. 해당 객체를 다양한 run 메서드에 전달합니다(예: `Runner.run(..., context=whatever)`).
+3. 모든 도구 호출, 생명주기 훅 등에는 래퍼 객체인 `RunContextWrapper[T]`가 전달되며, 여기서 `T`는 `wrapper.context`를 통해 접근할 수 있는 컨텍스트 객체 타입을 나타냅니다.
 
-일부 런타임 전용 콜백에서는 SDK가 `RunContextWrapper[T]`의 더 특화된 하위 클래스를 전달할 수 있습니다. 예를 들어, 함수 도구 라이프사이클 훅은 보통 `ToolContext`를 받으며, 이는 `tool_call_id`, `tool_name`, `tool_arguments` 같은 도구 호출 메타데이터도 제공합니다
+일부 런타임별 콜백의 경우 SDK가 `RunContextWrapper[T]`의 더 특화된 서브클래스를 전달할 수 있습니다. 예를 들어 함수 도구 생명주기 훅은 일반적으로 `ToolContext`를 받으며, 이는 `tool_call_id`, `tool_name`, `tool_arguments` 같은 도구 호출 메타데이터도 노출합니다.
 
-가장 **중요한** 점은 다음과 같습니다: 특정 에이전트 실행에서 모든 에이전트, 도구 함수, 라이프사이클 등은 동일한 컨텍스트 _타입_ 을 사용해야 합니다
+알아두어야 할 **가장 중요한** 점은 특정 에이전트 실행에 포함되는 모든 에이전트, 도구 함수, 생명주기 등은 동일한 컨텍스트 _타입_을 사용해야 한다는 것입니다.
 
-컨텍스트는 다음과 같은 용도로 사용할 수 있습니다
+컨텍스트는 다음과 같은 용도로 사용할 수 있습니다.
 
-- 실행에 대한 맥락 데이터(예: 사용자 이름/uid 또는 사용자에 관한 기타 정보)
-- 의존성(예: logger 객체, 데이터 fetcher 등)
-- 헬퍼 함수
+-   실행을 위한 컨텍스트 데이터(예: 사용자 이름/uid 또는 사용자에 대한 기타 정보)
+-   의존성(예: 로거 객체, 데이터 페처 등)
+-   헬퍼 함수
 
 !!! danger "참고"
 
-    컨텍스트 객체는 LLM으로 전송되지 **않습니다**. 이는 순수하게 로컬 객체이며, 읽고 쓰고 메서드를 호출할 수 있습니다
+    컨텍스트 객체는 LLM으로 전송되지 **않습니다**. 이는 오직 로컬 객체이며, 읽고 쓰거나 해당 객체의 메서드를 호출할 수 있습니다.
 
-단일 run 내에서 파생 래퍼는 동일한 기본 앱 컨텍스트, 승인 상태, 사용량 추적을 공유합니다. 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] run은 다른 `tool_input`을 연결할 수 있지만, 기본적으로 앱 상태의 격리된 복사본을 받지는 않습니다
+단일 실행 내에서 파생된 래퍼들은 동일한 기본 앱 컨텍스트, 승인 상태, 사용량 추적을 공유합니다. 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행은 다른 `tool_input`을 붙일 수 있지만, 기본적으로 앱 상태의 격리된 복사본을 받지는 않습니다.
 
-### `RunContextWrapper` 노출 항목
+### `RunContextWrapper`의 노출 항목
 
-[`RunContextWrapper`][agents.run_context.RunContextWrapper]는 앱에서 정의한 컨텍스트 객체를 감싸는 래퍼입니다. 실제로는 주로 다음을 사용합니다
+[`RunContextWrapper`][agents.run_context.RunContextWrapper]는 앱에서 정의한 컨텍스트 객체를 감싸는 래퍼입니다. 실제로는 대부분 다음을 사용하게 됩니다.
 
-- 자체 변경 가능한 앱 상태와 의존성을 위한 [`wrapper.context`][agents.run_context.RunContextWrapper.context]
-- 현재 run 전체의 요청/토큰 사용량 집계를 위한 [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]
-- 현재 run이 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 내부에서 실행 중일 때 구조화된 입력을 위한 [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]
-- 승인 상태를 프로그래밍 방식으로 업데이트해야 할 때 [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]
+-   [`wrapper.context`][agents.run_context.RunContextWrapper.context]: 직접 사용하는 변경 가능한 앱 상태와 의존성
+-   [`wrapper.usage`][agents.run_context.RunContextWrapper.usage]: 현재 실행 전반의 집계된 요청 및 토큰 사용량
+-   [`wrapper.tool_input`][agents.run_context.RunContextWrapper.tool_input]: 현재 실행이 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 안에서 실행 중일 때의 구조화된 입력
+-   [`wrapper.approve_tool(...)`][agents.run_context.RunContextWrapper.approve_tool] / [`wrapper.reject_tool(...)`][agents.run_context.RunContextWrapper.reject_tool]: 승인 상태를 프로그래밍 방식으로 업데이트해야 할 때 사용
 
-`wrapper.context`만 앱에서 정의한 객체입니다. 나머지 필드는 SDK가 관리하는 런타임 메타데이터입니다
+`wrapper.context`만 앱에서 정의한 객체입니다. 다른 필드는 SDK가 관리하는 런타임 메타데이터입니다.
 
-나중에 휴먼인더루프 (HITL) 또는 내구성 있는 작업 워크플로를 위해 [`RunState`][agents.run_state.RunState]를 직렬화하면, 해당 런타임 메타데이터도 상태와 함께 저장됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 비밀 정보를 넣지 마세요
+나중에 휴먼인더루프 (HITL) 또는 내구성 있는 작업 워크플로를 위해 [`RunState`][agents.run_state.RunState]를 직렬화하면, 해당 런타임 메타데이터가 상태와 함께 저장됩니다. 직렬화된 상태를 영속화하거나 전송할 계획이라면 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 비밀 정보를 넣지 마세요.
 
-대화 상태는 별도의 관심사입니다. 턴을 어떻게 이어갈지에 따라 `result.to_input_list()`, `session`, `conversation_id`, 또는 `previous_response_id`를 사용하세요. 이 결정은 [결과](results.md), [에이전트 실행](running_agents.md), [세션](sessions/index.md)을 참고하세요
+대화 상태는 별개의 문제입니다. 턴을 이어가는 방식에 따라 `result.to_input_list()`, `session`, `conversation_id`, 또는 `previous_response_id`를 사용하세요. 이 결정에 대해서는 [결과](results.md), [에이전트 실행](running_agents.md), [세션](sessions/index.md)을 참고하세요.
 
 ```python
 import asyncio
@@ -85,18 +85,18 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만 어떤 타입이든 사용할 수 있습니다
-2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 값을 읽습니다
-3. 타입 체커가 오류를 잡을 수 있도록(예: 다른 컨텍스트 타입을 받는 도구를 전달하려는 경우) 에이전트에 제네릭 `UserInfo`를 표시합니다
-4. 컨텍스트는 `run` 함수에 전달됩니다
-5. 에이전트가 도구를 올바르게 호출하고 나이를 가져옵니다
+1. 이것이 컨텍스트 객체입니다. 여기서는 dataclass를 사용했지만, 어떤 타입이든 사용할 수 있습니다.
+2. 이것은 도구입니다. `RunContextWrapper[UserInfo]`를 받는 것을 볼 수 있습니다. 도구 구현은 컨텍스트에서 읽습니다.
+3. 에이전트에 제네릭 `UserInfo`를 표시하여, 타입 검사기가 오류를 잡을 수 있도록 합니다(예를 들어 다른 컨텍스트 타입을 받는 도구를 전달하려고 한 경우).
+4. 컨텍스트가 `run` 함수에 전달됩니다.
+5. 에이전트가 도구를 올바르게 호출하고 나이를 가져옵니다.
 
 ---
 
 ### 고급: `ToolContext`
 
-경우에 따라 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원시 인자 문자열)에 접근하고 싶을 수 있습니다  
-이때는 `RunContextWrapper`를 확장한 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다
+어떤 경우에는 실행 중인 도구에 대한 추가 메타데이터(예: 이름, 호출 ID, 원문 인수 문자열)에 접근하고 싶을 수 있습니다.  
+이를 위해 `RunContextWrapper`를 확장하는 [`ToolContext`][agents.tool_context.ToolContext] 클래스를 사용할 수 있습니다.
 
 ```python
 from typing import Annotated
@@ -124,25 +124,25 @@ agent = Agent(
 )
 ```
 
-`ToolContext`는 `RunContextWrapper`와 동일한 `.context` 속성을 제공하며  
-현재 도구 호출에 특화된 추가 필드도 제공합니다
+`ToolContext`는 `RunContextWrapper`와 동일한 `.context` 속성을 제공하며,  
+현재 도구 호출에 특화된 추가 필드도 제공합니다.
 
 - `tool_name` – 호출되는 도구의 이름  
 - `tool_call_id` – 이 도구 호출의 고유 식별자  
-- `tool_arguments` – 도구에 전달된 원시 인자 문자열  
-- `tool_namespace` – 도구가 `tool_namespace()` 또는 다른 네임스페이스 표면을 통해 로드된 경우, 도구 호출의 Responses 네임스페이스  
-- `qualified_tool_name` – 네임스페이스가 있을 때 네임스페이스가 포함된 도구 이름  
+- `tool_arguments` – 도구에 전달된 원문 인수 문자열  
+- `tool_namespace` – 도구가 `tool_namespace()` 또는 다른 네임스페이스가 지정된 표면을 통해 로드된 경우, 도구 호출의 Responses 네임스페이스  
+- `qualified_tool_name` – 네임스페이스가 있을 때 해당 네임스페이스로 한정된 도구 이름  
 
-실행 중 도구 수준 메타데이터가 필요할 때 `ToolContext`를 사용하세요  
-에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper`로 충분합니다. `ToolContext`는 `RunContextWrapper`를 확장하므로, 중첩된 `Agent.as_tool()` run이 구조화된 입력을 제공한 경우 `.tool_input`도 노출할 수 있습니다
+실행 중에 도구 수준 메타데이터가 필요할 때 `ToolContext`를 사용하세요.  
+에이전트와 도구 간의 일반적인 컨텍스트 공유에는 `RunContextWrapper`로 충분합니다. `ToolContext`는 `RunContextWrapper`를 확장하므로, 중첩된 `Agent.as_tool()` 실행이 구조화된 입력을 제공한 경우 `.tool_input`도 노출할 수 있습니다.
 
 ---
 
 ## 에이전트/LLM 컨텍스트
 
-LLM이 호출될 때 LLM이 볼 수 있는 데이터는 대화 기록뿐입니다. 즉, LLM에서 새로운 데이터를 사용할 수 있게 하려면 해당 기록에서 접근 가능하도록 만들어야 합니다. 방법은 몇 가지가 있습니다
+LLM이 호출될 때 LLM이 볼 수 있는 **유일한** 데이터는 대화 기록에 있는 데이터입니다. 즉, LLM이 어떤 새 데이터를 사용할 수 있게 하려면 해당 기록에서 사용할 수 있는 방식으로 제공해야 합니다. 이를 수행하는 방법은 몇 가지가 있습니다.
 
-1. Agent `instructions`에 추가할 수 있습니다. 이는 "시스템 프롬프트" 또는 "개발자 메시지"라고도 합니다. 시스템 프롬프트는 정적 문자열일 수도 있고, 컨텍스트를 받아 문자열을 출력하는 동적 함수일 수도 있습니다. 이는 항상 유용한 정보(예: 사용자 이름 또는 현재 날짜)에 자주 쓰이는 방법입니다
-2. `Runner.run` 함수를 호출할 때 `input`에 추가합니다. 이는 `instructions` 방식과 유사하지만, [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 우선순위의 메시지를 둘 수 있게 해줍니다
-3. 함수 도구를 통해 노출합니다. 이는 _온디맨드_ 컨텍스트에 유용합니다. LLM이 어떤 데이터가 필요할 때를 스스로 결정하고, 그 데이터를 가져오기 위해 도구를 호출할 수 있습니다
-4. retrieval 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스(retrieval), 또는 웹(웹 검색)에서 관련 데이터를 가져올 수 있는 특수 도구입니다. 이는 관련 컨텍스트 데이터에 응답을 "grounding"하는 데 유용합니다
+1. Agent `instructions`에 추가할 수 있습니다. 이는 "시스템 프롬프트" 또는 "개발자 메시지"라고도 합니다. 시스템 프롬프트는 정적 문자열일 수도 있고, 컨텍스트를 받아 문자열을 출력하는 동적 함수일 수도 있습니다. 이는 항상 유용한 정보(예: 사용자의 이름 또는 현재 날짜)에 흔히 사용하는 전략입니다.
+2. `Runner.run` 함수를 호출할 때 `input`에 추가합니다. 이는 `instructions` 전략과 유사하지만, [명령 체계](https://cdn.openai.com/spec/model-spec-2024-05-08.html#follow-the-chain-of-command)에서 더 낮은 위치의 메시지를 사용할 수 있게 해줍니다.
+3. 함수 도구를 통해 노출합니다. 이는 _온디맨드_ 컨텍스트에 유용합니다. LLM이 어떤 데이터가 필요한 시점을 결정하고, 해당 데이터를 가져오기 위해 도구를 호출할 수 있습니다.
+4. 검색 또는 웹 검색을 사용합니다. 이는 파일이나 데이터베이스에서 관련 데이터를 가져올 수 있는 특수 도구(검색) 또는 웹에서 가져올 수 있는 특수 도구(웹 검색)입니다. 이는 응답을 관련 컨텍스트 데이터에 "근거화"하는 데 유용합니다.

docs/ko/examples.md

@@ -2,74 +2,74 @@
 search:
   exclude: true
 ---
-# 코드 예제
+# 예제
 
-[repo](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 SDK의 다양한 샘플 구현을 확인해 보세요. examples는 서로 다른 패턴과 기능을 보여주는 여러 카테고리로 구성되어 있습니다.
+SDK의 다양한 샘플 구현은 [리포지토리](https://github.com/openai/openai-agents-python/tree/main/examples)의 examples 섹션에서 확인하세요. 예제는 여러 카테고리로 구성되어 있으며, 각기 다른 패턴과 기능을 보여 줍니다.
 
 ## 카테고리
 
 -   **[agent_patterns](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns):**
-    이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여줍니다
+    이 카테고리의 예제는 다음과 같은 일반적인 에이전트 설계 패턴을 보여 줍니다
 
     -   결정론적 워크플로
     -   Agents as tools
-    -   스트리밍 이벤트를 포함한 Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`)
-    -   구조화된 입력 매개변수를 포함한 Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`)
+    -   스트리밍 이벤트를 사용하는 Agents as tools (`examples/agent_patterns/agents_as_tools_streaming.py`)
+    -   구조화된 입력 매개변수를 사용하는 Agents as tools (`examples/agent_patterns/agents_as_tools_structured.py`)
     -   병렬 에이전트 실행
     -   조건부 도구 사용
-    -   서로 다른 동작으로 도구 사용 강제 (`examples/agent_patterns/forcing_tool_use.py`)
+    -   다양한 동작으로 도구 사용 강제 (`examples/agent_patterns/forcing_tool_use.py`)
     -   입출력 가드레일
-    -   심판 역할의 LLM
+    -   평가자로서의 LLM
     -   라우팅
     -   스트리밍 가드레일
     -   도구 승인 및 상태 직렬화를 포함한 휴먼인더루프 (HITL) (`examples/agent_patterns/human_in_the_loop.py`)
     -   스트리밍을 포함한 휴먼인더루프 (HITL) (`examples/agent_patterns/human_in_the_loop_stream.py`)
-    -   승인 플로를 위한 사용자 지정 거절 메시지 (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`)
+    -   승인 흐름을 위한 사용자 지정 거부 메시지 (`examples/agent_patterns/human_in_the_loop_custom_rejection.py`)
 
 -   **[basic](https://github.com/openai/openai-agents-python/tree/main/examples/basic):**
-    이 예제들은 다음과 같은 SDK의 기본 기능을 보여줍니다
+    이 예제는 다음과 같은 SDK의 기본 기능을 보여 줍니다
 
-    -   Hello World 예제 (기본 모델, GPT-5, 오픈 웨이트 모델)
-    -   에이전트 라이프사이클 관리
-    -   실행 훅 및 에이전트 훅 라이프사이클 예제 (`examples/basic/lifecycle_example.py`)
+    -   Hello world 예제(기본 모델, GPT-5, open-weight 모델)
+    -   에이전트 수명 주기 관리
+    -   실행 훅 및 에이전트 훅 수명 주기 예제 (`examples/basic/lifecycle_example.py`)
     -   동적 시스템 프롬프트
     -   기본 도구 사용 (`examples/basic/tools.py`)
     -   도구 입출력 가드레일 (`examples/basic/tool_guardrails.py`)
     -   이미지 도구 출력 (`examples/basic/image_tool_output.py`)
-    -   스트리밍 출력 (텍스트, 항목, 함수 호출 인자)
+    -   스트리밍 출력(텍스트, 항목, 함수 호출 인수)
     -   턴 간 공유 세션 헬퍼를 사용하는 Responses websocket 전송 (`examples/basic/stream_ws.py`)
     -   프롬프트 템플릿
-    -   파일 처리 (로컬 및 원격, 이미지 및 PDF)
+    -   파일 처리(로컬 및 원격, 이미지 및 PDF)
     -   사용량 추적
-    -   Runner 관리 재시도 설정 (`examples/basic/retry.py`)
-    -   서드파티 어댑터를 통한 Runner 관리 재시도 (`examples/basic/retry_litellm.py`)
+    -   Runner가 관리하는 재시도 설정 (`examples/basic/retry.py`)
+    -   서드파티 어댑터를 통해 Runner가 관리하는 재시도 (`examples/basic/retry_litellm.py`)
     -   비엄격 출력 타입
     -   이전 응답 ID 사용
 
 -   **[customer_service](https://github.com/openai/openai-agents-python/tree/main/examples/customer_service):**
-    항공사를 위한 고객 서비스 시스템 예제입니다
+    항공사를 위한 고객 서비스 시스템 예제입니다.
 
 -   **[financial_research_agent](https://github.com/openai/openai-agents-python/tree/main/examples/financial_research_agent):**
-    금융 데이터 분석을 위한 에이전트와 도구를 사용한 구조화된 리서치 워크플로를 보여주는 금융 리서치 에이전트입니다
+    금융 데이터 분석을 위한 에이전트와 도구로 구조화된 연구 워크플로를 보여 주는 금융 연구 에이전트입니다.
 
 -   **[handoffs](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs):**
-    메시지 필터링을 포함한 에이전트 핸드오프의 실용적인 예제:
+    메시지 필터링을 포함한 에이전트 핸드오프의 실제 예제입니다. 포함 항목:
 
     -   메시지 필터 예제 (`examples/handoffs/message_filter.py`)
     -   스트리밍을 포함한 메시지 필터 (`examples/handoffs/message_filter_streaming.py`)
 
 -   **[hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp):**
-    OpenAI Responses API와 함께 호스티드 MCP (Model context protocol)를 사용하는 방법을 보여주는 예제:
+    OpenAI Responses API와 함께 호스티드 MCP (Model Context Protocol)를 사용하는 방법을 보여 주는 예제입니다. 포함 항목:
 
-    -   승인 없는 간단한 호스티드 MCP (`examples/hosted_mcp/simple.py`)
-    -   Google Calendar 같은 MCP 커넥터 (`examples/hosted_mcp/connectors.py`)
+    -   승인이 없는 간단한 호스티드 MCP (`examples/hosted_mcp/simple.py`)
+    -   Google Calendar와 같은 MCP 커넥터 (`examples/hosted_mcp/connectors.py`)
     -   인터럽션(중단 처리) 기반 승인을 포함한 휴먼인더루프 (HITL) (`examples/hosted_mcp/human_in_the_loop.py`)
-    -   MCP 도구 호출용 승인 시 콜백 (`examples/hosted_mcp/on_approval.py`)
+    -   MCP 도구 호출에 대한 승인 시 콜백 (`examples/hosted_mcp/on_approval.py`)
 
 -   **[mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp):**
-    MCP (Model context protocol)로 에이전트를 구축하는 방법을 알아보세요:
+    다음을 포함하여 MCP (Model Context Protocol)로 에이전트를 빌드하는 방법을 알아봅니다:
 
-    -   파일시스템 예제
+    -   파일 시스템 예제
     -   Git 예제
     -   MCP 프롬프트 서버 예제
     -   SSE (Server-Sent Events) 예제
@@ -77,61 +77,61 @@ search:
     -   Streamable HTTP 예제
     -   Streamable HTTP 원격 연결 (`examples/mcp/streamable_http_remote_example`)
     -   Streamable HTTP용 사용자 지정 HTTP 클라이언트 팩토리 (`examples/mcp/streamablehttp_custom_client_example`)
-    -   `MCPUtil.get_all_function_tools`를 사용한 모든 MCP 도구 프리패칭 (`examples/mcp/get_all_mcp_tools_example`)
-    -   FastAPI를 사용하는 MCPServerManager (`examples/mcp/manager_example`)
+    -   `MCPUtil.get_all_function_tools`를 사용한 모든 MCP 도구 사전 가져오기 (`examples/mcp/get_all_mcp_tools_example`)
+    -   FastAPI와 함께 사용하는 MCPServerManager (`examples/mcp/manager_example`)
     -   MCP 도구 필터링 (`examples/mcp/tool_filter_example`)
 
 -   **[memory](https://github.com/openai/openai-agents-python/tree/main/examples/memory):**
-    에이전트를 위한 다양한 메모리 구현 예제:
+    에이전트용 다양한 메모리 구현 예제입니다. 포함 항목:
 
-    -   SQLite 세션 저장소
-    -   고급 SQLite 세션 저장소
-    -   Redis 세션 저장소
-    -   SQLAlchemy 세션 저장소
-    -   Dapr 상태 저장소 세션 저장소
-    -   암호화된 세션 저장소
-    -   OpenAI Conversations 세션 저장소
-    -   Responses 컴팩션 세션 저장소
-    -   `ModelSettings(store=False)`를 사용한 상태 비저장 Responses 컴팩션 (`examples/memory/compaction_session_stateless_example.py`)
-    -   파일 기반 세션 저장소 (`examples/memory/file_session.py`)
+    -   SQLite 세션 스토리지
+    -   고급 SQLite 세션 스토리지
+    -   Redis 세션 스토리지
+    -   SQLAlchemy 세션 스토리지
+    -   Dapr 상태 저장소 세션 스토리지
+    -   암호화된 세션 스토리지
+    -   OpenAI Conversations 세션 스토리지
+    -   Responses 압축 세션 스토리지
+    -   `ModelSettings(store=False)`를 사용한 무상태 Responses 압축 (`examples/memory/compaction_session_stateless_example.py`)
+    -   파일 기반 세션 스토리지 (`examples/memory/file_session.py`)
     -   휴먼인더루프 (HITL)를 포함한 파일 기반 세션 (`examples/memory/file_hitl_example.py`)
     -   휴먼인더루프 (HITL)를 포함한 SQLite 인메모리 세션 (`examples/memory/memory_session_hitl_example.py`)
     -   휴먼인더루프 (HITL)를 포함한 OpenAI Conversations 세션 (`examples/memory/openai_session_hitl_example.py`)
-    -   세션 전반의 HITL 승인/거절 시나리오 (`examples/memory/hitl_session_scenario.py`)
+    -   세션 간 HITL 승인/거부 시나리오 (`examples/memory/hitl_session_scenario.py`)
 
 -   **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
-    사용자 지정 프로바이더와 서드파티 어댑터를 포함해 SDK에서 OpenAI 이외 모델을 사용하는 방법을 살펴보세요
+    사용자 지정 제공자와 서드파티 어댑터를 포함하여 SDK에서 OpenAI가 아닌 모델을 사용하는 방법을 살펴봅니다.
 
 -   **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
-    SDK를 사용해 실시간 경험을 구축하는 방법을 보여주는 예제:
+    SDK를 사용하여 실시간 경험을 빌드하는 방법을 보여 주는 예제입니다. 포함 항목:
 
     -   구조화된 텍스트 및 이미지 메시지를 사용하는 웹 애플리케이션 패턴
-    -   커맨드라인 오디오 루프 및 재생 처리
+    -   명령줄 오디오 루프 및 재생 처리
     -   WebSocket을 통한 Twilio Media Streams 통합
-    -   Realtime Calls API attach 플로를 사용하는 Twilio SIP 통합
+    -   Realtime Calls API attach flows를 사용하는 Twilio SIP 통합
 
 -   **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
-    reasoning content를 다루는 방법을 보여주는 예제:
+    추론 콘텐츠를 다루는 방법을 보여 주는 예제입니다. 포함 항목:
 
-    -   Runner API의 reasoning content, 스트리밍 및 비스트리밍 (`examples/reasoning_content/runner_example.py`)
-    -   OpenRouter를 통한 OSS 모델의 reasoning content (`examples/reasoning_content/gpt_oss_stream.py`)
-    -   기본 reasoning content 예제 (`examples/reasoning_content/main.py`)
+    -   Runner API를 사용한 추론 콘텐츠, 스트리밍 및 비스트리밍 (`examples/reasoning_content/runner_example.py`)
+    -   OpenRouter를 통한 OSS 모델의 추론 콘텐츠 (`examples/reasoning_content/gpt_oss_stream.py`)
+    -   기본 추론 콘텐츠 예제 (`examples/reasoning_content/main.py`)
 
 -   **[research_bot](https://github.com/openai/openai-agents-python/tree/main/examples/research_bot):**
-    복잡한 멀티 에이전트 리서치 워크플로를 보여주는 간단한 딥 리서치 클론입니다
+    복잡한 다중 에이전트 연구 워크플로를 보여 주는 간단한 딥 리서치 클론입니다.
 
 -   **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
-    다음과 같은 OpenAI 호스트하는 도구 및 실험적 Codex 도구 기능을 구현하는 방법을 알아보세요:
+    다음과 같은 OpenAI 호스트하는 도구와 실험적 Codex 도구 기능을 구현하는 방법을 알아봅니다:
 
-    -   웹 검색 및 필터를 포함한 웹 검색
+    -   웹 검색 및 필터를 사용한 웹 검색
     -   파일 검색
-    -   Code Interpreter
+    -   Code interpreter
     -   파일 편집 및 승인을 포함한 패치 적용 도구 (`examples/tools/apply_patch.py`)
-    -   승인 콜백을 포함한 셸 도구 실행 (`examples/tools/shell.py`)
+    -   승인 콜백을 사용하는 셸 도구 실행 (`examples/tools/shell.py`)
     -   휴먼인더루프 (HITL) 인터럽션(중단 처리) 기반 승인을 포함한 셸 도구 (`examples/tools/shell_human_in_the_loop.py`)
-    -   인라인 스킬을 포함한 호스티드 컨테이너 셸 (`examples/tools/container_shell_inline_skill.py`)
-    -   스킬 참조를 포함한 호스티드 컨테이너 셸 (`examples/tools/container_shell_skill_reference.py`)
-    -   로컬 스킬을 포함한 로컬 셸 (`examples/tools/local_shell_skill.py`)
+    -   인라인 스킬을 사용하는 호스티드 컨테이너 셸 (`examples/tools/container_shell_inline_skill.py`)
+    -   스킬 참조를 사용하는 호스티드 컨테이너 셸 (`examples/tools/container_shell_skill_reference.py`)
+    -   로컬 스킬을 사용하는 로컬 셸 (`examples/tools/local_shell_skill.py`)
     -   네임스페이스 및 지연 도구를 사용하는 도구 검색 (`examples/tools/tool_search.py`)
     -   컴퓨터 사용
     -   이미지 생성
@@ -139,4 +139,4 @@ search:
     -   실험적 Codex 동일 스레드 워크플로 (`examples/tools/codex_same_thread.py`)
 
 -   **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
-    스트리밍 음성 예제를 포함해 TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인해 보세요
+    스트리밍 음성 예제를 포함하여, TTS 및 STT 모델을 사용하는 음성 에이전트 예제를 확인하세요.

docs/ko/guardrails.md

@@ -4,74 +4,74 @@ search:
 ---
 # 가드레일
 
-가드레일을 사용하면 사용자 입력과 에이전트 출력에 대한 검사 및 검증을 수행할 수 있습니다. 예를 들어, 고객 요청을 돕기 위해 매우 똑똑한(따라서 느리고/비싼) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 그 모델에게 수학 숙제를 도와달라고 요청하게 두고 싶지는 않을 것입니다. 따라서 빠르고/저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적인 사용을 감지하면 즉시 오류를 발생시켜 비싼 모델의 실행을 막을 수 있어 시간과 비용을 절약할 수 있습니다(**blocking guardrails를 사용할 때; parallel guardrails의 경우 가드레일이 완료되기 전에 비싼 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래의 "Execution modes"를 참고하세요**).
+가드레일을 사용하면 사용자 입력과 에이전트 출력에 대한 검사와 검증을 수행할 수 있습니다. 예를 들어, 고객 요청을 지원하기 위해 매우 똑똑한(따라서 느리고 비용이 많이 드는) 모델을 사용하는 에이전트가 있다고 가정해 보겠습니다. 악의적인 사용자가 모델에게 수학 숙제를 도와달라고 요청하는 상황은 원치 않을 것입니다. 따라서 빠르고 저렴한 모델로 가드레일을 실행할 수 있습니다. 가드레일이 악의적 사용을 감지하면 즉시 오류를 발생시켜 비용이 많이 드는 모델이 실행되지 않도록 하여 시간과 비용을 절약할 수 있습니다(**blocking 가드레일을 사용하는 경우입니다. parallel 가드레일의 경우 가드레일이 완료되기 전에 비용이 많이 드는 모델이 이미 실행을 시작했을 수 있습니다. 자세한 내용은 아래 "실행 모드"를 참고하세요**).
 
-가드레일에는 두 가지 종류가 있습니다:
+가드레일에는 두 가지 종류가 있습니다.
 
-1. 입력 가드레일은 초기 사용자 입력에서 실행됩니다
+1. 입력 가드레일은 최초 사용자 입력에서 실행됩니다
 2. 출력 가드레일은 최종 에이전트 출력에서 실행됩니다
 
 ## 워크플로 경계
 
-가드레일은 에이전트와 도구에 연결되지만, 워크플로의 동일한 지점에서 모두 실행되지는 않습니다:
+가드레일은 에이전트와 도구에 연결되지만, 워크플로의 모든 지점에서 실행되는 것은 아닙니다.
 
-- **입력 가드레일**은 체인의 첫 번째 에이전트에 대해서만 실행됩니다
-- **출력 가드레일**은 최종 출력을 생성하는 에이전트에 대해서만 실행됩니다
-- **도구 가드레일**은 모든 커스텀 함수 도구 호출에서 실행되며, 실행 전에는 입력 가드레일이, 실행 후에는 출력 가드레일이 실행됩니다
+-   **입력 가드레일**은 체인의 첫 번째 에이전트에 대해서만 실행됩니다.
+-   **출력 가드레일**은 최종 출력을 생성하는 에이전트에 대해서만 실행됩니다.
+-   **도구 가드레일**은 모든 사용자 지정 함수 도구 호출에서 실행되며, 입력 가드레일은 실행 전에, 출력 가드레일은 실행 후에 실행됩니다.
 
-매니저, 핸드오프 또는 위임된 전문 에이전트가 포함된 워크플로에서 각 커스텀 함수 도구 호출마다 검사가 필요하다면, 에이전트 수준의 입력/출력 가드레일에만 의존하지 말고 도구 가드레일을 사용하세요.
+매니저, 핸드오프, 또는 위임된 전문가가 포함된 워크플로에서 각 사용자 지정 함수 도구 호출 주변에 검사가 필요하다면, 에이전트 수준의 입력/출력 가드레일에만 의존하지 말고 도구 가드레일을 사용하세요.
 
 ## 입력 가드레일
 
-입력 가드레일은 3단계로 실행됩니다:
+입력 가드레일은 3단계로 실행됩니다.
 
-1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다
+1. 먼저, 가드레일은 에이전트에 전달된 것과 동일한 입력을 받습니다.
 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult]로 래핑됩니다
-3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다
+3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다.
 
 !!! Note
 
-    입력 가드레일은 사용자 입력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트일 때만 실행됩니다. 그렇다면 왜 가드레일을 `Runner.run`에 전달하지 않고 에이전트의 `guardrails` 속성에 두는지 궁금할 수 있습니다. 이는 가드레일이 실제 Agent와 관련되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 유리합니다.
+    입력 가드레일은 사용자 입력에서 실행되도록 의도되었으므로, 에이전트의 가드레일은 해당 에이전트가 *첫 번째* 에이전트인 경우에만 실행됩니다. `guardrails` 속성이 왜 `Runner.run`에 전달되지 않고 에이전트에 있는지 궁금할 수 있습니다. 이는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로, 코드를 함께 배치하면 가독성에 도움이 됩니다.
 
 ### 실행 모드
 
-입력 가드레일은 두 가지 실행 모드를 지원합니다:
+입력 가드레일은 두 가지 실행 모드를 지원합니다.
 
-- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트 실행과 동시에 실행됩니다. 둘 다 같은 시점에 시작되므로 지연 시간 측면에서 가장 유리합니다. 하지만 가드레일이 실패하면, 취소되기 전에 에이전트가 이미 토큰을 소비하고 도구를 실행했을 수 있습니다
+- **병렬 실행**(기본값, `run_in_parallel=True`): 가드레일이 에이전트 실행과 동시에 실행됩니다. 둘 다 동시에 시작되므로 가장 낮은 지연 시간을 제공합니다. 하지만 가드레일이 실패하면, 취소되기 전에 에이전트가 이미 토큰을 소비하고 도구를 실행했을 수 있습니다.
 
-- **차단 실행**(`run_in_parallel=False`): 에이전트가 시작되기 *전에* 가드레일이 실행되고 완료됩니다. 가드레일 트립와이어가 트리거되면 에이전트는 전혀 실행되지 않아 토큰 소비와 도구 실행을 방지합니다. 비용 최적화가 중요하고 도구 호출로 인한 잠재적 부작용을 피하고 싶을 때 이상적입니다
+- **차단 실행**(`run_in_parallel=False`): 에이전트가 시작되기 *전에* 가드레일이 실행되고 완료됩니다. 가드레일 트립와이어가 트리거되면 에이전트는 실행되지 않으므로 토큰 소비와 도구 실행을 방지합니다. 비용 최적화에 적합하며 도구 호출로 인한 잠재적 부작용을 피하고자 할 때 이상적입니다.
 
 ## 출력 가드레일
 
-출력 가드레일은 3단계로 실행됩니다:
+출력 가드레일은 3단계로 실행됩니다.
 
-1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다
+1. 먼저, 가드레일은 에이전트가 생성한 출력을 받습니다.
 2. 다음으로, 가드레일 함수가 실행되어 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 생성하고, 이는 [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]로 래핑됩니다
-3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다
+3. 마지막으로, [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered]가 true인지 확인합니다. true이면 [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 예외가 발생하므로, 사용자에게 적절히 응답하거나 예외를 처리할 수 있습니다.
 
 !!! Note
 
-    출력 가드레일은 최종 에이전트 출력에서 실행되도록 설계되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트일 때만 실행됩니다. 입력 가드레일과 마찬가지로 이렇게 하는 이유는 가드레일이 실제 Agent와 관련되는 경향이 있기 때문입니다. 에이전트마다 다른 가드레일을 실행하게 되므로 코드를 함께 배치하면 가독성에 유리합니다.
+    출력 가드레일은 최종 에이전트 출력에서 실행되도록 의도되었으므로, 에이전트의 가드레일은 해당 에이전트가 *마지막* 에이전트인 경우에만 실행됩니다. 입력 가드레일과 마찬가지로, 이렇게 하는 이유는 가드레일이 실제 에이전트와 관련되는 경우가 많기 때문입니다. 에이전트마다 서로 다른 가드레일을 실행하게 되므로, 코드를 함께 배치하면 가독성에 도움이 됩니다.
 
-    출력 가드레일은 항상 에이전트 완료 후 실행되므로 `run_in_parallel` 매개변수를 지원하지 않습니다.
+    출력 가드레일은 항상 에이전트가 완료된 후 실행되므로 `run_in_parallel` 매개변수를 지원하지 않습니다.
 
 ## 도구 가드레일
 
-도구 가드레일은 **함수 도구**를 감싸서 실행 전후에 도구 호출을 검증하거나 차단할 수 있게 합니다. 도구 자체에 구성되며 해당 도구가 호출될 때마다 실행됩니다.
+도구 가드레일은 **함수 도구**를 감싸며, 실행 전후에 도구 호출을 검증하거나 차단할 수 있게 해줍니다. 도구 자체에 구성되며, 해당 도구가 호출될 때마다 실행됩니다.
 
-- 입력 도구 가드레일은 도구 실행 전에 실행되며 호출 건너뛰기, 메시지로 출력 대체, 또는 트립와이어 발생을 수행할 수 있습니다
-- 출력 도구 가드레일은 도구 실행 후에 실행되며 출력 대체 또는 트립와이어 발생을 수행할 수 있습니다
-- 도구 가드레일은 [`function_tool`][agents.tool.function_tool]로 생성된 함수 도구에만 적용됩니다. 핸드오프는 일반 함수 도구 파이프라인이 아닌 SDK의 핸드오프 파이프라인을 통해 실행되므로, 핸드오프 호출 자체에는 도구 가드레일이 적용되지 않습니다. Hosted tools(`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`) 및 내장 실행 도구(`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`)도 이 가드레일 파이프라인을 사용하지 않으며, [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 현재 도구 가드레일 옵션을 직접 노출하지 않습니다
+- 입력 도구 가드레일은 도구가 실행되기 전에 실행되며, 호출을 건너뛰거나, 출력을 메시지로 대체하거나, 트립와이어를 발생시킬 수 있습니다.
+- 출력 도구 가드레일은 도구가 실행된 후 실행되며, 출력을 대체하거나 트립와이어를 발생시킬 수 있습니다.
+- 도구 가드레일은 [`function_tool`][agents.tool.function_tool]로 생성된 함수 도구에만 적용됩니다. 핸드오프는 일반적인 함수 도구 파이프라인이 아니라 SDK의 핸드오프 파이프라인을 통해 실행되므로, 도구 가드레일은 핸드오프 호출 자체에는 적용되지 않습니다. 호스티드 툴(`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`)과 내장 실행 도구(`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`)도 이 가드레일 파이프라인을 사용하지 않으며, [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 현재 도구 가드레일 옵션을 직접 노출하지 않습니다.
 
 자세한 내용은 아래 코드 스니펫을 참고하세요.
 
 ## 트립와이어
 
-입력 또는 출력이 가드레일 검사를 통과하지 못하면, Guardrail은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 Agent 실행을 중단합니다.
+입력 또는 출력이 가드레일을 통과하지 못하면, Guardrail은 트립와이어로 이를 신호할 수 있습니다. 트립와이어가 트리거된 가드레일을 확인하는 즉시 `{Input,Output}GuardrailTripwireTriggered` 예외를 발생시키고 에이전트 실행을 중단합니다.
 
 ## 가드레일 구현
 
-입력을 받아 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예제에서는 내부적으로 에이전트를 실행하는 방식으로 이를 수행합니다.
+입력을 받고 [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput]을 반환하는 함수를 제공해야 합니다. 이 예시에서는 내부적으로 에이전트를 실행하여 이를 수행합니다.
 
 ```python
 from pydantic import BaseModel
@@ -124,10 +124,10 @@ async def main():
         print("Math homework guardrail tripped")
 ```
 
-1. 가드레일 함수에서 이 에이전트를 사용합니다
-2. 에이전트의 입력/컨텍스트를 받아 결과를 반환하는 가드레일 함수입니다
-3. 가드레일 결과에 추가 정보를 포함할 수 있습니다
-4. 워크플로를 정의하는 실제 에이전트입니다
+1. 이 에이전트를 가드레일 함수에서 사용합니다.
+2. 에이전트의 입력/컨텍스트를 받고 결과를 반환하는 가드레일 함수입니다.
+3. 가드레일 결과에 추가 정보를 포함할 수 있습니다.
+4. 워크플로를 정의하는 실제 에이전트입니다.
 
 출력 가드레일도 유사합니다.
 
@@ -182,12 +182,12 @@ async def main():
         print("Math output guardrail tripped")
 ```
 
-1. 실제 에이전트의 출력 타입입니다
-2. 가드레일의 출력 타입입니다
-3. 에이전트의 출력을 받아 결과를 반환하는 가드레일 함수입니다
-4. 워크플로를 정의하는 실제 에이전트입니다
+1. 실제 에이전트의 출력 타입입니다.
+2. 가드레일의 출력 타입입니다.
+3. 에이전트의 출력을 받고 결과를 반환하는 가드레일 함수입니다.
+4. 워크플로를 정의하는 실제 에이전트입니다.
 
-마지막으로, 다음은 도구 가드레일 예시입니다.
+마지막으로, 도구 가드레일의 예시는 다음과 같습니다.
 
 ```python
 import json

docs/ko/handoffs.md

@@ -4,17 +4,17 @@ search:
 ---
 # 핸드오프
 
-핸드오프를 사용하면 한 에이전트가 다른 에이전트에 작업을 위임할 수 있습니다. 이는 서로 다른 에이전트가 각기 다른 영역을 전문으로 하는 시나리오에서 특히 유용합니다. 예를 들어 고객 지원 앱에는 주문 상태, 환불, FAQ 등의 작업을 각각 전담하는 에이전트가 있을 수 있습니다.
+핸드오프를 사용하면 에이전트가 다른 에이전트에 작업을 위임할 수 있습니다. 이는 서로 다른 에이전트가 각기 다른 영역에 특화된 시나리오에서 특히 유용합니다. 예를 들어 고객 지원 앱에는 주문 상태, 환불, FAQ 등의 작업을 각각 전담하는 에이전트가 있을 수 있습니다.
 
-핸드오프는 LLM에 도구로 표현됩니다. 따라서 `Refund Agent`라는 이름의 에이전트로 핸드오프가 있으면 도구 이름은 `transfer_to_refund_agent`가 됩니다.
+핸드오프는 LLM에 도구로 표현됩니다. 따라서 `Refund Agent`라는 에이전트로 핸드오프가 있다면, 도구는 `transfer_to_refund_agent`로 호출됩니다.
 
 ## 핸드오프 생성
 
-모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, 여기에 `Agent`를 직접 전달하거나 핸드오프를 사용자 지정하는 `Handoff` 객체를 전달할 수 있습니다.
+모든 에이전트에는 [`handoffs`][agents.agent.Agent.handoffs] 매개변수가 있으며, 이 매개변수는 `Agent`를 직접 받거나 핸드오프를 사용자 지정하는 `Handoff` 객체를 받을 수 있습니다.
 
-일반 `Agent` 인스턴스를 전달하면 해당 [`handoff_description`][agents.agent.Agent.handoff_description] (설정된 경우)이 기본 도구 설명에 추가됩니다. 전체 `handoff()` 객체를 작성하지 않고도 모델이 해당 핸드오프를 선택해야 하는 시점을 힌트로 제공할 때 사용하세요.
+일반 `Agent` 인스턴스를 전달하면, 해당 [`handoff_description`][agents.agent.Agent.handoff_description]이 설정된 경우 기본 도구 설명에 덧붙여집니다. 전체 `handoff()` 객체를 작성하지 않고도 모델이 해당 핸드오프를 선택해야 하는 경우를 암시하는 데 사용하세요.
 
-Agents SDK가 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용해 핸드오프를 만들 수 있습니다. 이 함수로 핸드오프 대상 에이전트와 선택적 재정의 및 입력 필터를 지정할 수 있습니다.
+Agents SDK에서 제공하는 [`handoff()`][agents.handoffs.handoff] 함수를 사용하여 핸드오프를 만들 수 있습니다. 이 함수를 사용하면 핸드오프할 에이전트를 지정하고, 선택적으로 오버라이드와 입력 필터를 지정할 수 있습니다.
 
 ### 기본 사용법
 
@@ -30,22 +30,22 @@ refund_agent = Agent(name="Refund agent")
 triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
 ```
 
-1. 에이전트를 직접 사용할 수 있고(`billing_agent`처럼), 또는 `handoff()` 함수를 사용할 수 있습니다.
+1. 에이전트를 직접 사용할 수도 있고(`billing_agent`에서처럼), `handoff()` 함수를 사용할 수도 있습니다.
 
-### `handoff()` 함수로 핸드오프 사용자 지정
+### `handoff()` 함수를 통한 핸드오프 사용자 지정
 
-[`handoff()`][agents.handoffs.handoff] 함수로 여러 항목을 사용자 지정할 수 있습니다.
+[`handoff()`][agents.handoffs.handoff] 함수를 사용하면 여러 항목을 사용자 지정할 수 있습니다.
 
 -   `agent`: 핸드오프 대상 에이전트입니다.
--   `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, `transfer_to_<agent_name>`으로 해석됩니다. 이를 재정의할 수 있습니다.
--   `tool_description_override`: `Handoff.default_tool_description()`의 기본 도구 설명을 재정의합니다
--   `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프 호출이 확정되는 즉시 데이터 페칭을 시작하는 등의 용도에 유용합니다. 이 함수는 에이전트 컨텍스트를 받으며, 선택적으로 LLM이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다.
--   `input_type`: 핸드오프 도구 호출 인자의 스키마입니다. 설정하면 파싱된 페이로드가 `on_handoff`로 전달됩니다.
--   `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있습니다. 자세한 내용은 아래를 참고하세요.
--   `is_enabled`: 핸드오프 활성화 여부입니다. 불리언 또는 불리언을 반환하는 함수가 될 수 있어 런타임에 동적으로 핸드오프를 활성화/비활성화할 수 있습니다.
--   `nest_handoff_history`: RunConfig 수준의 `nest_handoff_history` 설정에 대한 선택적 호출별 재정의입니다. `None`이면 활성 run 설정에 정의된 값을 대신 사용합니다.
+-   `tool_name_override`: 기본적으로 `Handoff.default_tool_name()` 함수가 사용되며, 이는 `transfer_to_<agent_name>`으로 해석됩니다. 이를 오버라이드할 수 있습니다.
+-   `tool_description_override`: `Handoff.default_tool_description()`의 기본 도구 설명을 오버라이드합니다.
+-   `on_handoff`: 핸드오프가 호출될 때 실행되는 콜백 함수입니다. 핸드오프가 호출되는 것을 알게 되는 즉시 일부 데이터 가져오기를 시작하는 등의 작업에 유용합니다. 이 함수는 에이전트 컨텍스트를 받으며, 선택적으로 LLM이 생성한 입력도 받을 수 있습니다. 입력 데이터는 `input_type` 매개변수로 제어됩니다.
+-   `input_type`: 핸드오프 도구 호출 인자의 스키마입니다. 설정하면 파싱된 페이로드가 `on_handoff`에 전달됩니다.
+-   `input_filter`: 다음 에이전트가 받는 입력을 필터링할 수 있게 해줍니다. 자세한 내용은 아래를 참조하세요.
+-   `is_enabled`: 핸드오프가 활성화되어 있는지 여부입니다. 불리언이거나 불리언을 반환하는 함수일 수 있으므로, 런타임에 동적으로 핸드오프를 활성화하거나 비활성화할 수 있습니다.
+-   `nest_handoff_history`: RunConfig 수준의 `nest_handoff_history` 설정에 대한 선택적 호출별 오버라이드입니다. `None`이면 활성 실행 구성에 정의된 값이 대신 사용됩니다.
 
-[`handoff()`][agents.handoffs.handoff] 헬퍼는 항상 전달한 특정 `agent`로 제어를 넘깁니다. 가능한 대상이 여러 개라면 대상마다 하나의 핸드오프를 등록하고 모델이 그중에서 선택하게 하세요. 호출 시점에 어떤 에이전트를 반환할지 직접 핸드오프 코드에서 결정해야 할 때만 사용자 지정 [`Handoff`][agents.handoffs.Handoff]를 사용하세요.
+[`handoff()`][agents.handoffs.handoff] 헬퍼는 항상 전달한 특정 `agent`로 제어권을 이전합니다. 가능한 목적지가 여러 개라면 목적지마다 하나의 핸드오프를 등록하고 모델이 그중에서 선택하게 하세요. 호출 시점에 어떤 에이전트를 반환할지 자체 핸드오프 코드가 결정해야 하는 경우에만 사용자 지정 [`Handoff`][agents.handoffs.Handoff]를 사용하세요.
 
 ```python
 from agents import Agent, handoff, RunContextWrapper
@@ -65,7 +65,7 @@ handoff_obj = handoff(
 
 ## 핸드오프 입력
 
-특정 상황에서는 핸드오프를 호출할 때 LLM이 일부 데이터를 제공하도록 하고 싶을 수 있습니다. 예를 들어 "Escalation agent"로 핸드오프한다고 가정해 보겠습니다. 이때 기록을 남기기 위해 사유를 함께 받도록 할 수 있습니다.
+특정 상황에서는 LLM이 핸드오프를 호출할 때 일부 데이터를 제공하기를 원할 수 있습니다. 예를 들어 "에스컬레이션 에이전트"로 핸드오프하는 경우를 생각해 보세요. 이를 기록할 수 있도록 사유를 제공받고 싶을 수 있습니다.
 
 ```python
 from pydantic import BaseModel
@@ -87,44 +87,44 @@ handoff_obj = handoff(
 )
 ```
 
-`input_type`은 핸드오프 도구 호출 자체의 인자를 설명합니다. SDK는 그 스키마를 핸드오프 도구의 `parameters`로 모델에 노출하고, 반환된 JSON을 로컬에서 검증한 뒤, 파싱된 값을 `on_handoff`에 전달합니다.
+`input_type`은 핸드오프 도구 호출 자체의 인자를 설명합니다. SDK는 해당 스키마를 핸드오프 도구의 `parameters`로 모델에 노출하고, 반환된 JSON을 로컬에서 검증하며, 파싱된 값을 `on_handoff`에 전달합니다.
 
-이는 다음 에이전트의 기본 입력을 대체하지 않으며, 다른 목적지를 선택하지도 않습니다. [`handoff()`][agents.handoffs.handoff] 헬퍼는 여전히 래핑한 특정 에이전트로 전송하며, 수신 에이전트는 [`input_filter`][agents.handoffs.Handoff.input_filter] 또는 중첩 핸드오프 기록 설정으로 변경하지 않는 한 대화 기록을 계속 확인합니다.
+이는 다음 에이전트의 주 입력을 대체하지 않으며, 다른 목적지를 선택하지도 않습니다. [`handoff()`][agents.handoffs.handoff] 헬퍼는 여전히 래핑한 특정 에이전트로 이전하며, 수신 에이전트는 [`input_filter`][agents.handoffs.Handoff.input_filter] 또는 중첩 핸드오프 기록 설정으로 변경하지 않는 한 여전히 대화 기록을 봅니다.
 
-`input_type`은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]와도 별개입니다. 이미 로컬에 있는 애플리케이션 상태나 의존성이 아니라, 모델이 핸드오프 시점에 결정하는 메타데이터에 `input_type`을 사용하세요.
+`input_type`은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]와도 별개입니다. 로컬에 이미 있는 애플리케이션 상태나 종속성이 아니라, 모델이 핸드오프 시점에 결정하는 메타데이터에는 `input_type`을 사용하세요.
 
 ### `input_type` 사용 시점
 
-핸드오프에 `reason`, `language`, `priority`, `summary` 같은 모델 생성 메타데이터의 작은 조각이 필요할 때 `input_type`을 사용하세요. 예를 들어 트리아지 에이전트는 `{ "reason": "duplicate_charge", "priority": "high" }`와 함께 환불 에이전트로 핸드오프할 수 있으며, `on_handoff`는 환불 에이전트가 이어받기 전에 해당 메타데이터를 기록하거나 저장할 수 있습니다.
+핸드오프에 `reason`, `language`, `priority`, `summary`와 같이 모델이 생성한 작은 메타데이터가 필요할 때 `input_type`을 사용하세요. 예를 들어 분류 에이전트는 `{ "reason": "duplicate_charge", "priority": "high" }`와 함께 환불 에이전트로 핸드오프할 수 있으며, 환불 에이전트가 이어받기 전에 `on_handoff`에서 해당 메타데이터를 기록하거나 저장할 수 있습니다.
 
-목적이 다르면 다른 메커니즘을 선택하세요:
+목표가 다른 경우에는 다른 메커니즘을 선택하세요:
 
--   기존 애플리케이션 상태와 의존성은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 넣으세요. [컨텍스트 가이드](context.md)를 참고하세요.
--   수신 에이전트가 보는 기록을 바꾸려면 [`input_filter`][agents.handoffs.Handoff.input_filter], [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history], 또는 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 사용하세요.
--   가능한 전문 에이전트 대상이 여러 개라면 대상마다 하나의 핸드오프를 등록하세요. `input_type`은 선택된 핸드오프에 메타데이터를 추가할 수는 있지만, 대상 간 디스패치를 수행하지는 않습니다.
--   대화를 전송하지 않고 중첩 전문 에이전트에 구조화된 입력을 주고 싶다면 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]을 우선 사용하세요. [도구](tools.md#structured-input-for-tool-agents)를 참고하세요.
+-   기존 애플리케이션 상태와 종속성은 [`RunContextWrapper.context`][agents.run_context.RunContextWrapper.context]에 넣으세요. [컨텍스트 가이드](context.md)를 참조하세요.
+-   수신 에이전트가 보게 될 기록을 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter], [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history] 또는 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 사용하세요.
+-   여러 전문 에이전트 중 하나를 선택할 수 있는 경우 목적지마다 하나의 핸드오프를 등록하세요. `input_type`은 선택된 핸드오프에 메타데이터를 추가할 수 있지만, 목적지 사이에서 디스패치하지는 않습니다.
+-   대화를 이전하지 않고 중첩된 전문 에이전트에 구조화된 입력을 제공하려면 [`Agent.as_tool(parameters=...)`][agents.agent.Agent.as_tool]를 선호하세요. [도구](tools.md#structured-input-for-tool-agents)를 참조하세요.
 
 ## 입력 필터
 
-핸드오프가 발생하면 새 에이전트가 대화를 이어받아 이전 전체 대화 기록을 보는 것과 같습니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter]를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData]를 통해 기존 입력을 받고, 새로운 `HandoffInputData`를 반환해야 하는 함수입니다.
+핸드오프가 발생하면 새 에이전트가 대화를 이어받아 이전 대화 기록 전체를 볼 수 있는 것처럼 동작합니다. 이를 변경하려면 [`input_filter`][agents.handoffs.Handoff.input_filter]를 설정할 수 있습니다. 입력 필터는 [`HandoffInputData`][agents.handoffs.HandoffInputData]를 통해 기존 입력을 받는 함수이며, 새로운 `HandoffInputData`를 반환해야 합니다.
 
 [`HandoffInputData`][agents.handoffs.HandoffInputData]에는 다음이 포함됩니다:
 
--   `input_history`: `Runner.run(...)` 시작 전의 입력 기록
--   `pre_handoff_items`: 핸드오프가 호출된 에이전트 턴 이전에 생성된 항목
--   `new_items`: 핸드오프 호출 및 핸드오프 출력 항목을 포함해 현재 턴에서 생성된 항목
--   `input_items`: `new_items` 대신 다음 에이전트로 전달할 선택적 항목으로, 세션 기록용 `new_items`는 유지하면서 모델 입력을 필터링할 수 있게 해줍니다
--   `run_context`: 핸드오프 호출 시점의 활성 [`RunContextWrapper`][agents.run_context.RunContextWrapper]
+-   `input_history`: `Runner.run(...)`이 시작되기 전의 입력 기록입니다.
+-   `pre_handoff_items`: 핸드오프가 호출된 에이전트 턴 이전에 생성된 항목입니다.
+-   `new_items`: 핸드오프 호출과 핸드오프 출력 항목을 포함하여 현재 턴 동안 생성된 항목입니다.
+-   `input_items`: `new_items` 대신 다음 에이전트로 전달할 선택적 항목으로, 세션 기록을 위해 `new_items`는 그대로 유지하면서 모델 입력을 필터링할 수 있습니다.
+-   `run_context`: 핸드오프가 호출된 시점의 활성 [`RunContextWrapper`][agents.run_context.RunContextWrapper]입니다.
 
-중첩 핸드오프는 옵트인 베타로 제공되며 안정화 중이므로 기본적으로 비활성화되어 있습니다. [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]를 활성화하면 러너는 이전 전사를 단일 어시스턴트 요약 메시지로 축약하고, 동일 run에서 여러 핸드오프가 발생할 때 새 턴이 계속 추가되도록 `<CONVERSATION HISTORY>` 블록으로 감쌉니다. 전체 `input_filter`를 작성하지 않고 생성된 메시지를 대체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 통해 자체 매핑 함수를 제공할 수 있습니다. 이 옵트인은 핸드오프와 run 어느 쪽에서도 명시적 `input_filter`를 제공하지 않을 때만 적용되므로, 이미 페이로드를 사용자 지정하는 기존 코드(이 저장소의 예제 포함)는 변경 없이 현재 동작을 유지합니다. [`handoff(...)`][agents.handoffs.handoff]에 `nest_handoff_history=True` 또는 `False`를 전달해 단일 핸드오프의 중첩 동작을 재정의할 수 있으며, 이는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 설정합니다. 생성된 요약의 래퍼 텍스트만 바꾸면 된다면 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (및 선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers])를 호출하세요.
+중첩 핸드오프는 옵트인 베타로 제공되며, 안정화하는 동안 기본적으로 비활성화되어 있습니다. [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]를 활성화하면 러너는 이전 대화 기록을 하나의 assistant 요약 메시지로 축약하고, 동일한 실행 중 여러 핸드오프가 발생할 때 새 턴을 계속 덧붙이는 `<CONVERSATION HISTORY>` 블록으로 감쌉니다. 전체 `input_filter`를 작성하지 않고 생성된 메시지를 대체하려면 [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]를 통해 자체 매핑 함수를 제공할 수 있습니다. 이 옵트인은 핸드오프와 실행 모두 명시적 `input_filter`를 제공하지 않을 때만 적용되므로, 이미 페이로드를 사용자 지정하는 기존 코드(이 저장소의 코드 예제 포함)는 변경 없이 현재 동작을 유지합니다. 단일 핸드오프에 대한 중첩 동작은 [`handoff(...)`][agents.handoffs.handoff]에 `nest_handoff_history=True` 또는 `False`를 전달하여 오버라이드할 수 있으며, 이는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 설정합니다. 생성된 요약의 래퍼 텍스트만 변경해야 하는 경우, 에이전트를 실행하기 전에 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(선택적으로 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]도 호출할 수 있습니다).
 
-핸드오프와 활성 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter] 양쪽 모두 필터를 정의한 경우, 해당 핸드오프에는 핸드오프별 [`input_filter`][agents.handoffs.Handoff.input_filter]가 우선 적용됩니다.
+핸드오프와 활성 [`RunConfig.handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]가 모두 필터를 정의하는 경우, 해당 특정 핸드오프에는 핸드오프별 [`input_filter`][agents.handoffs.Handoff.input_filter]가 우선합니다.
 
 !!! note
 
-    핸드오프는 단일 run 내에서만 유지됩니다. 입력 가드레일은 체인의 첫 번째 에이전트에만 계속 적용되고, 출력 가드레일은 최종 출력을 생성하는 에이전트에만 적용됩니다. 워크플로 내 각 사용자 지정 함수 도구 호출 주변에서 검사가 필요하다면 도구 가드레일을 사용하세요.
+    핸드오프는 단일 실행 안에서만 이루어집니다. 입력 가드레일은 여전히 체인의 첫 번째 에이전트에만 적용되고, 출력 가드레일은 최종 출력을 생성하는 에이전트에만 적용됩니다. 워크플로 안의 각 사용자 지정 함수 도구 호출 주변에 검사가 필요할 때는 도구 가드레일을 사용하세요.
 
-일부 일반 패턴(예: 기록에서 모든 도구 호출 제거)은 [`agents.extensions.handoff_filters`][]에 구현되어 있습니다
+몇 가지 일반적인 패턴(예: 기록에서 모든 도구 호출 제거)은 [`agents.extensions.handoff_filters`][]에 구현되어 있습니다.
 
 ```python
 from agents import Agent, handoff
@@ -142,7 +142,7 @@ handoff_obj = handoff(
 
 ## 권장 프롬프트
 
-LLM이 핸드오프를 올바르게 이해하도록 하려면, 에이전트에 핸드오프 관련 정보를 포함할 것을 권장합니다. [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][]에 권장 접두사가 있으며, [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][]를 호출해 프롬프트에 권장 데이터를 자동으로 추가할 수도 있습니다.
+LLM이 핸드오프를 올바르게 이해하도록 하려면 에이전트에 핸드오프 관련 정보를 포함할 것을 권장합니다. [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][]에 권장 접두사가 있으며, [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][]를 호출하여 프롬프트에 권장 데이터를 자동으로 추가할 수도 있습니다.
 
 ```python
 from agents import Agent

docs/ko/human_in_the_loop.md

@@ -4,17 +4,17 @@ search:
 ---
 # 휴먼인더루프 (HITL)
 
-휴먼인더루프 (HITL) 흐름을 사용해 민감한 도구 호출을 사람이 승인하거나 거절할 때까지 에이전트 실행을 일시 중지할 수 있습니다. 도구는 승인 필요 여부를 선언하고, 실행 결과는 대기 중인 승인을 인터럽션으로 노출하며, `RunState`를 통해 결정 이후 실행을 직렬화하고 재개할 수 있습니다
+휴먼인더루프 (HITL) 흐름을 사용해 사람이 민감한 도구 호출을 승인하거나 거부할 때까지 에이전트 실행을 일시 중지합니다. 도구는 승인이 필요한 시점을 선언하고, 실행 결과는 대기 중인 승인을 인터럽션(중단 처리)으로 표시하며, `RunState`를 사용하면 결정이 내려진 뒤 실행을 직렬화하고 재개할 수 있습니다.
 
-이 승인 표면은 현재 최상위 에이전트로 제한되지 않고 실행 전체에 적용됩니다. 동일한 패턴은 도구가 현재 에이전트에 속한 경우, 핸드오프를 통해 도달한 에이전트에 속한 경우, 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에 속한 경우에도 적용됩니다. 중첩된 `Agent.as_tool()`의 경우에도 인터럽션은 바깥 실행에 나타나므로, 바깥 `RunState`에서 승인 또는 거절하고 원래 최상위 실행을 재개합니다
+이 승인 표면은 실행 전체에 적용되며, 현재 최상위 에이전트로 제한되지 않습니다. 도구가 현재 에이전트에 속한 경우, 핸드오프를 통해 도달한 에이전트에 속한 경우, 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에 속한 경우에도 동일한 패턴이 적용됩니다. 중첩된 `Agent.as_tool()` 사례에서도 인터럽션(중단 처리)은 여전히 외부 실행에 표시되므로, 외부 `RunState`에서 승인하거나 거부한 뒤 원래 최상위 실행을 재개합니다.
 
-`Agent.as_tool()`에서는 서로 다른 두 계층에서 승인이 발생할 수 있습니다: 에이전트 도구 자체가 `Agent.as_tool(..., needs_approval=...)`를 통해 승인을 요구할 수 있고, 중첩된 실행이 시작된 뒤에는 중첩 에이전트 내부 도구가 자체 승인을 다시 요청할 수 있습니다. 둘 다 동일한 바깥 실행 인터럽션 흐름으로 처리됩니다
+`Agent.as_tool()`을 사용할 때 승인은 두 가지 서로 다른 계층에서 발생할 수 있습니다. 에이전트 도구 자체가 `Agent.as_tool(..., needs_approval=...)`을 통해 승인을 요구할 수 있고, 중첩된 에이전트 내부의 도구가 중첩 실행이 시작된 뒤 나중에 자체 승인을 발생시킬 수 있습니다. 둘 다 동일한 외부 실행 인터럽션(중단 처리) 흐름을 통해 처리됩니다.
 
-이 페이지는 `interruptions`를 통한 수동 승인 흐름에 중점을 둡니다. 앱에서 코드로 판단할 수 있다면, 일부 도구 유형은 프로그래매틱 승인 콜백도 지원하므로 실행을 멈추지 않고 계속할 수 있습니다
+이 페이지는 `interruptions`를 통한 수동 승인 흐름에 초점을 맞춥니다. 앱이 코드에서 결정을 내릴 수 있다면, 일부 도구 유형은 프로그래밍 방식 승인 콜백도 지원하므로 실행을 일시 중지하지 않고 계속할 수 있습니다.
 
-## 승인 필요 도구 표시
+## 승인이 필요한 도구 표시
 
-항상 승인을 요구하려면 `needs_approval`를 `True`로 설정하거나, 호출별로 판단하는 비동기 함수를 제공하세요. 호출 가능 객체는 실행 컨텍스트, 파싱된 도구 매개변수, 도구 호출 ID를 받습니다
+항상 승인을 요구하려면 `needs_approval`을 `True`로 설정하고, 호출별로 결정하려면 비동기 함수를 제공합니다. 호출 가능한 객체는 실행 컨텍스트, 파싱된 도구 매개변수, 도구 호출 ID를 받습니다.
 
 ```python
 from agents import Agent, Runner, function_tool
@@ -41,28 +41,28 @@ agent = Agent(
 )
 ```
 
-`needs_approval`는 [`function_tool`][agents.tool.function_tool], [`Agent.as_tool`][agents.agent.Agent.as_tool], [`ShellTool`][agents.tool.ShellTool], [`ApplyPatchTool`][agents.tool.ApplyPatchTool]에서 사용할 수 있습니다. 로컬 MCP 서버도 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]의 `require_approval`를 통해 승인을 지원합니다. 호스티드 MCP 서버는 [`HostedMCPTool`][agents.tool.HostedMCPTool]에서 `tool_config={"require_approval": "always"}`와 선택적 `on_approval_request` 콜백으로 승인을 지원합니다. Shell 및 apply_patch 도구는 인터럽션을 노출하지 않고 자동 승인 또는 자동 거절하려는 경우 `on_approval` 콜백을 받을 수 있습니다
+`needs_approval`은 [`function_tool`][agents.tool.function_tool], [`Agent.as_tool`][agents.agent.Agent.as_tool], [`ShellTool`][agents.tool.ShellTool], [`ApplyPatchTool`][agents.tool.ApplyPatchTool]에서 사용할 수 있습니다. 로컬 MCP 서버도 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]의 `require_approval`을 통해 승인을 지원합니다. 호스티드 MCP 서버는 [`HostedMCPTool`][agents.tool.HostedMCPTool]에서 `tool_config={"require_approval": "always"}`와 선택적 `on_approval_request` 콜백을 통해 승인을 지원합니다. Shell 및 apply_patch 도구는 인터럽션(중단 처리)을 표시하지 않고 자동 승인 또는 자동 거부를 하려는 경우 `on_approval` 콜백을 허용합니다.
 
-## 승인 흐름 작동 방식
+## 승인 흐름의 작동 방식
 
-1. 모델이 도구 호출을 생성하면 러너는 해당 도구의 승인 규칙(`needs_approval`, `require_approval`, 또는 호스티드 MCP 동등 설정)을 평가합니다
-2. 해당 도구 호출에 대한 승인 결정이 이미 [`RunContextWrapper`][agents.run_context.RunContextWrapper]에 저장되어 있으면, 러너는 추가 확인 없이 진행합니다. 호출별 승인은 특정 호출 ID 범위에만 적용됩니다. 실행의 나머지 동안 같은 도구의 향후 호출에도 동일한 결정을 유지하려면 `always_approve=True` 또는 `always_reject=True`를 전달하세요
-3. 그렇지 않으면 실행이 일시 중지되고 `RunResult.interruptions`(또는 `RunResultStreaming.interruptions`)에 `agent.name`, `tool_name`, `arguments` 같은 세부 정보를 담은 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 항목이 포함됩니다. 여기에는 핸드오프 이후 또는 중첩 `Agent.as_tool()` 실행 내부에서 발생한 승인도 포함됩니다
-4. `result.to_state()`로 결과를 `RunState`로 변환하고, `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤, `Runner.run(agent, state)` 또는 `Runner.run_streamed(agent, state)`로 재개하세요. 여기서 `agent`는 해당 실행의 원래 최상위 에이전트입니다
-5. 재개된 실행은 중단된 지점부터 계속되며, 새 승인이 필요하면 이 흐름으로 다시 진입합니다
+1. 모델이 도구 호출을 내보내면, 러너는 해당 승인 규칙(`needs_approval`, `require_approval` 또는 호스티드 MCP에 해당하는 설정)을 평가합니다.
+2. 해당 도구 호출에 대한 승인 결정이 이미 [`RunContextWrapper`][agents.run_context.RunContextWrapper]에 저장되어 있으면, 러너는 프롬프트 없이 진행합니다. 호출별 승인은 특정 호출 ID로 범위가 지정됩니다. 실행의 나머지 동안 해당 도구에 대한 향후 호출에도 같은 결정을 유지하려면 `always_approve=True` 또는 `always_reject=True`를 전달합니다.
+3. 그렇지 않으면 실행이 일시 중지되고 `RunResult.interruptions`(또는 `RunResultStreaming.interruptions`)에는 `agent.name`, `tool_name`, `arguments`와 같은 세부 정보가 포함된 [`ToolApprovalItem`][agents.items.ToolApprovalItem] 항목이 들어갑니다. 여기에는 핸드오프 이후 또는 중첩된 `Agent.as_tool()` 실행 내부에서 발생한 승인도 포함됩니다.
+4. `result.to_state()`로 결과를 `RunState`로 변환하고, `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤, 실행의 원래 최상위 에이전트인 `agent`와 함께 `Runner.run(agent, state)` 또는 `Runner.run_streamed(agent, state)`로 재개합니다.
+5. 재개된 실행은 중단된 지점부터 계속되며, 새 승인이 필요하면 이 흐름에 다시 진입합니다.
 
-`always_approve=True` 또는 `always_reject=True`로 생성된 고정 결정은 실행 상태에 저장되므로, 나중에 동일한 일시 중지 실행을 재개할 때 `state.to_string()` / `RunState.from_string(...)` 및 `state.to_json()` / `RunState.from_json(...)`을 거쳐도 유지됩니다
+`always_approve=True` 또는 `always_reject=True`로 생성된 고정 결정은 실행 상태에 저장되므로, 나중에 같은 일시 중지된 실행을 재개할 때 `state.to_string()` / `RunState.from_string(...)` 및 `state.to_json()` / `RunState.from_json(...)` 후에도 유지됩니다.
 
-같은 패스에서 모든 대기 중 승인을 처리할 필요는 없습니다. `interruptions`에는 일반 함수 도구, 호스티드 MCP 승인, 중첩 `Agent.as_tool()` 승인이 혼합되어 있을 수 있습니다. 일부 항목만 승인 또는 거절한 뒤 다시 실행하면, 해결된 호출은 계속 진행되고 미해결 항목은 `interruptions`에 남아 실행을 다시 일시 중지합니다
+같은 단계에서 대기 중인 모든 승인을 해결할 필요는 없습니다. `interruptions`에는 일반 함수 도구, 호스티드 MCP 승인, 중첩된 `Agent.as_tool()` 승인 등이 섞여 있을 수 있습니다. 일부 항목만 승인하거나 거부한 뒤 다시 실행하면, 해결된 호출은 계속될 수 있고 해결되지 않은 호출은 `interruptions`에 남아 실행을 다시 일시 중지합니다.
 
-## 사용자 지정 거절 메시지
+## 사용자 지정 거부 메시지
 
-기본적으로 거절된 도구 호출은 SDK의 표준 거절 텍스트를 실행으로 다시 반환합니다. 이 메시지는 두 계층에서 사용자 지정할 수 있습니다
+기본적으로 거부된 도구 호출은 SDK의 표준 거부 텍스트를 실행으로 다시 반환합니다. 이 메시지는 두 계층에서 사용자 지정할 수 있습니다.
 
--   실행 전체 대체값: [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]를 설정해 실행 전체의 승인 거절에 대한 기본 모델 표시 메시지를 제어합니다
--   호출별 재정의: 특정 거절 도구 호출에 다른 메시지를 노출하려면 `state.reject(...)`에 `rejection_message=...`를 전달합니다
+-   실행 전체 폴백: 전체 실행에서 승인 거부에 대해 모델에 표시되는 기본 메시지를 제어하려면 [`RunConfig.tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]를 설정합니다.
+-   호출별 재정의: 특정 거부된 도구 호출 하나에 다른 메시지를 표시하려면 `state.reject(...)`에 `rejection_message=...`를 전달합니다.
 
-둘 다 제공되면 호출별 `rejection_message`가 실행 전체 포매터보다 우선합니다
+둘 다 제공되면, 호출별 `rejection_message`가 실행 전체 포매터보다 우선합니다.
 
 ```python
 from agents import RunConfig, ToolErrorFormatterArgs
@@ -83,27 +83,27 @@ state.reject(
 )
 ```
 
-두 계층을 함께 보여주는 완전한 예시는 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py)를 참조하세요
+두 계층을 함께 보여 주는 전체 예제는 [`examples/agent_patterns/human_in_the_loop_custom_rejection.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/human_in_the_loop_custom_rejection.py)를 참고하세요.
 
 ## 자동 승인 결정
 
-수동 `interruptions`가 가장 일반적인 패턴이지만 유일한 방법은 아닙니다
+수동 `interruptions`가 가장 일반적인 패턴이지만, 유일한 방법은 아닙니다.
 
--   로컬 [`ShellTool`][agents.tool.ShellTool] 및 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]은 `on_approval`을 사용해 코드에서 즉시 승인 또는 거절할 수 있습니다
--   [`HostedMCPTool`][agents.tool.HostedMCPTool]은 `tool_config={"require_approval": "always"}`와 `on_approval_request`를 함께 사용해 같은 유형의 프로그래매틱 결정을 내릴 수 있습니다
--   일반 [`function_tool`][agents.tool.function_tool] 도구와 [`Agent.as_tool()`][agents.agent.Agent.as_tool]은 이 페이지의 수동 인터럽션 흐름을 사용합니다
+-   로컬 [`ShellTool`][agents.tool.ShellTool] 및 [`ApplyPatchTool`][agents.tool.ApplyPatchTool]은 `on_approval`을 사용해 코드에서 즉시 승인하거나 거부할 수 있습니다.
+-   [`HostedMCPTool`][agents.tool.HostedMCPTool]은 `tool_config={"require_approval": "always"}`와 `on_approval_request`를 함께 사용해 같은 종류의 프로그래밍 방식 결정을 수행할 수 있습니다.
+-   일반 [`function_tool`][agents.tool.function_tool] 도구와 [`Agent.as_tool()`][agents.agent.Agent.as_tool]는 이 페이지의 수동 인터럽션(중단 처리) 흐름을 사용합니다.
 
-이 콜백들이 결정을 반환하면 실행은 사람 응답을 기다리며 멈추지 않고 계속됩니다. Realtime 및 음성 세션 API의 경우 [Realtime 가이드](realtime/guide.md)의 승인 흐름을 참조하세요
+이러한 콜백이 결정을 반환하면, 실행은 사람의 응답을 기다리며 일시 중지하지 않고 계속됩니다. Realtime 및 음성 세션 API의 경우 [Realtime 가이드](realtime/guide.md)의 승인 흐름을 참고하세요.
 
 ## 스트리밍 및 세션
 
-동일한 인터럽션 흐름은 스트리밍 실행에서도 동작합니다. 스트리밍 실행이 일시 중지된 뒤에는 반복자가 끝날 때까지 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events]를 계속 소비하고, [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]를 확인해 해결한 다음, 재개 출력도 계속 스트리밍하려면 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed]로 재개하세요. 이 패턴의 스트리밍 버전은 [스트리밍](streaming.md)을 참조하세요
+동일한 인터럽션(중단 처리) 흐름은 스트리밍 실행에서도 작동합니다. 스트리밍 실행이 일시 중지된 뒤에는 이터레이터가 완료될 때까지 [`RunResultStreaming.stream_events()`][agents.result.RunResultStreaming.stream_events]를 계속 소비하고, [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]를 검사하고, 이를 해결한 다음, 재개된 출력도 계속 스트리밍하려면 [`Runner.run_streamed(...)`][agents.run.Runner.run_streamed]로 재개합니다. 이 패턴의 스트리밍 버전은 [스트리밍](streaming.md)을 참고하세요.
 
-세션도 함께 사용 중이라면 `RunState`에서 재개할 때 동일한 세션 인스턴스를 계속 전달하거나, 같은 백엔드 스토어를 가리키는 다른 세션 객체를 전달하세요. 그러면 재개된 턴이 같은 저장 대화 기록에 추가됩니다. 세션 수명주기 상세는 [세션](sessions/index.md)을 참조하세요
+세션도 사용 중이라면 `RunState`에서 재개할 때 동일한 세션 인스턴스를 계속 전달하거나, 같은 백킹 스토어를 가리키는 다른 세션 객체를 전달합니다. 그러면 재개된 턴이 동일하게 저장된 대화 기록에 추가됩니다. 세션 수명 주기 세부 정보는 [세션](sessions/index.md)을 참고하세요.
 
 ## 예시: 일시 중지, 승인, 재개
 
-아래 스니펫은 JavaScript HITL 가이드를 반영합니다: 도구에 승인이 필요하면 일시 중지하고, 상태를 디스크에 저장했다가, 다시 불러와 결정 수집 후 재개합니다
+아래 스니펫은 JavaScript HITL 가이드를 반영합니다. 도구에 승인이 필요할 때 일시 중지하고, 상태를 디스크에 저장하며, 다시 로드한 뒤 결정을 수집하고 재개합니다.
 
 ```python
 import asyncio
@@ -167,35 +167,35 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-이 예시에서 `prompt_approval`는 `input()`을 사용하고 `run_in_executor(...)`로 실행되므로 동기식입니다. 승인 소스가 이미 비동기(예: HTTP 요청 또는 비동기 데이터베이스 쿼리)라면 `async def` 함수를 사용해 대신 직접 `await`할 수 있습니다
+이 예제에서 `prompt_approval`은 `input()`을 사용하고 `run_in_executor(...)`로 실행되기 때문에 동기식입니다. 승인 소스가 이미 비동기식인 경우(예: HTTP 요청 또는 비동기 데이터베이스 쿼리), 대신 `async def` 함수를 사용하고 직접 `await`할 수 있습니다.
 
-승인 대기 중에도 출력을 스트리밍하려면 `Runner.run_streamed`를 호출하고, `result.stream_events()`를 완료될 때까지 소비한 다음, 위에 나온 동일한 `result.to_state()` 및 재개 단계를 따르세요
+승인을 기다리는 동안 출력을 스트리밍하려면 `Runner.run_streamed`를 호출하고, 완료될 때까지 `result.stream_events()`를 소비한 다음, 위에 표시된 것과 동일한 `result.to_state()` 및 재개 단계를 따릅니다.
 
-## 저장소 패턴 및 예제
+## 리포지토리 패턴 및 코드 예제
 
-- **스트리밍 승인**: `examples/agent_patterns/human_in_the_loop_stream.py`는 `stream_events()`를 모두 소비한 뒤 대기 중인 도구 호출을 승인하고 `Runner.run_streamed(agent, state)`로 재개하는 방법을 보여줍니다
-- **사용자 지정 거절 텍스트**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py`는 승인이 거절될 때 실행 수준 `tool_error_formatter`와 호출별 `rejection_message` 재정의를 결합하는 방법을 보여줍니다
-- **도구로서의 에이전트 승인**: `Agent.as_tool(..., needs_approval=...)`는 위임된 에이전트 작업에 검토가 필요할 때 동일한 인터럽션 흐름을 적용합니다. 중첩 인터럽션도 바깥 실행에 노출되므로 중첩 에이전트가 아니라 원래 최상위 에이전트를 재개하세요
-- **로컬 shell 및 apply_patch 도구**: `ShellTool`과 `ApplyPatchTool`도 `needs_approval`를 지원합니다. 향후 호출에 대한 결정을 캐시하려면 `state.approve(interruption, always_approve=True)` 또는 `state.reject(..., always_reject=True)`를 사용하세요. 자동 결정을 위해서는 `on_approval`를 제공하고(`examples/tools/shell.py` 참조), 수동 결정을 위해서는 인터럽션을 처리하세요(`examples/tools/shell_human_in_the_loop.py` 참조). 호스티드 shell 환경은 `needs_approval` 또는 `on_approval`를 지원하지 않습니다. [도구 가이드](tools.md)를 참조하세요
-- **로컬 MCP 서버**: MCP 도구 호출을 제어하려면 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp`에서 `require_approval`를 사용하세요(`examples/mcp/get_all_mcp_tools_example/main.py`, `examples/mcp/tool_filter_example/main.py` 참조)
-- **호스티드 MCP 서버**: HITL을 강제하려면 `HostedMCPTool`에서 `require_approval`를 `"always"`로 설정하고, 필요 시 `on_approval_request`를 제공해 자동 승인 또는 거절할 수 있습니다(`examples/hosted_mcp/human_in_the_loop.py`, `examples/hosted_mcp/on_approval.py` 참조). 신뢰 가능한 서버에는 `"never"`를 사용하세요(`examples/hosted_mcp/simple.py`)
-- **세션 및 메모리**: 승인과 대화 기록이 여러 턴에 걸쳐 유지되도록 `Runner.run`에 세션을 전달하세요. SQLite 및 OpenAI Conversations 세션 변형은 `examples/memory/memory_session_hitl_example.py`와 `examples/memory/openai_session_hitl_example.py`에 있습니다
-- **실시간 에이전트**: realtime 데모는 `RealtimeSession`의 `approve_tool_call` / `reject_tool_call`을 통해 도구 호출을 승인 또는 거절하는 WebSocket 메시지를 노출합니다(서버 측 핸들러는 `examples/realtime/app/server.py`, API 표면은 [Realtime 가이드](realtime/guide.md#tool-approvals) 참조)
+- **스트리밍 승인**: `examples/agent_patterns/human_in_the_loop_stream.py`는 `stream_events()`를 모두 소비한 다음, `Runner.run_streamed(agent, state)`로 재개하기 전에 대기 중인 도구 호출을 승인하는 방법을 보여 줍니다.
+- **사용자 지정 거부 텍스트**: `examples/agent_patterns/human_in_the_loop_custom_rejection.py`는 승인이 거부될 때 실행 수준 `tool_error_formatter`와 호출별 `rejection_message` 재정의를 결합하는 방법을 보여 줍니다.
+- **도구로서의 에이전트 승인**: 위임된 에이전트 작업에 검토가 필요할 때 `Agent.as_tool(..., needs_approval=...)`은 동일한 인터럽션(중단 처리) 흐름을 적용합니다. 중첩된 인터럽션(중단 처리)은 여전히 외부 실행에 표시되므로, 중첩된 에이전트가 아니라 원래 최상위 에이전트를 재개합니다.
+- **로컬 shell 및 apply_patch 도구**: `ShellTool` 및 `ApplyPatchTool`도 `needs_approval`을 지원합니다. 향후 호출에 대한 결정을 캐시하려면 `state.approve(interruption, always_approve=True)` 또는 `state.reject(..., always_reject=True)`를 사용합니다. 자동 결정의 경우 `on_approval`을 제공하고(`examples/tools/shell.py` 참고), 수동 결정의 경우 인터럽션(중단 처리)을 처리합니다(`examples/tools/shell_human_in_the_loop.py` 참고). 호스티드 shell 환경은 `needs_approval` 또는 `on_approval`을 지원하지 않습니다. [도구 가이드](tools.md)를 참고하세요.
+- **로컬 MCP 서버**: MCP 도구 호출을 제한하려면 `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp`에서 `require_approval`을 사용합니다(`examples/mcp/get_all_mcp_tools_example/main.py` 및 `examples/mcp/tool_filter_example/main.py` 참고).
+- **호스티드 MCP 서버**: HITL을 강제하려면 `HostedMCPTool`에서 `require_approval`을 `"always"`로 설정하고, 선택적으로 자동 승인 또는 거부를 위해 `on_approval_request`를 제공합니다(`examples/hosted_mcp/human_in_the_loop.py` 및 `examples/hosted_mcp/on_approval.py` 참고). 신뢰할 수 있는 서버에는 `"never"`를 사용합니다(`examples/hosted_mcp/simple.py`).
+- **세션 및 메모리**: 승인과 대화 기록이 여러 턴에 걸쳐 유지되도록 `Runner.run`에 세션을 전달합니다. SQLite 및 OpenAI Conversations 세션 변형은 `examples/memory/memory_session_hitl_example.py` 및 `examples/memory/openai_session_hitl_example.py`에 있습니다.
+- **실시간 에이전트**: realtime 데모는 `RealtimeSession`의 `approve_tool_call` / `reject_tool_call`을 통해 도구 호출을 승인하거나 거부하는 WebSocket 메시지를 노출합니다(서버 측 핸들러는 `examples/realtime/app/server.py`, API 표면은 [Realtime 가이드](realtime/guide.md#tool-approvals) 참고).
 
 ## 장기 실행 승인
 
-`RunState`는 내구성을 고려해 설계되었습니다. 대기 작업을 데이터베이스나 큐에 저장하려면 `state.to_json()` 또는 `state.to_string()`을 사용하고, 나중에 `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 다시 생성하세요
+`RunState`는 내구성을 갖도록 설계되었습니다. `state.to_json()` 또는 `state.to_string()`을 사용해 대기 중인 작업을 데이터베이스나 큐에 저장하고, 나중에 `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 다시 생성합니다.
 
 유용한 직렬화 옵션:
 
--   `context_serializer`: 매핑이 아닌 컨텍스트 객체를 직렬화하는 방식을 사용자 지정합니다
--   `context_deserializer`: `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 상태를 불러올 때 매핑이 아닌 컨텍스트 객체를 재구성합니다
--   `strict_context=True`: 컨텍스트가 이미 매핑이거나 적절한 serializer/deserializer를 제공하지 않으면 직렬화 또는 역직렬화를 실패시킵니다
--   `context_override`: 상태를 불러올 때 직렬화된 컨텍스트를 대체합니다. 원래 컨텍스트 객체를 복원하지 않으려는 경우 유용하지만, 이미 직렬화된 페이로드에서 해당 컨텍스트를 제거하지는 않습니다
--   `include_tracing_api_key=True`: 재개된 작업이 동일한 자격 증명으로 트레이스를 계속 내보내야 할 때 직렬화된 트레이스 페이로드에 트레이싱 API 키를 포함합니다
+-   `context_serializer`: 매핑이 아닌 컨텍스트 객체를 직렬화하는 방식을 사용자 지정합니다.
+-   `context_deserializer`: `RunState.from_json(...)` 또는 `RunState.from_string(...)`으로 상태를 로드할 때 매핑이 아닌 컨텍스트 객체를 다시 빌드합니다.
+-   `strict_context=True`: 컨텍스트가 이미 매핑이거나 적절한 직렬화기/역직렬화기를 제공하지 않는 한 직렬화 또는 역직렬화에 실패합니다.
+-   `context_override`: 상태를 로드할 때 직렬화된 컨텍스트를 교체합니다. 원래 컨텍스트 객체를 복원하고 싶지 않을 때 유용하지만, 이미 직렬화된 페이로드에서 해당 컨텍스트를 제거하지는 않습니다.
+-   `include_tracing_api_key=True`: 재개된 작업이 동일한 자격 증명으로 트레이스를 계속 내보내야 할 때 직렬화된 트레이스 페이로드에 트레이싱 API 키를 포함합니다.
 
-직렬화된 실행 상태에는 앱 컨텍스트와 함께 승인, 사용량, 직렬화된 `tool_input`, 중첩 에이전트-as-tool 재개, 트레이스 메타데이터, 서버 관리 대화 설정 같은 SDK 관리 런타임 메타데이터가 포함됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 `RunContextWrapper.context`를 영속 데이터로 취급하고, 상태와 함께 이동시키려는 의도가 없는 한 비밀 정보를 그 안에 두지 마세요
+직렬화된 실행 상태에는 앱 컨텍스트와 함께 승인, 사용량, 직렬화된 `tool_input`, 중첩된 agent-as-tool 재개, 트레이스 메타데이터, 서버 관리 대화 설정과 같은 SDK 관리 런타임 메타데이터가 포함됩니다. 직렬화된 상태를 저장하거나 전송할 계획이라면 `RunContextWrapper.context`를 영속화된 데이터로 취급하고, 해당 상태와 함께 이동하기를 의도한 경우가 아니라면 여기에 비밀 정보를 넣지 마세요.
 
-## 대기 작업 버전 관리
+## 대기 중인 작업의 버전 관리
 
-승인이 한동안 대기 상태로 있을 수 있다면, 직렬화된 상태와 함께 에이전트 정의 또는 SDK의 버전 마커를 저장하세요. 그러면 모델, 프롬프트 또는 도구 정의가 바뀔 때 발생할 수 있는 비호환성을 피하기 위해 역직렬화를 일치하는 코드 경로로 라우팅할 수 있습니다
+승인이 한동안 대기할 수 있다면, 직렬화된 상태와 함께 에이전트 정의 또는 SDK의 버전 마커를 저장합니다. 그러면 모델, 프롬프트 또는 도구 정의가 변경될 때 비호환성을 피하기 위해 역직렬화를 일치하는 코드 경로로 라우팅할 수 있습니다.

docs/ko/index.md

@@ -4,51 +4,51 @@ search:
 ---
 # OpenAI Agents SDK
 
-[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)는 매우 적은 추상화만으로 에이전트형 AI 앱을 가볍고 사용하기 쉬운 패키지로 구축할 수 있게 해줍니다. 이는 이전의 에이전트 실험용 프레임워크인 [Swarm](https://github.com/openai/swarm/tree/main)을 프로덕션 준비 수준으로 확장한 것입니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 제공합니다.
+[OpenAI Agents SDK](https://github.com/openai/openai-agents-python)를 사용하면 매우 적은 추상화만으로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있습니다. 이는 이전 에이전트 실험 프로젝트인 [Swarm](https://github.com/openai/swarm/tree/main)을 프로덕션에 바로 사용할 수 있도록 업그레이드한 것입니다. Agents SDK는 매우 작은 기본 구성 요소 집합을 갖습니다.
 
 -   **에이전트**: instructions와 tools를 갖춘 LLM
--   **Agents as tools / 핸드오프**: 에이전트가 특정 작업을 위해 다른 에이전트에 위임할 수 있게 해주는 기능
--   **가드레일**: 에이전트 입력과 출력을 검증할 수 있게 해주는 기능
+-   **Agents as tools / 핸드오프**: 에이전트가 특정 작업을 다른 에이전트에 위임할 수 있게 하는 기능
+-   **가드레일**: 에이전트 입력과 출력을 검증할 수 있게 하는 기능
 
-이러한 기본 구성 요소는 Python과 결합될 때 도구와 에이전트 간의 복잡한 관계를 표현할 수 있을 만큼 강력하며, 가파른 학습 곡선 없이도 실제 애플리케이션을 구축할 수 있게 해줍니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버그할 수 있을 뿐만 아니라 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수 있도록 해주는 내장 **트레이싱**도 포함되어 있습니다.
+Python과 결합하면 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하기에 충분히 강력하며, 가파른 학습 곡선 없이 실제 애플리케이션을 구축할 수 있습니다. 또한 SDK에는 에이전트형 흐름을 시각화하고 디버깅하며, 이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝할 수 있는 내장 **트레이싱** 기능이 포함되어 있습니다.
 
-## Agents SDK 사용 이유
+## Agents SDK를 사용하는 이유
 
 SDK에는 두 가지 핵심 설계 원칙이 있습니다.
 
-1. 사용할 가치가 있을 만큼 충분한 기능을 제공하면서도, 빠르게 익힐 수 있을 만큼 기본 구성 요소 수는 적게 유지합니다
-2. 기본 상태로도 훌륭하게 동작하지만, 정확히 어떤 일이 일어날지 세밀하게 사용자 지정할 수 있습니다
+1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 배울 수 있을 만큼 기본 구성 요소는 적게 유지합니다.
+2. 기본 설정만으로도 잘 작동하지만, 어떤 일이 일어나는지는 정확하게 사용자 지정할 수 있습니다.
 
-다음은 SDK의 주요 기능입니다.
+SDK의 주요 기능은 다음과 같습니다.
 
--   **에이전트 루프**: 도구 호출을 처리하고, 결과를 LLM에 다시 전달하며, 작업이 완료될 때까지 계속하는 내장 에이전트 루프
--   **파이썬 우선**: 새로운 추상화를 배울 필요 없이, 내장 언어 기능을 사용해 에이전트를 오케스트레이션하고 연결합니다
--   **Agents as tools / 핸드오프**: 여러 에이전트에 걸쳐 작업을 조율하고 위임하기 위한 강력한 메커니즘
--   **샌드박스 에이전트**: 매니페스트로 정의된 파일, 샌드박스 클라이언트 선택, 재개 가능한 샌드박스 세션을 갖춘 실제 격리 작업공간 안에서 전문 에이전트를 실행합니다
--   **가드레일**: 에이전트 실행과 병렬로 입력 검증 및 안전성 검사를 수행하고, 검사를 통과하지 못하면 즉시 실패 처리합니다
--   **함수 도구**: 자동 스키마 생성과 Pydantic 기반 검증을 통해 모든 Python 함수를 도구로 변환합니다
+-   **에이전트 루프**: 도구 호출을 처리하고, 결과를 LLM에 다시 보내며, 작업이 완료될 때까지 계속 실행하는 내장 에이전트 루프
+-   **파이썬 우선**: 새로운 추상화를 배울 필요 없이, 내장 언어 기능을 사용해 에이전트를 오케스트레이션하고 체인으로 연결
+-   **Agents as tools / 핸드오프**: 여러 에이전트 간 작업을 조율하고 위임하기 위한 강력한 메커니즘
+-   **샌드박스 에이전트**: 매니페스트로 정의된 파일, 샌드박스 클라이언트 선택, 재개 가능한 샌드박스 세션을 통해 실제 격리된 워크스페이스 안에서 전문가 실행
+-   **가드레일**: 에이전트 실행과 병렬로 입력 검증 및 안전성 검사를 실행하고, 검사를 통과하지 못하면 빠르게 실패 처리
+-   **함수 도구**: 자동 스키마 생성 및 Pydantic 기반 검증을 통해 모든 Python 함수를 도구로 변환
 -   **MCP 서버 도구 호출**: 함수 도구와 동일한 방식으로 작동하는 내장 MCP 서버 도구 통합
--   **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 지속형 메모리 계층
--   **휴먼인더루프 (HITL)**: 에이전트 실행 전반에 걸쳐 사람이 개입할 수 있도록 하는 내장 메커니즘
--   **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하기 위한 내장 트레이싱으로, OpenAI의 평가, 파인튜닝, 증류 도구 모음을 지원합니다
--   **실시간 에이전트**: `gpt-realtime-1.5`와 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 사용해 강력한 음성 에이전트를 구축합니다
+-   **세션**: 에이전트 루프 내에서 작업 컨텍스트를 유지하기 위한 영속 메모리 계층
+-   **휴먼인더루프 (HITL)**: 에이전트 실행 전반에 사람을 참여시키기 위한 내장 메커니즘
+-   **트레이싱**: OpenAI의 평가, 파인튜닝, 증류 도구 모음 지원과 함께 워크플로를 시각화, 디버깅, 모니터링하기 위한 내장 트레이싱
+-   **실시간 에이전트**: `gpt-realtime-2`, 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등을 활용해 강력한 음성 에이전트 구축
 
 ## Agents SDK 또는 Responses API
 
-SDK는 OpenAI 모델에 대해 기본적으로 Responses API를 사용하지만, 모델 호출 위에 더 높은 수준의 런타임을 추가로 제공합니다.
+SDK는 OpenAI 모델에 기본적으로 Responses API를 사용하지만, 모델 호출 주변에 더 높은 수준의 런타임을 추가합니다.
 
-다음과 같은 경우에는 Responses API를 직접 사용하세요.
+다음과 같은 경우 Responses API를 직접 사용하세요.
 
--   루프, 도구 디스패치, 상태 처리를 직접 관리하고 싶은 경우
--   워크플로가 짧게 유지되며 주로 모델의 응답을 반환하는 것이 목적일 경우
+-   루프, 도구 디스패치, 상태 처리를 직접 관리하려는 경우
+-   워크플로가 짧게 실행되며 주로 모델의 응답을 반환하는 것이 목적인 경우
 
-다음과 같은 경우에는 Agents SDK를 사용하세요.
+다음과 같은 경우 Agents SDK를 사용하세요.
 
--   런타임이 턴, 도구 실행, 가드레일, 핸드오프 또는 세션을 관리하길 원하는 경우
--   에이전트가 아티팩트를 생성하거나 여러 조정된 단계에 걸쳐 작업해야 하는 경우
--   [샌드박스 에이전트](sandbox_agents.md)를 통해 실제 작업공간이나 재개 가능한 실행이 필요한 경우
+-   런타임이 턴, 도구 실행, 가드레일, 핸드오프 또는 세션을 관리하기를 원하는 경우
+-   에이전트가 아티팩트를 생성하거나 여러 조율된 단계에 걸쳐 동작해야 하는 경우
+-   실제 워크스페이스나 [샌드박스 에이전트](sandbox_agents.md)를 통한 재개 가능한 실행이 필요한 경우
 
-둘 중 하나를 전역적으로 선택할 필요는 없습니다. 많은 애플리케이션이 관리형 워크플로에는 SDK를 사용하고, 더 낮은 수준의 경로에는 Responses API를 직접 호출합니다.
+둘 중 하나를 전역적으로 선택할 필요는 없습니다. 많은 애플리케이션은 관리형 워크플로에는 SDK를 사용하고, 더 낮은 수준의 경로에는 Responses API를 직접 호출합니다.
 
 ## 설치
 
@@ -56,7 +56,7 @@ SDK는 OpenAI 모델에 대해 기본적으로 Responses API를 사용하지만,
 pip install openai-agents
 ```
 
-## Hello World 예제
+## Hello world 예제
 
 ```python
 from agents import Agent, Runner
@@ -71,7 +71,7 @@ print(result.final_output)
 # Infinite loop's dance.
 ```
 
-(_이를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정했는지 확인하세요_)
+(_이를 실행하는 경우 `OPENAI_API_KEY` 환경 변수를 설정했는지 확인하세요_)
 
 ```bash
 export OPENAI_API_KEY=sk-...
@@ -79,23 +79,23 @@ export OPENAI_API_KEY=sk-...
 
 ## 시작 지점
 
--   [Quickstart](quickstart.md)로 첫 번째 텍스트 기반 에이전트를 구축하세요
--   그런 다음 [에이전트 실행](running_agents.md#choose-a-memory-strategy)에서 턴 간 상태를 어떻게 유지할지 결정하세요
--   작업이 실제 파일, 저장소 또는 에이전트별로 격리된 작업공간 상태에 의존한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)을 읽어보세요
--   핸드오프와 관리자 스타일 오케스트레이션 중 무엇을 선택할지 결정하고 있다면 [에이전트 오케스트레이션](multi_agent.md)을 읽어보세요
+-   [빠른 시작](quickstart.md)으로 첫 텍스트 기반 에이전트를 구축하세요.
+-   그런 다음 [에이전트 실행](running_agents.md#choose-a-memory-strategy)에서 턴 간 상태를 어떻게 유지할지 결정하세요.
+-   작업이 실제 파일, 리포지토리 또는 에이전트별 격리된 워크스페이스 상태에 의존한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)을 읽어 보세요.
+-   핸드오프와 매니저 스타일 오케스트레이션 중에서 결정하는 중이라면 [에이전트 오케스트레이션](multi_agent.md)을 읽어 보세요.
 
 ## 경로 선택
 
-원하는 작업은 알고 있지만 어떤 페이지가 이를 설명하는지 모를 때 이 표를 사용하세요.
+하려는 작업은 알고 있지만 어느 페이지에서 설명하는지 모를 때 이 표를 사용하세요.
 
 | 목표 | 시작 지점 |
 | --- | --- |
-| 첫 번째 텍스트 에이전트를 만들고 하나의 전체 실행을 확인하기 | [Quickstart](quickstart.md) |
-| 함수 도구, 호스티드 툴 또는 Agents as tools 추가하기 | [도구](tools.md) |
-| 실제 격리 작업공간 안에서 코딩, 리뷰 또는 문서 에이전트 실행하기 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) 및 [샌드박스 클라이언트](sandbox/clients.md) |
-| 핸드오프와 관리자 스타일 오케스트레이션 중 선택하기 | [에이전트 오케스트레이션](multi_agent.md) |
-| 턴 간 메모리 유지하기 | [에이전트 실행](running_agents.md#choose-a-memory-strategy) 및 [세션](sessions/index.md) |
-| OpenAI 모델, websocket 전송 또는 OpenAI가 아닌 제공자 사용하기 | [모델](models/index.md) |
-| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토하기 | [결과](results.md) |
-| `gpt-realtime-1.5`로 저지연 음성 에이전트 구축하기 | [실시간 에이전트 빠른 시작](realtime/quickstart.md) 및 [실시간 전송](realtime/transport.md) |
-| speech-to-text / 에이전트 / text-to-speech 파이프라인 구축하기 | [음성 파이프라인 빠른 시작](voice/quickstart.md) |
+| 첫 텍스트 에이전트를 만들고 전체 실행 한 번 확인 | [빠른 시작](quickstart.md) |
+| 함수 도구, 호스티드 툴 또는 agents as tools 추가 | [도구](tools.md) |
+| 실제 격리된 워크스페이스 안에서 코딩, 리뷰 또는 문서 에이전트 실행 | [샌드박스 에이전트 빠른 시작](sandbox_agents.md) 및 [샌드박스 클라이언트](sandbox/clients.md) |
+| 핸드오프와 매니저 스타일 오케스트레이션 중에서 결정 | [에이전트 오케스트레이션](multi_agent.md) |
+| 턴 간 메모리 유지 | [에이전트 실행](running_agents.md#choose-a-memory-strategy) 및 [세션](sessions/index.md) |
+| OpenAI 모델, 웹소켓 전송 또는 비 OpenAI 제공자 사용 | [모델](models/index.md) |
+| 출력, 실행 항목, 인터럽션(중단 처리), 재개 상태 검토 | [결과](results.md) |
+| `gpt-realtime-2`로 지연 시간이 낮은 음성 에이전트 구축 | [실시간 에이전트 빠른 시작](realtime/quickstart.md) 및 [실시간 전송](realtime/transport.md) |
+| 음성-텍스트 변환 / 에이전트 / 텍스트-음성 변환 파이프라인 구축 | [음성 파이프라인 빠른 시작](voice/quickstart.md) |

docs/ko/mcp.md

@@ -4,32 +4,32 @@ search:
 ---
 # Model context protocol (MCP)
 
-[Model context protocol](https://modelcontextprotocol.io/introduction)(MCP)은 애플리케이션이 언어 모델에 도구와 컨텍스트를 노출하는 방식을 표준화합니다. 공식 문서에서 다음과 같이 설명합니다:
+[Model context protocol](https://modelcontextprotocol.io/introduction)(MCP)은 애플리케이션이 언어 모델에 도구와 컨텍스트를 노출하는 방식을 표준화합니다. 공식 문서에 따르면:
 
-> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI 애플리케이션용 USB-C 포트라고 생각해 보세요
-> USB-C가 다양한 주변기기 및 액세서리에 기기를 연결하는 표준화된 방법을 제공하듯, MCP는
-> AI 모델을 서로 다른 데이터 소스 및 도구에 연결하는 표준화된 방법을 제공합니다
+> MCP는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP를 AI
+> 애플리케이션용 USB-C 포트처럼 생각해 보세요. USB-C가 기기를 다양한 주변기기 및 액세서리에 연결하는 표준화된 방법을 제공하듯이, MCP는
+> AI 모델을 다양한 데이터 소스와 도구에 연결하는 표준화된 방법을 제공합니다.
 
 Agents Python SDK는 여러 MCP 전송 방식을 이해합니다. 이를 통해 기존 MCP 서버를 재사용하거나 직접 구축하여
-파일시스템, HTTP 또는 커넥터 기반 도구를 에이전트에 노출할 수 있습니다.
+파일 시스템, HTTP 또는 커넥터 기반 도구를 에이전트에 노출할 수 있습니다.
 
 ## MCP 통합 선택
 
-에이전트에 MCP 서버를 연결하기 전에 도구 호출이 어디에서 실행되어야 하는지, 어떤 전송 방식에 도달할 수 있는지 결정하세요. 아래
-매트릭스는 Python SDK가 지원하는 옵션을 요약합니다.
+MCP 서버를 에이전트에 연결하기 전에 도구 호출을 어디에서 실행해야 하는지, 어떤 전송 방식에 접근할 수 있는지 결정하세요. 아래
+표는 Python SDK가 지원하는 옵션을 요약합니다.
 
-| 필요한 항목                                                                        | 권장 옵션                                    |
+| 필요한 사항                                                                        | 권장 옵션                                    |
 | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
-| OpenAI의 Responses API가 모델을 대신해 공개적으로 접근 가능한 MCP 서버를 호출하도록 하기| [`HostedMCPTool`][agents.tool.HostedMCPTool]을 통한 **호스티드 MCP 서버 도구** |
-| 로컬 또는 원격에서 실행하는 Streamable HTTP 서버에 연결                  | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 통한 **Streamable HTTP MCP 서버** |
-| Server-Sent Events를 사용하는 HTTP를 구현한 서버와 통신                          | [`MCPServerSse`][agents.mcp.server.MCPServerSse]를 통한 **SSE 기반 HTTP MCP 서버** |
-| 로컬 프로세스를 실행하고 stdin/stdout으로 통신                             | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 통한 **stdio MCP 서버** |
+| OpenAI의 Responses API가 모델을 대신해 공개적으로 접근 가능한 MCP 서버를 호출하도록 하기| [`HostedMCPTool`][agents.tool.HostedMCPTool]을 통한 **Hosted MCP server tools** |
+| 로컬 또는 원격에서 실행하는 Streamable HTTP 서버에 연결하기                  | [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 통한 **Streamable HTTP MCP 서버** |
+| Server-Sent Events를 사용하는 HTTP를 구현한 서버와 통신하기                          | [`MCPServerSse`][agents.mcp.server.MCPServerSse]를 통한 **SSE 사용 HTTP MCP 서버** |
+| 로컬 프로세스를 시작하고 stdin/stdout을 통해 통신하기                             | [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 통한 **stdio MCP 서버** |
 
-아래 섹션에서는 각 옵션, 구성 방법, 그리고 어떤 전송 방식을 선호해야 하는지를 안내합니다.
+아래 섹션에서는 각 옵션, 구성 방법, 그리고 어떤 경우에 특정 전송 방식을 선호해야 하는지 설명합니다.
 
 ## 에이전트 수준 MCP 구성
 
-전송 방식 선택 외에도 `Agent.mcp_config`를 설정하여 MCP 도구 준비 방식을 조정할 수 있습니다.
+전송 방식을 선택하는 것 외에도 `Agent.mcp_config`를 설정하여 MCP 도구가 준비되는 방식을 조정할 수 있습니다.
 
 ```python
 from agents import Agent
@@ -43,38 +43,42 @@ agent = Agent(
         # If None, MCP tool failures are raised as exceptions instead of
         # returning model-visible error text.
         "failure_error_function": None,
+        # Prefix local MCP tool names with their server name.
+        "include_server_in_tool_names": True,
     },
 )
 ```
 
 참고:
 
-- `convert_schemas_to_strict`는 최선의 노력 방식입니다. 스키마를 변환할 수 없으면 원래 스키마를 사용합니다
-- `failure_error_function`은 MCP 도구 호출 실패가 모델에 어떻게 표시될지 제어합니다
-- `failure_error_function`이 설정되지 않으면 SDK는 기본 도구 오류 포매터를 사용합니다
-- 서버 수준 `failure_error_function`은 해당 서버에서 `Agent.mcp_config["failure_error_function"]`보다 우선합니다
+- `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 도구 이름을 호출합니다.
 
 ## 전송 방식 전반의 공통 패턴
 
-전송 방식을 선택한 뒤에는 대부분의 통합에서 동일한 후속 결정을 해야 합니다:
+전송 방식을 선택한 후에는 대부분의 통합에서 동일한 후속 결정을 내려야 합니다:
 
-- 도구의 일부만 노출하는 방법([도구 필터링](#tool-filtering))
-- 서버가 재사용 가능한 프롬프트도 제공하는지 여부([프롬프트](#prompts))
-- `list_tools()`를 캐시해야 하는지 여부([캐싱](#caching))
-- MCP 활동이 트레이스에 어떻게 표시되는지([트레이싱](#tracing))
+- 도구의 일부만 노출하는 방법([도구 필터링](#tool-filtering)).
+- 서버가 재사용 가능한 프롬프트도 제공하는지 여부([프롬프트](#prompts)).
+- `list_tools()`를 캐시해야 하는지 여부([캐싱](#caching)).
+- MCP 활동이 트레이스에 표시되는 방식([트레이싱](#tracing)).
 
-로컬 MCP 서버(`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`)의 경우 승인 정책과 호출별 `_meta` 페이로드도 공통 개념입니다. Streamable HTTP 섹션에 가장 완전한 예제가 있으며, 동일한 패턴이 다른 로컬 전송 방식에도 적용됩니다.
+로컬 MCP 서버(`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`)의 경우 승인 정책과 호출별 `_meta` 페이로드도 공통 개념입니다. Streamable HTTP 섹션에서 가장 완전한 예를 보여 주며, 동일한 패턴은 다른 로컬 전송 방식에도 적용됩니다.
 
-## 1. 호스티드 MCP 서버 도구
+## 1. Hosted MCP server tools
 
-호스티드 도구는 도구 라운드트립 전체를 OpenAI 인프라로 이동시킵니다. 코드가 도구를 나열하고 호출하는 대신
-[`HostedMCPTool`][agents.tool.HostedMCPTool]이 서버 레이블(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 모델은
-원격 서버의 도구를 나열하고 Python 프로세스에 추가 콜백 없이 이를 호출합니다. 현재 호스티드 도구는 Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 동작합니다.
+호스티드 툴은 전체 도구 왕복 과정을 OpenAI 인프라로 넘깁니다. 코드에서 도구를 나열하고 호출하는 대신,
+[`HostedMCPTool`][agents.tool.HostedMCPTool]이 서버 라벨(및 선택적 커넥터 메타데이터)을 Responses API로 전달합니다. 그러면
+모델이 원격 서버의 도구를 나열하고, Python 프로세스에 추가 콜백 없이 이를 호출합니다. 호스티드 툴은 현재
+Responses API의 호스티드 MCP 통합을 지원하는 OpenAI 모델에서 작동합니다.
 
 ### 기본 호스티드 MCP 도구
 
-에이전트의 `tools` 목록에 [`HostedMCPTool`][agents.tool.HostedMCPTool]을 추가하여 호스티드 도구를 생성합니다. `tool_config`
-딕셔너리는 REST API로 보내는 JSON을 반영합니다:
+[`HostedMCPTool`][agents.tool.HostedMCPTool]을 에이전트의 `tools` 목록에 추가하여 호스티드 툴을 만듭니다. `tool_config`
+dict는 REST API로 보낼 JSON과 동일한 구조입니다:
 
 ```python
 import asyncio
@@ -84,32 +88,36 @@ from agents import Agent, HostedMCPTool, Runner
 async def main() -> None:
     agent = Agent(
         name="Assistant",
+        instructions="Use the DeepWiki hosted MCP server to inspect openai/openai-agents-python.",
         tools=[
             HostedMCPTool(
                 tool_config={
                     "type": "mcp",
-                    "server_label": "gitmcp",
-                    "server_url": "https://gitmcp.io/openai/codex",
+                    "server_label": "deepwiki",
+                    "server_url": "https://mcp.deepwiki.com/mcp",
                     "require_approval": "never",
                 }
             )
         ],
     )
 
-    result = await Runner.run(agent, "Which language is this repository written in?")
+    result = await Runner.run(
+        agent,
+        "Which language is the repository openai/openai-agents-python written in?",
+    )
     print(result.final_output)
 
 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 결과 스트리밍
 
-호스티드 도구는 함수 도구와 정확히 동일한 방식으로 결과 스트리밍을 지원합니다. `Runner.run_streamed`를 사용해
-모델이 아직 작업 중일 때 점진적인 MCP 출력을 소비하세요:
+호스티드 툴은 함수 도구와 정확히 같은 방식으로 결과 스트리밍을 지원합니다. 모델이 아직 작업 중일 때
+증분 MCP 출력을 소비하려면 `Runner.run_streamed`를 사용하세요:
 
 ```python
 result = Runner.run_streamed(agent, "Summarise this repository's top languages")
@@ -121,13 +129,14 @@ print(result.final_output)
 
 ### 선택적 승인 흐름
 
-서버가 민감한 작업을 수행할 수 있다면 각 도구 실행 전에 사람 또는 프로그래매틱 승인을 요구할 수 있습니다. `tool_config`에서
-`require_approval`을 단일 정책(`"always"`, `"never"`) 또는 도구 이름별 정책 딕셔너리로 구성하세요. Python 내부에서 결정을 내리려면 `on_approval_request` 콜백을 제공하세요.
+서버가 민감한 작업을 수행할 수 있다면 각 도구 실행 전에 사람 또는 프로그램에 의한 승인을 요구할 수 있습니다. `tool_config`에서
+`require_approval`을 단일 정책(`"always"`, `"never"`) 또는 도구 이름을 정책에 매핑하는 dict로 구성하세요.
+Python 내부에서 결정을 내리려면 `on_approval_request` 콜백을 제공하세요.
 
 ```python
 from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest
 
-SAFE_TOOLS = {"read_project_metadata"}
+SAFE_TOOLS = {"read_wiki_structure", "read_wiki_contents", "ask_question"}
 
 def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
     if request.data.name in SAFE_TOOLS:
@@ -140,8 +149,8 @@ agent = Agent(
         HostedMCPTool(
             tool_config={
                 "type": "mcp",
-                "server_label": "gitmcp",
-                "server_url": "https://gitmcp.io/openai/codex",
+                "server_label": "deepwiki",
+                "server_url": "https://mcp.deepwiki.com/mcp",
                 "require_approval": "always",
             },
             on_approval_request=approve_tool,
@@ -150,12 +159,12 @@ agent = Agent(
 )
 ```
 
-콜백은 동기 또는 비동기일 수 있으며, 모델이 실행을 계속하기 위해 승인 데이터가 필요할 때마다 호출됩니다.
+콜백은 동기 또는 비동기일 수 있으며, 모델이 계속 실행되기 위해 승인 데이터가 필요할 때마다 호출됩니다.
 
 ### 커넥터 기반 호스티드 서버
 
-호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요. Responses
-API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다.
+호스티드 MCP는 OpenAI 커넥터도 지원합니다. `server_url`을 지정하는 대신 `connector_id`와 액세스 토큰을 제공하세요.
+Responses API가 인증을 처리하고 호스티드 서버가 커넥터의 도구를 노출합니다.
 
 ```python
 import os
@@ -171,14 +180,14 @@ HostedMCPTool(
 )
 ```
 
-스트리밍, 승인, 커넥터를 포함한 완전한 동작 예제는
+스트리밍, 승인, 커넥터를 포함해 완전히 동작하는 호스티드 툴 샘플은
 [`examples/hosted_mcp`](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp)에 있습니다.
 
 ## 2. Streamable HTTP MCP 서버
 
 네트워크 연결을 직접 관리하려면
-[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 사용하세요. Streamable HTTP 서버는 전송 계층을 제어하거나
-지연 시간을 낮게 유지하면서 자체 인프라에서 서버를 실행하려는 경우에 이상적입니다.
+[`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]를 사용하세요. Streamable HTTP 서버는 전송 방식을 제어하거나,
+낮은 지연 시간을 유지하면서 자체 인프라 내에서 서버를 실행하려는 경우에 적합합니다.
 
 ```python
 import asyncio
@@ -213,27 +222,27 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-생성자는 다음과 같은 추가 옵션을 받습니다:
+생성자는 추가 옵션을 받습니다:
 
-- `client_session_timeout_seconds`는 HTTP 읽기 타임아웃을 제어합니다
-- `use_structured_content`는 텍스트 출력보다 `tool_result.structured_content`를 우선할지 전환합니다
-- `max_retry_attempts`와 `retry_backoff_seconds_base`는 `list_tools()`와 `call_tool()`에 자동 재시도를 추가합니다
-- `tool_filter`는 도구 일부만 노출할 수 있게 합니다([도구 필터링](#tool-filtering) 참조)
-- `require_approval`은 로컬 MCP 도구에 휴먼인더루프 (HITL) 승인 정책을 활성화합니다
-- `failure_error_function`은 모델에 표시되는 MCP 도구 실패 메시지를 사용자 지정합니다. 대신 오류를 발생시키려면 `None`으로 설정하세요
-- `tool_meta_resolver`는 `call_tool()` 전에 호출별 MCP `_meta` 페이로드를 주입합니다
+- `client_session_timeout_seconds`는 HTTP 읽기 타임아웃을 제어합니다.
+- `use_structured_content`는 텍스트 출력보다 `tool_result.structured_content`를 우선할지 여부를 전환합니다.
+- `max_retry_attempts`와 `retry_backoff_seconds_base`는 `list_tools()` 및 `call_tool()`에 자동 재시도를 추가합니다.
+- `tool_filter`를 사용하면 도구의 일부만 노출할 수 있습니다([도구 필터링](#tool-filtering) 참고).
+- `require_approval`은 로컬 MCP 도구에 대한 휴먼인더루프 (HITL) 승인 정책을 활성화합니다.
+- `failure_error_function`은 모델에 표시되는 MCP 도구 실패 메시지를 사용자 지정합니다. 대신 오류를 발생시키려면 `None`으로 설정하세요.
+- `tool_meta_resolver`는 `call_tool()` 전에 호출별 MCP `_meta` 페이로드를 주입합니다.
 
-### 로컬 MCP 서버용 승인 정책
+### 로컬 MCP 서버의 승인 정책
 
-`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`는 모두 `require_approval`을 지원합니다.
+`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`는 모두 `require_approval`을 받습니다.
 
-지원 형식:
+지원되는 형식:
 
-- 모든 도구에 대해 `"always"` 또는 `"never"`
-- `True` / `False`(always/never와 동일)
-- 도구별 맵(예: `{"delete_file": "always", "read_file": "never"}`)
-- 그룹 객체:
-  `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`
+- 모든 도구에 대해 `"always"` 또는 `"never"`.
+- `True` / `False`(always/never와 동일).
+- 도구별 맵, 예: `{"delete_file": "always", "read_file": "never"}`.
+- 그룹화된 객체:
+  `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`.
 
 ```python
 async with MCPServerStreamableHttp(
@@ -244,11 +253,11 @@ async with MCPServerStreamableHttp(
     ...
 ```
 
-전체 일시정지/재개 흐름은 [휴먼인더루프](human_in_the_loop.md) 및 `examples/mcp/get_all_mcp_tools_example/main.py`를 참고하세요.
+전체 일시 중지/재개 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md) 및 `examples/mcp/get_all_mcp_tools_example/main.py`를 참고하세요.
 
 ### `tool_meta_resolver`를 사용한 호출별 메타데이터
 
-MCP 서버가 `_meta`에 요청 메타데이터(예: 테넌트 ID 또는 트레이스 컨텍스트)를 기대한다면 `tool_meta_resolver`를 사용하세요. 아래 예제는 `Runner.run(...)`에 `context`로 `dict`를 전달한다고 가정합니다.
+MCP 서버가 `_meta`에 요청 메타데이터(예: 테넌트 ID 또는 트레이스 컨텍스트)를 기대하는 경우 `tool_meta_resolver`를 사용하세요. 아래 예에서는 `Runner.run(...)`에 `context`로 `dict`를 전달한다고 가정합니다.
 
 ```python
 from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext
@@ -269,20 +278,20 @@ server = MCPServerStreamableHttp(
 )
 ```
 
-실행 컨텍스트가 Pydantic 모델, dataclass 또는 사용자 정의 클래스라면 대신 속성 접근으로 테넌트 ID를 읽으세요.
+실행 컨텍스트가 Pydantic 모델, dataclass 또는 사용자 지정 클래스인 경우 속성 접근으로 테넌트 ID를 읽으세요.
 
 ### MCP 도구 출력: 텍스트 및 이미지
 
-MCP 도구가 이미지 콘텐츠를 반환하면 SDK가 이를 이미지 도구 출력 항목으로 자동 매핑합니다. 텍스트/이미지 혼합 응답은 출력 항목 목록으로 전달되므로 에이전트는 일반 함수 도구의 이미지 출력과 동일한 방식으로 MCP 이미지 결과를 소비할 수 있습니다.
+MCP 도구가 이미지 콘텐츠를 반환하면 SDK가 이를 이미지 도구 출력 항목으로 자동 매핑합니다. 텍스트/이미지 혼합 응답은 출력 항목 목록으로 전달되므로, 에이전트는 일반 함수 도구의 이미지 출력을 소비하는 것과 같은 방식으로 MCP 이미지 결과를 소비할 수 있습니다.
 
-## 3. SSE 기반 HTTP MCP 서버
+## 3. SSE 사용 HTTP MCP 서버
 
 !!! warning
 
-    MCP 프로젝트는 Server-Sent Events 전송 방식을 더 이상 권장하지 않습니다. 새 통합에는 Streamable HTTP 또는 stdio를 우선 사용하고, SSE는 레거시 서버에만 유지하세요
+    MCP 프로젝트는 Server-Sent Events 전송 방식을 더 이상 권장하지 않습니다. 새 통합에는 Streamable HTTP 또는 stdio를 선호하고, SSE는 레거시 서버에만 유지하세요.
 
-MCP 서버가 SSE 기반 HTTP 전송 방식을 구현한 경우
-[`MCPServerSse`][agents.mcp.server.MCPServerSse]를 인스턴스화하세요. 전송 방식 외에는 API가 Streamable HTTP 서버와 동일합니다.
+MCP 서버가 SSE 사용 HTTP 전송 방식을 구현하는 경우
+[`MCPServerSse`][agents.mcp.server.MCPServerSse]를 인스턴스화하세요. 전송 방식을 제외하면 API는 Streamable HTTP 서버와 동일합니다.
 
 ```python
 
@@ -311,8 +320,9 @@ async with MCPServerSse(
 
 ## 4. stdio MCP 서버
 
-로컬 서브프로세스로 실행되는 MCP 서버에는 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 사용하세요. SDK가 프로세스를 생성하고
-파이프를 열린 상태로 유지하며, 컨텍스트 매니저가 종료되면 자동으로 닫습니다. 이 옵션은 빠른 개념 검증이나 서버가 명령줄 엔트리 포인트만 노출할 때 유용합니다.
+로컬 하위 프로세스로 실행되는 MCP 서버에는 [`MCPServerStdio`][agents.mcp.server.MCPServerStdio]를 사용하세요. SDK가
+프로세스를 생성하고 파이프를 열린 상태로 유지하며, 컨텍스트 관리자가 종료될 때 자동으로 닫습니다. 이 옵션은 빠른
+개념 증명이나 서버가 명령줄 진입점만 노출하는 경우에 유용합니다.
 
 ```python
 from pathlib import Path
@@ -338,10 +348,10 @@ async with MCPServerStdio(
     print(result.final_output)
 ```
 
-## 5. MCP 서버 매니저
+## 5. MCP 서버 관리자
 
-여러 MCP 서버가 있는 경우 `MCPServerManager`를 사용해 미리 연결하고, 연결된 하위 집합을 에이전트에 노출하세요.
-생성자 옵션과 재연결 동작은 [MCPServerManager API 참조](ref/mcp/manager.md)를 참고하세요.
+여러 MCP 서버가 있는 경우 `MCPServerManager`를 사용하여 미리 연결하고 연결된 하위 집합을 에이전트에 노출하세요.
+생성자 옵션과 재연결 동작은 [MCPServerManager API 참조](ref/mcp/manager.md)를 확인하세요.
 
 ```python
 from agents import Agent, Runner
@@ -362,22 +372,22 @@ async with MCPServerManager(servers) as manager:
     print(result.final_output)
 ```
 
-핵심 동작:
+주요 동작:
 
-- `drop_failed_servers=True`(기본값)일 때 `active_servers`에는 연결에 성공한 서버만 포함됩니다
-- 실패는 `failed_servers`와 `errors`에 추적됩니다
-- 첫 연결 실패에서 예외를 발생시키려면 `strict=True`로 설정하세요
-- 실패한 서버만 재시도하려면 `reconnect(failed_only=True)`, 모든 서버를 재시작하려면 `reconnect(failed_only=False)`를 호출하세요
-- 라이프사이클 동작을 조정하려면 `connect_timeout_seconds`, `cleanup_timeout_seconds`, `connect_in_parallel`을 사용하세요
+- `drop_failed_servers=True`(기본값)인 경우 `active_servers`에는 성공적으로 연결된 서버만 포함됩니다.
+- 실패는 `failed_servers`와 `errors`에 추적됩니다.
+- 첫 번째 연결 실패 시 오류를 발생시키려면 `strict=True`를 설정하세요.
+- 실패한 서버를 다시 시도하려면 `reconnect(failed_only=True)`를 호출하고, 모든 서버를 다시 시작하려면 `reconnect(failed_only=False)`를 호출하세요.
+- 수명 주기 동작을 조정하려면 `connect_timeout_seconds`, `cleanup_timeout_seconds`, `connect_in_parallel`을 사용하세요.
 
 ## 공통 서버 기능
 
-아래 섹션은 MCP 서버 전송 방식 전반에 적용됩니다(API 표면은 서버 클래스에 따라 정확히 달라질 수 있음).
+아래 섹션은 MCP 서버 전송 방식 전반에 적용됩니다(정확한 API 표면은 서버 클래스에 따라 다름).
 
 ## 도구 필터링
 
 각 MCP 서버는 도구 필터를 지원하므로 에이전트에 필요한 함수만 노출할 수 있습니다. 필터링은
-생성 시점이나 실행별 동적으로 수행할 수 있습니다.
+생성 시점에 수행하거나 실행별로 동적으로 수행할 수 있습니다.
 
 ### 정적 도구 필터링
 
@@ -399,13 +409,13 @@ filesystem_server = MCPServerStdio(
 )
 ```
 
-`allowed_tool_names`와 `blocked_tool_names`가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 뒤, 남은 집합에서
+`allowed_tool_names`와 `blocked_tool_names`가 모두 제공되면 SDK는 먼저 허용 목록을 적용한 다음 남은 집합에서
 차단된 도구를 제거합니다.
 
 ### 동적 도구 필터링
 
-더 정교한 로직이 필요하면 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 callable을 전달하세요. 해당 callable은
-동기 또는 비동기일 수 있으며, 도구를 노출해야 하면 `True`를 반환합니다.
+더 정교한 로직이 필요하면 [`ToolFilterContext`][agents.mcp.ToolFilterContext]를 받는 콜러블을 전달하세요. 이 콜러블은
+동기 또는 비동기일 수 있으며, 도구가 노출되어야 하는 경우 `True`를 반환합니다.
 
 ```python
 from pathlib import Path
@@ -429,15 +439,15 @@ async with MCPServerStdio(
     ...
 ```
 
-필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, `server_name`을 노출합니다.
+필터 컨텍스트는 활성 `run_context`, 도구를 요청하는 `agent`, 그리고 `server_name`을 노출합니다.
 
 ## 프롬프트
 
-MCP 서버는 에이전트 instructions를 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지
+MCP 서버는 에이전트 지침을 동적으로 생성하는 프롬프트도 제공할 수 있습니다. 프롬프트를 지원하는 서버는 두 가지
 메서드를 노출합니다:
 
-- `list_prompts()`는 사용 가능한 프롬프트 템플릿을 열거합니다
-- `get_prompt(name, arguments)`는 선택적으로 매개변수와 함께 구체적인 프롬프트를 가져옵니다
+- `list_prompts()`는 사용 가능한 프롬프트 템플릿을 열거합니다.
+- `get_prompt(name, arguments)`는 선택적으로 매개변수를 포함해 구체적인 프롬프트를 가져옵니다.
 
 ```python
 from agents import Agent
@@ -457,21 +467,20 @@ agent = Agent(
 
 ## 캐싱
 
-모든 에이전트 실행은 각 MCP 서버에서 `list_tools()`를 호출합니다. 원격 서버는 눈에 띄는 지연 시간을 유발할 수 있으므로 모든 MCP
-서버 클래스는 `cache_tools_list` 옵션을 노출합니다. 도구 정의가 자주
-변경되지 않는다고 확신할 때만 이를 `True`로 설정하세요. 나중에 최신 목록을 강제로 가져오려면 서버 인스턴스에서 `invalidate_tools_cache()`를 호출하세요.
+모든 에이전트 실행은 각 MCP 서버에서 `list_tools()`를 호출합니다. 원격 서버는 눈에 띄는 지연 시간을 유발할 수 있으므로, 모든 MCP
+서버 클래스는 `cache_tools_list` 옵션을 노출합니다. 도구 정의가 자주 변경되지 않는다고 확신하는 경우에만 이를 `True`로 설정하세요. 나중에 새 목록을 강제로 가져오려면 서버 인스턴스에서 `invalidate_tools_cache()`를 호출하세요.
 
 ## 트레이싱
 
-[트레이싱](./tracing.md)은 다음을 포함해 MCP 활동을 자동으로 수집합니다:
+[트레이싱](./tracing.md)은 다음을 포함한 MCP 활동을 자동으로 캡처합니다:
 
-1. 도구 목록 조회를 위한 MCP 서버 호출
-2. 도구 호출의 MCP 관련 정보
+1. 도구를 나열하기 위한 MCP 서버 호출.
+2. 도구 호출의 MCP 관련 정보.
 
-![MCP Tracing Screenshot](../assets/images/mcp-tracing.jpg)
+![MCP 트레이싱 스크린샷](../assets/images/mcp-tracing.jpg)
 
-## 추가 읽을거리
+## 추가 자료
 
-- [Model Context Protocol](https://modelcontextprotocol.io/) – 명세 및 설계 가이드
-- [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp) – 실행 가능한 stdio, SSE, Streamable HTTP 샘플
-- [examples/hosted_mcp](https://github.com/openai/openai-agents-python/tree/main/examples/hosted_mcp) – 승인 및 커넥터를 포함한 완전한 호스티드 MCP 데모
+- [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 데모.

docs/ko/models/index.md

@@ -4,35 +4,35 @@ search:
 ---
 # 모델
 
-Agents SDK는 OpenAI 모델을 두 가지 방식으로 즉시 사용할 수 있도록 지원합니다.
+Agents SDK는 두 가지 방식으로 OpenAI 모델을 기본 지원합니다.
 
--   **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용해 OpenAI API를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]
--   [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용해 OpenAI API를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]
+-   **권장**: 새로운 [Responses API](https://platform.openai.com/docs/api-reference/responses)를 사용하여 OpenAI API를 호출하는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]
+-   [Chat Completions API](https://platform.openai.com/docs/api-reference/chat)를 사용하여 OpenAI API를 호출하는 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]
 
 ## 모델 설정 선택
 
 설정에 맞는 가장 단순한 경로부터 시작하세요.
 
-| 원하는 작업 | 권장 경로 | 더 읽기 |
+| 수행하려는 작업 | 권장 경로 | 더 읽기 |
 | --- | --- | --- |
-| OpenAI 모델만 사용 | Responses 모델 경로와 함께 기본 OpenAI provider 사용 | [OpenAI 모델](#openai-models) |
+| OpenAI 모델만 사용 | Responses 모델 경로와 함께 기본 OpenAI 프로바이더 사용 | [OpenAI 모델](#openai-models) |
 | websocket 전송으로 OpenAI Responses API 사용 | Responses 모델 경로를 유지하고 websocket 전송 활성화 | [Responses WebSocket 전송](#responses-websocket-transport) |
-| OpenAI가 아닌 provider 하나 사용 | 기본 제공 provider 통합 지점부터 시작 | [OpenAI 외 모델](#non-openai-models) |
-| 에이전트 전반에서 모델 또는 provider 혼합 | 실행별 또는 에이전트별로 provider를 선택하고 기능 차이를 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [provider 전반에서 모델 혼합](#mixing-models-across-providers) |
+| 하나의 비 OpenAI 프로바이더 사용 | 내장 프로바이더 통합 지점부터 시작 | [비 OpenAI 모델](#non-openai-models) |
+| 에이전트 간 모델 또는 프로바이더 혼합 | 실행별 또는 에이전트별로 프로바이더를 선택하고 기능 차이 검토 | [하나의 워크플로에서 모델 혼합](#mixing-models-in-one-workflow) 및 [프로바이더 간 모델 혼합](#mixing-models-across-providers) |
 | 고급 OpenAI Responses 요청 설정 조정 | OpenAI Responses 경로에서 `ModelSettings` 사용 | [고급 OpenAI Responses 설정](#advanced-openai-responses-settings) |
-| OpenAI 외 또는 혼합 provider 라우팅에 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 출시하려는 provider 경로 검증 | [서드파티 어댑터](#third-party-adapters) |
+| 비 OpenAI 또는 혼합 프로바이더 라우팅을 위한 서드파티 어댑터 사용 | 지원되는 베타 어댑터를 비교하고 배포하려는 프로바이더 경로 검증 | [서드파티 어댑터](#third-party-adapters) |
 
 ## OpenAI 모델
 
-대부분의 OpenAI 전용 앱에서는 기본 OpenAI provider와 함께 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것을 권장합니다.
+대부분의 OpenAI 전용 앱에서는 기본 OpenAI 프로바이더와 함께 문자열 모델 이름을 사용하고 Responses 모델 경로를 유지하는 것이 권장됩니다.
 
-`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1)입니다. 액세스 권한이 있다면 명시적인 `model_settings`를 유지하면서 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하는 것을 권장합니다.
+`Agent`를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 지연 시간이 낮은 에이전트 워크플로를 위해 `reasoning.effort="none"` 및 `verbosity="low"`가 적용된 [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini)입니다. 접근 권한이 있다면 더 높은 품질을 위해 에이전트를 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5)로 설정하되 명시적인 `model_settings`를 유지하는 것을 권장합니다.
 
-[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법이 두 가지 있습니다.
+[`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 다른 모델로 전환하려면 두 가지 방법으로 에이전트를 구성할 수 있습니다.
 
 ### 기본 모델
 
-먼저, 사용자 지정 모델을 설정하지 않은 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
+첫째, 사용자 지정 모델을 설정하지 않는 모든 에이전트에 특정 모델을 일관되게 사용하려면 에이전트를 실행하기 전에 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
 
 ```bash
 export OPENAI_DEFAULT_MODEL=gpt-5.5
@@ -58,7 +58,7 @@ result = await Runner.run(
 
 #### GPT-5 모델
 
-이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 GPT-5 모델을 사용하면 SDK는 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에 가장 잘 맞는 값들이 설정됩니다. 기본 모델의 reasoning effort를 조정하려면 자체 `ModelSettings`를 전달하세요.
+이 방식으로 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 같은 GPT-5 모델을 사용하면 SDK는 기본 `ModelSettings`를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 값을 설정합니다. 기본 모델의 추론 노력을 조정하려면 직접 만든 `ModelSettings`를 전달하세요.
 
 ```python
 from openai.types.shared import Reasoning
@@ -74,21 +74,21 @@ my_agent = Agent(
 )
 ```
 
-더 낮은 지연 시간을 위해서는 `gpt-5.5`와 함께 `reasoning.effort="none"`을 사용하는 것을 권장합니다. gpt-4.1 계열(mini 및 nano 변형 포함)도 인터랙티브 에이전트 앱을 구축하는 데 여전히 좋은 선택입니다.
+지연 시간을 낮추려면 GPT-5 모델에 `reasoning.effort="none"`을 사용하는 것이 권장됩니다.
 
 #### ComputerTool 모델 선택
 
-에이전트가 [`ComputerTool`][agents.tool.ComputerTool]을 포함하는 경우, 실제 Responses 요청에서 유효한 모델이 SDK가 전송하는 computer-tool 페이로드를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 기본 제공 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` 페이로드를 유지합니다.
+에이전트에 [`ComputerTool`][agents.tool.ComputerTool]이 포함되어 있으면 실제 Responses 요청에서 유효한 모델이 SDK가 전송하는 컴퓨터 도구 페이로드를 결정합니다. 명시적인 `gpt-5.5` 요청은 GA 내장 `computer` 도구를 사용하고, 명시적인 `computer-use-preview` 요청은 이전 `computer_use_preview` 페이로드를 유지합니다.
 
-프롬프트 관리 호출이 주된 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않도록 preview 호환 computer 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하세요.
+프롬프트 관리형 호출은 주요 예외입니다. 프롬프트 템플릿이 모델을 소유하고 SDK가 요청에서 `model`을 생략하는 경우, SDK는 프롬프트가 어떤 모델을 고정하는지 추측하지 않도록 프리뷰 호환 컴퓨터 페이로드를 기본값으로 사용합니다. 이 흐름에서 GA 경로를 유지하려면 요청에 `model="gpt-5.5"`를 명시하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하세요.
 
-등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효한 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. 등록된 `ComputerTool`이 없으면 이러한 문자열은 일반 함수 이름처럼 계속 동작합니다.
+등록된 [`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`는 유효한 요청 모델과 일치하는 내장 선택자로 정규화됩니다. `ComputerTool`이 등록되어 있지 않으면 이러한 문자열은 일반 함수 이름처럼 계속 동작합니다.
 
-Preview 호환 요청은 `environment`와 표시 크기를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩터리를 사용하는 프롬프트 관리 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA 선택기를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참고하세요.
+프리뷰 호환 요청은 `environment`와 표시 크기를 미리 직렬화해야 하므로, [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리를 사용하는 프롬프트 관리형 흐름은 구체적인 `Computer` 또는 `AsyncComputer` 인스턴스를 전달하거나 요청을 보내기 전에 GA 선택자를 강제해야 합니다. 전체 마이그레이션 세부 정보는 [도구](../tools.md#computertool-and-the-responses-computer-tool)를 참조하세요.
 
-#### GPT-5 외 모델
+#### 비 GPT-5 모델
 
-사용자 지정 `model_settings` 없이 GPT-5가 아닌 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다.
+사용자 지정 `model_settings` 없이 비 GPT-5 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 `ModelSettings`로 되돌아갑니다.
 
 ### Responses 전용 도구 검색 기능
 
@@ -98,11 +98,11 @@ Preview 호환 요청은 `environment`와 표시 크기를 미리 직렬화해
 -   [`tool_namespace()`][agents.tool.tool_namespace]
 -   `@function_tool(defer_loading=True)` 및 기타 지연 로딩 Responses 도구 표면
 
-이러한 기능은 Chat Completions 모델 및 Responses가 아닌 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 모델이 bare namespace 이름이나 지연 전용 함수 이름을 강제하는 대신 `auto` 또는 `required` 도구 선택을 통해 도구를 로드하게 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참고하세요.
+이러한 기능은 Chat Completions 모델과 비 Responses 백엔드에서 거부됩니다. 지연 로딩 도구를 사용할 때는 에이전트에 `ToolSearchTool()`을 추가하고, 단순 네임스페이스 이름이나 지연 전용 함수 이름을 강제로 지정하는 대신 모델이 `auto` 또는 `required` 도구 선택을 통해 도구를 로드하도록 하세요. 설정 세부 정보와 현재 제약 사항은 [도구](../tools.md#hosted-tool-search)를 참조하세요.
 
 ### Responses WebSocket 전송
 
-기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델을 사용할 때 websocket 전송을 선택할 수 있습니다.
+기본적으로 OpenAI Responses API 요청은 HTTP 전송을 사용합니다. OpenAI 기반 모델을 사용할 때 websocket 전송을 선택적으로 사용할 수 있습니다.
 
 #### 기본 설정
 
@@ -112,13 +112,13 @@ from agents import set_default_openai_responses_transport
 set_default_openai_responses_transport("websocket")
 ```
 
-이는 기본 OpenAI provider가 해석한 OpenAI Responses 모델(예: `"gpt-5.5"` 같은 문자열 모델 이름 포함)에 영향을 줍니다.
+이는 기본 OpenAI 프로바이더가 해석하는 OpenAI Responses 모델에 영향을 줍니다(`"gpt-5.5"` 같은 문자열 모델 이름 포함).
 
-전송 선택은 SDK가 모델 이름을 모델 인스턴스로 해석할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 전송은 이미 고정되어 있습니다. [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket을 사용하고, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP를 사용하며, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions에 머뭅니다. `RunConfig(model_provider=...)`를 전달하면 전역 기본값 대신 해당 provider가 전송 선택을 제어합니다.
+전송 선택은 SDK가 모델 이름을 모델 인스턴스로 해석할 때 발생합니다. 구체적인 [`Model`][agents.models.interface.Model] 객체를 전달하면 해당 전송은 이미 고정되어 있습니다. [`OpenAIResponsesWSModel`][agents.models.openai_responses.OpenAIResponsesWSModel]은 websocket을 사용하고, [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]은 HTTP를 사용하며, [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]은 Chat Completions를 유지합니다. `RunConfig(model_provider=...)`를 전달하면 전역 기본값 대신 해당 프로바이더가 전송 선택을 제어합니다.
 
-#### Provider 또는 실행 수준 설정
+#### 프로바이더 또는 실행 수준 설정
 
-provider별 또는 실행별로 websocket 전송을 구성할 수도 있습니다.
+프로바이더별 또는 실행별로 websocket 전송을 구성할 수도 있습니다.
 
 ```python
 from agents import Agent, OpenAIProvider, RunConfig, Runner
@@ -127,6 +127,8 @@ provider = OpenAIProvider(
     use_responses_websocket=True,
     # Optional; if omitted, OPENAI_WEBSOCKET_BASE_URL is used when set.
     websocket_base_url="wss://your-proxy.example/v1",
+    # Optional low-level websocket keepalive settings.
+    responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
 )
 
 agent = Agent(name="Assistant")
@@ -137,7 +139,7 @@ result = await Runner.run(
 )
 ```
 
-OpenAI 기반 provider는 선택적 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정에서 harness ID와 같은 provider 수준 등록 메타데이터가 필요한 경우를 위한 고급 옵션입니다.
+OpenAI 기반 프로바이더는 선택적 에이전트 등록 구성도 허용합니다. 이는 OpenAI 설정이 하니스 ID 같은 프로바이더 수준 등록 메타데이터를 기대하는 경우를 위한 고급 옵션입니다.
 
 ```python
 from agents import (
@@ -163,14 +165,14 @@ result = await Runner.run(
 
 #### `MultiProvider`를 사용한 고급 라우팅
 
-접두사 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...`와 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 그곳에서 `openai_use_responses_websocket=True`를 설정하세요.
+접두사 기반 모델 라우팅이 필요한 경우(예: 하나의 실행에서 `openai/...` 및 `any-llm/...` 모델 이름 혼합) [`MultiProvider`][agents.MultiProvider]를 사용하고 그곳에서 `openai_use_responses_websocket=True`를 설정하세요.
 
 `MultiProvider`는 두 가지 기존 기본값을 유지합니다.
 
--   `openai/...`는 OpenAI provider의 별칭으로 취급되므로, `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다.
+-   `openai/...`는 OpenAI 프로바이더의 별칭으로 처리되므로 `openai/gpt-4.1`은 모델 `gpt-4.1`로 라우팅됩니다.
 -   알 수 없는 접두사는 그대로 전달되지 않고 `UserError`를 발생시킵니다.
 
-OpenAI provider가 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키는 경우, pass-through 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요.
+OpenAI 프로바이더가 리터럴 네임스페이스 모델 ID를 기대하는 OpenAI 호환 엔드포인트를 가리키는 경우, 패스스루 동작을 명시적으로 선택하세요. websocket이 활성화된 설정에서는 `MultiProvider`에도 `openai_use_responses_websocket=True`를 유지하세요.
 
 ```python
 from agents import Agent, MultiProvider, RunConfig, Runner
@@ -196,38 +198,39 @@ result = await Runner.run(
 )
 ```
 
-백엔드가 리터럴 `openai/...` 문자열을 기대할 때 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대할 때 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket 전송 외부의 `MultiProvider`에서도 작동합니다. 이 예시는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다.
+백엔드가 리터럴 `openai/...` 문자열을 기대하는 경우 `openai_prefix_mode="model_id"`를 사용하세요. 백엔드가 `openrouter/openai/gpt-4.1-mini` 같은 다른 네임스페이스 모델 ID를 기대하는 경우 `unknown_prefix_mode="model_id"`를 사용하세요. 이러한 옵션은 websocket 전송 외부의 `MultiProvider`에서도 작동합니다. 이 예제에서는 이 섹션에서 설명한 전송 설정의 일부이므로 websocket을 활성화한 상태로 유지합니다. 동일한 옵션은 [`responses_websocket_session()`][agents.responses_websocket_session]에서도 사용할 수 있습니다.
 
-`MultiProvider`를 통해 라우팅하면서 동일한 provider 수준 등록 메타데이터가 필요하면 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 기본 OpenAI provider로 전달됩니다.
+`MultiProvider`를 통해 라우팅하면서 동일한 프로바이더 수준 등록 메타데이터가 필요한 경우 `openai_agent_registration=OpenAIAgentRegistrationConfig(...)`를 전달하면 기본 OpenAI 프로바이더로 전달됩니다.
 
-사용자 지정 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우, websocket 전송에도 호환되는 websocket `/responses` 엔드포인트가 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다.
+사용자 지정 OpenAI 호환 엔드포인트나 프록시를 사용하는 경우 websocket 전송에는 호환되는 websocket `/responses` 엔드포인트도 필요합니다. 이러한 설정에서는 `websocket_base_url`을 명시적으로 설정해야 할 수 있습니다.
 
 #### 참고 사항
 
--   이는 websocket 전송을 통한 Responses API이며, [Realtime API](../realtime/guide.md)가 아닙니다. Chat Completions 또는 OpenAI가 아닌 provider에는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 한 적용되지 않습니다.
--   환경에서 아직 사용할 수 없다면 `websockets` 패키지를 설치하세요.
--   websocket 전송을 활성화한 뒤 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 여러 턴에 걸친 워크플로에서 같은 websocket 연결을 턴 간(및 중첩된 agent-as-tool 호출 간)에 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼를 권장합니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참고하세요.
+-   이것은 [Realtime API](../realtime/guide.md)가 아니라 websocket 전송을 통한 Responses API입니다. Chat Completions나 비 OpenAI 프로바이더에는 Responses websocket `/responses` 엔드포인트를 지원하지 않는 한 적용되지 않습니다.
+-   환경에 아직 없다면 `websockets` 패키지를 설치하세요.
+-   websocket 전송을 활성화한 후 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 직접 사용할 수 있습니다. 여러 턴의 워크플로에서 같은 websocket 연결을 여러 턴(및 중첩된 agent-as-tool 호출)에 걸쳐 재사용하려면 [`responses_websocket_session()`][agents.responses_websocket_session] 헬퍼가 권장됩니다. [에이전트 실행](../running_agents.md) 가이드와 [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py)를 참조하세요.
+-   긴 추론 턴이나 지연 시간 급증이 있는 네트워크의 경우 `responses_websocket_options`로 websocket keepalive 동작을 사용자 지정하세요. 지연된 pong 프레임을 허용하려면 `ping_timeout`을 늘리거나, ping은 활성화한 상태로 heartbeat 시간 제한을 비활성화하려면 `ping_timeout=None`을 설정하세요. websocket 지연 시간보다 안정성이 더 중요한 경우 HTTP/SSE 전송을 선호하세요.
 
-## OpenAI 외 모델
+## 비 OpenAI 모델
 
-OpenAI가 아닌 provider가 필요한 경우 SDK의 기본 제공 provider 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 이것으로 충분합니다. 각 패턴의 예시는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다.
+비 OpenAI 프로바이더가 필요한 경우 SDK의 내장 프로바이더 통합 지점부터 시작하세요. 많은 설정에서는 서드파티 어댑터를 추가하지 않아도 이것만으로 충분합니다. 각 패턴의 코드 예제는 [examples/model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다.
 
-### OpenAI 외 provider 통합 방법
+### 비 OpenAI 프로바이더 통합 방법
 
 | 접근 방식 | 사용 시점 | 범위 |
 | --- | --- | --- |
 | [`set_default_openai_client`][agents.set_default_openai_client] | 하나의 OpenAI 호환 엔드포인트가 대부분 또는 모든 에이전트의 기본값이어야 하는 경우 | 전역 기본값 |
-| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 provider를 단일 실행에 적용해야 하는 경우 | 실행별 |
-| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트가 다른 provider 또는 구체적인 모델 객체를 필요로 하는 경우 | 에이전트별 |
-| 서드파티 어댑터 | 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우 | [서드파티 어댑터](#third-party-adapters) 참고 |
+| [`ModelProvider`][agents.models.interface.ModelProvider] | 하나의 사용자 지정 프로바이더가 단일 실행에 적용되어야 하는 경우 | 실행별 |
+| [`Agent.model`][agents.agent.Agent.model] | 서로 다른 에이전트에 서로 다른 프로바이더 또는 구체적인 모델 객체가 필요한 경우 | 에이전트별 |
+| 서드파티 어댑터 | 내장 경로가 제공하지 않는 어댑터 관리형 프로바이더 범위 또는 라우팅이 필요한 경우 | [서드파티 어댑터](#third-party-adapters) 참조 |
 
-다음 기본 제공 경로를 통해 다른 LLM provider를 통합할 수 있습니다.
+다음 내장 경로를 사용하여 다른 LLM 프로바이더를 통합할 수 있습니다.
 
-1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역적으로 사용하고 싶은 경우에 유용합니다. 이는 LLM provider가 OpenAI 호환 API 엔드포인트를 가지고 있고, `base_url` 및 `api_key`를 설정할 수 있는 경우를 위한 것입니다. 구성 가능한 예시는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)를 참고하세요.
-2. [`ModelProvider`][agents.models.interface.ModelProvider]는 `Runner.run` 수준에 있습니다. 이를 통해 "이 실행의 모든 에이전트에 사용자 지정 모델 provider를 사용"하도록 지정할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)를 참고하세요.
-3. [`Agent.model`][agents.agent.Agent.model]을 사용하면 특정 Agent 인스턴스에 모델을 지정할 수 있습니다. 이를 통해 서로 다른 에이전트에 대해 서로 다른 provider를 혼합해 사용할 수 있습니다. 구성 가능한 예시는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)를 참고하세요.
+1. [`set_default_openai_client`][agents.set_default_openai_client]는 `AsyncOpenAI` 인스턴스를 LLM 클라이언트로 전역적으로 사용하려는 경우에 유용합니다. 이는 LLM 프로바이더에 OpenAI 호환 API 엔드포인트가 있고 `base_url` 및 `api_key`를 설정할 수 있는 경우를 위한 것입니다. 구성 가능한 예제는 [examples/model_providers/custom_example_global.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_global.py)를 참조하세요.
+2. [`ModelProvider`][agents.models.interface.ModelProvider]는 `Runner.run` 수준에 있습니다. 이를 통해 “이 실행의 모든 에이전트에 사용자 지정 모델 프로바이더를 사용”하도록 지정할 수 있습니다. 구성 가능한 예제는 [examples/model_providers/custom_example_provider.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_provider.py)를 참조하세요.
+3. [`Agent.model`][agents.agent.Agent.model]을 사용하면 특정 Agent 인스턴스의 모델을 지정할 수 있습니다. 이를 통해 에이전트별로 서로 다른 프로바이더를 자유롭게 조합할 수 있습니다. 구성 가능한 예제는 [examples/model_providers/custom_example_agent.py](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/custom_example_agent.py)를 참조하세요.
 
-`platform.openai.com`의 API 키가 없는 경우 `set_tracing_disabled()`로 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다.
+`platform.openai.com`의 API 키가 없는 경우 `set_tracing_disabled()`를 통해 트레이싱을 비활성화하거나 [다른 트레이싱 프로세서](../tracing.md)를 설정하는 것을 권장합니다.
 
 ``` python
 from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
@@ -242,19 +245,19 @@ agent= Agent(name="Helping Agent", instructions="You are a Helping Agent", model
 
 !!! note
 
-    이 예시들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM provider가 아직 Responses API를 지원하지 않기 때문입니다. LLM provider가 이를 지원한다면 Responses 사용을 권장합니다.
+    이 예제들에서는 Chat Completions API/모델을 사용합니다. 많은 LLM 프로바이더가 아직 Responses API를 지원하지 않기 때문입니다. 사용 중인 LLM 프로바이더가 이를 지원한다면 Responses 사용을 권장합니다.
 
 ## 하나의 워크플로에서 모델 혼합
 
-단일 워크플로 내에서 각 에이전트마다 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어 triage에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 성능이 뛰어난 모델을 사용할 수 있습니다. [`Agent`][agents.Agent]를 구성할 때는 다음 중 하나로 특정 모델을 선택할 수 있습니다.
+단일 워크플로 내에서 각 에이전트에 서로 다른 모델을 사용하고 싶을 수 있습니다. 예를 들어, 분류에는 더 작고 빠른 모델을 사용하고 복잡한 작업에는 더 크고 유능한 모델을 사용할 수 있습니다. [`Agent`][agents.Agent]를 구성할 때 다음 중 하나로 특정 모델을 선택할 수 있습니다.
 
 1. 모델 이름 전달
-2. 임의의 모델 이름 + 해당 이름을 Model 인스턴스에 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider] 전달
-3. [`Model`][agents.models.interface.Model] 구현 직접 제공
+2. 해당 이름을 Model 인스턴스에 매핑할 수 있는 [`ModelProvider`][agents.models.interface.ModelProvider]와 함께 임의의 모델 이름 전달
+3. [`Model`][agents.models.interface.Model] 구현을 직접 제공
 
 !!! note
 
-    SDK는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]과 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태가 서로 다른 기능 및 도구 집합을 지원하므로 각 워크플로에는 단일 모델 형태를 사용하는 것을 권장합니다. 워크플로에서 모델 형태를 혼합해야 하는 경우, 사용하는 모든 기능이 양쪽 모두에서 제공되는지 확인하세요.
+    SDK는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 및 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 형태를 모두 지원하지만, 두 형태가 서로 다른 기능 및 도구 집합을 지원하므로 각 워크플로에는 단일 모델 형태를 사용하는 것을 권장합니다. 워크플로에서 모델 형태를 혼합해야 하는 경우, 사용 중인 모든 기능을 양쪽 모두에서 사용할 수 있는지 확인하세요.
 
 ```python
 from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
@@ -290,7 +293,7 @@ async def main():
 1.  OpenAI 모델 이름을 직접 설정합니다.
 2.  [`Model`][agents.models.interface.Model] 구현을 제공합니다.
 
-에이전트에 사용되는 모델을 더 세부적으로 구성하려면 temperature와 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다.
+에이전트에 사용되는 모델을 더 세부적으로 구성하려면 temperature 같은 선택적 모델 구성 매개변수를 제공하는 [`ModelSettings`][agents.models.interface.ModelSettings]를 전달할 수 있습니다.
 
 ```python
 from agents import Agent, ModelSettings
@@ -309,15 +312,16 @@ OpenAI Responses 경로를 사용 중이고 더 많은 제어가 필요하다면
 
 ### 일반적인 고급 `ModelSettings` 옵션
 
-OpenAI Responses API를 사용할 때는 여러 요청 필드가 이미 직접적인 `ModelSettings` 필드로 제공되므로, 해당 필드에는 `extra_args`가 필요하지 않습니다.
+OpenAI Responses API를 사용할 때 여러 요청 필드는 이미 직접적인 `ModelSettings` 필드를 갖고 있으므로 해당 필드에는 `extra_args`가 필요하지 않습니다.
 
 - `parallel_tool_calls`: 같은 턴에서 여러 도구 호출을 허용하거나 금지합니다.
-- `truncation`: context가 넘칠 때 실패하는 대신 Responses API가 가장 오래된 대화 항목을 삭제하도록 `"auto"`를 설정합니다.
-- `store`: 생성된 응답을 나중에 조회할 수 있도록 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와, `store=False`일 때 로컬 입력으로 fallback해야 할 수 있는 세션 압축 흐름에 중요합니다.
-- `prompt_cache_retention`: 예를 들어 `"24h"`로 캐시된 프롬프트 접두사를 더 오래 유지합니다.
-- `response_include`: `web_search_call.action.sources`, `file_search_call.results` 또는 `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다.
-- `top_logprobs`: 출력 텍스트의 상위 토큰 logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다.
-- `retry`: 모델 호출에 대해 runner 관리 재시도 설정을 사용합니다. [Runner 관리 재시도](#runner-managed-retries)를 참고하세요.
+- `truncation`: 컨텍스트가 초과되어 실패하는 대신 Responses API가 가장 오래된 대화 항목을 삭제하도록 하려면 `"auto"`를 설정합니다.
+- `store`: 생성된 응답을 나중에 검색할 수 있도록 서버 측에 저장할지 제어합니다. 이는 응답 ID에 의존하는 후속 워크플로와, `store=False`일 때 로컬 입력으로 폴백해야 할 수 있는 세션 압축 흐름에 중요합니다.
+- `context_management`: `compact_threshold`를 사용하는 Responses 압축 같은 서버 측 컨텍스트 처리를 구성합니다.
+- `prompt_cache_retention`: 예를 들어 `"24h"`를 사용해 캐시된 프롬프트 접두사를 더 오래 유지합니다.
+- `response_include`: `web_search_call.action.sources`, `file_search_call.results`, `reasoning.encrypted_content` 같은 더 풍부한 응답 페이로드를 요청합니다.
+- `top_logprobs`: 출력 텍스트에 대한 상위 토큰 logprobs를 요청합니다. SDK는 `message.output_text.logprobs`도 자동으로 추가합니다.
+- `retry`: 모델 호출에 대해 러너 관리형 재시도 설정을 선택적으로 사용합니다. [Runner 관리형 재시도](#runner-managed-retries)를 참조하세요.
 
 ```python
 from agents import Agent, ModelSettings
@@ -329,6 +333,7 @@ research_agent = Agent(
         parallel_tool_calls=False,
         truncation="auto",
         store=True,
+        context_management=[{"type": "compaction", "compact_threshold": 200000}],
         prompt_cache_retention="24h",
         response_include=["web_search_call.action.sources"],
         top_logprobs=5,
@@ -336,13 +341,15 @@ research_agent = Agent(
 )
 ```
 
-`store=False`를 설정하면 Responses API는 해당 응답을 나중에 서버 측에서 조회할 수 있도록 보관하지 않습니다. 이는 stateless 또는 zero-data-retention 스타일 흐름에 유용하지만, 응답 ID를 재사용하던 기능이 대신 로컬로 관리되는 상태에 의존해야 한다는 뜻이기도 합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않은 경우 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [세션 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참고하세요.
+`store=False`를 설정하면 Responses API는 해당 응답을 나중에 서버 측에서 검색할 수 있도록 보관하지 않습니다. 이는 상태 비저장 또는 제로 데이터 보존 스타일의 흐름에 유용하지만, 그렇지 않으면 응답 ID를 재사용할 기능들이 대신 로컬에서 관리되는 상태에 의존해야 함을 의미하기도 합니다. 예를 들어 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]은 마지막 응답이 저장되지 않은 경우 기본 `"auto"` 압축 경로를 입력 기반 압축으로 전환합니다. [세션 가이드](../sessions/index.md#openai-responses-compaction-sessions)를 참조하세요.
+
+서버 측 압축은 [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]과 다릅니다. `context_management=[{"type": "compaction", "compact_threshold": ...}]`는 각 Responses API 요청과 함께 전송되며, 렌더링된 컨텍스트가 임계값을 넘을 때 API가 응답의 일부로 압축 항목을 내보낼 수 있습니다. `OpenAIResponsesCompactionSession`은 턴 사이에 독립형 `responses.compact` 엔드포인트를 호출하고 로컬 세션 기록을 다시 작성합니다.
 
 ### `extra_args` 전달
 
-SDK가 아직 최상위 수준에서 직접 노출하지 않는 provider별 또는 최신 요청 필드가 필요할 때 `extra_args`를 사용하세요.
+SDK가 아직 최상위 수준에서 직접 노출하지 않는 프로바이더별 또는 최신 요청 필드가 필요할 때 `extra_args`를 사용하세요.
 
-또한 OpenAI의 Responses API를 사용할 때는 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 최상위 수준에서 사용할 수 없다면 `extra_args`를 사용해 전달할 수도 있습니다.
+또한 OpenAI의 Responses API를 사용할 때 [몇 가지 다른 선택적 매개변수](https://platform.openai.com/docs/api-reference/responses/create)(예: `user`, `service_tier` 등)가 있습니다. 이러한 매개변수가 최상위 수준에서 제공되지 않는 경우 `extra_args`를 사용해 전달할 수 있습니다. 동일한 요청 필드를 직접적인 `ModelSettings` 필드를 통해 동시에 설정하지 마세요.
 
 ```python
 from agents import Agent, ModelSettings
@@ -358,9 +365,9 @@ english_agent = Agent(
 )
 ```
 
-## Runner 관리 재시도
+## Runner 관리형 재시도
 
-재시도는 런타임 전용이며 명시적으로 사용해야 합니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않는 한, SDK는 일반 모델 요청을 재시도하지 않습니다.
+재시도는 런타임 전용이며 선택적으로 사용합니다. `ModelSettings(retry=...)`를 설정하고 재시도 정책이 재시도를 선택하지 않는 한 SDK는 일반 모델 요청을 재시도하지 않습니다.
 
 ```python
 from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies
@@ -394,79 +401,79 @@ agent = Agent(
 
 | 필드 | 타입 | 참고 |
 | --- | --- | --- |
-| `max_retries` | `int | None` | 최초 요청 이후 허용되는 재시도 횟수입니다. |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 재시도할 때의 기본 지연 전략입니다. |
+| `max_retries` | `int | None` | 초기 요청 이후 허용되는 재시도 횟수입니다. |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | 정책이 명시적 지연을 반환하지 않고 재시도할 때의 기본 지연 전략입니다. `backoff.max_delay`는 이 계산된 backoff 지연만 제한합니다. 정책이 반환한 명시적 지연이나 retry-after 힌트는 제한하지 않습니다. |
 | `policy` | `RetryPolicy | None` | 재시도 여부를 결정하는 콜백입니다. 이 필드는 런타임 전용이며 직렬화되지 않습니다. |
 
 </div>
 
 재시도 정책은 다음을 포함하는 [`RetryPolicyContext`][agents.retry.RetryPolicyContext]를 받습니다.
 
-- `attempt`와 `max_retries`: 시도 횟수를 고려한 결정을 내릴 수 있습니다.
-- `stream`: 스트리밍 및 비스트리밍 동작을 분기할 수 있습니다.
-- `error`: 원문 검사를 위한 값입니다.
-- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 `normalized` 사실
-- 기본 모델 어댑터가 재시도 지침을 제공할 수 있는 경우 `provider_advice`
+- `attempt` 및 `max_retries`로 시도 횟수를 고려한 결정을 내릴 수 있습니다.
+- `stream`으로 스트리밍 및 비스트리밍 동작을 분기할 수 있습니다.
+- 원문 검사를 위한 `error`
+- `status_code`, `retry_after`, `error_code`, `is_network_error`, `is_timeout`, `is_abort` 같은 정규화된 사실
+- 기본 모델 어댑터가 재시도 지침을 제공할 수 있을 때의 `provider_advice`
 
 정책은 다음 중 하나를 반환할 수 있습니다.
 
-- 단순한 재시도 결정을 위한 `True` / `False`
-- 지연을 재정의하거나 진단 사유를 첨부하고 싶을 때 [`RetryDecision`][agents.retry.RetryDecision]
+- 간단한 재시도 결정을 위한 `True` / `False`
+- 지연을 재정의하거나 진단 이유를 첨부하려는 경우 [`RetryDecision`][agents.retry.RetryDecision]
 
 SDK는 `retry_policies`에서 바로 사용할 수 있는 헬퍼를 내보냅니다.
 
 | 헬퍼 | 동작 |
 | --- | --- |
-| `retry_policies.never()` | 항상 사용하지 않습니다. |
-| `retry_policies.provider_suggested()` | 가능한 경우 provider의 재시도 조언을 따릅니다. |
-| `retry_policies.network_error()` | 일시적인 전송 및 timeout 실패와 일치합니다. |
-| `retry_policies.http_status([...])` | 선택한 HTTP 상태 코드와 일치합니다. |
-| `retry_policies.retry_after()` | retry-after 힌트를 사용할 수 있을 때만 해당 지연을 사용해 재시도합니다. |
-| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 사용을 선택하면 재시도합니다. |
-| `retry_policies.all(...)` | 모든 중첩 정책이 사용을 선택한 경우에만 재시도합니다. |
+| `retry_policies.never()` | 항상 선택하지 않습니다. |
+| `retry_policies.provider_suggested()` | 제공되는 경우 프로바이더의 재시도 조언을 따릅니다. |
+| `retry_policies.network_error()` | 일시적인 전송 및 시간 초과 실패와 일치합니다. |
+| `retry_policies.http_status([...])` | 선택된 HTTP 상태 코드와 일치합니다. |
+| `retry_policies.retry_after()` | retry-after 힌트가 제공될 때만 해당 지연을 사용해 재시도합니다. 이 헬퍼는 retry-after 값을 명시적 정책 지연으로 취급하므로 `backoff.max_delay`가 이를 제한하지 않습니다. |
+| `retry_policies.any(...)` | 중첩된 정책 중 하나라도 선택하면 재시도합니다. |
+| `retry_policies.all(...)` | 중첩된 모든 정책이 선택할 때만 재시도합니다. |
 
-정책을 조합할 때는 provider가 이를 구분할 수 있는 경우 provider 거부와 replay-safety 승인을 보존하므로 `provider_suggested()`가 가장 안전한 첫 구성 요소입니다.
+정책을 조합할 때 `provider_suggested()`가 가장 안전한 첫 구성 요소입니다. 프로바이더가 구분할 수 있는 경우 프로바이더의 거부와 재실행 안전성 승인을 보존하기 때문입니다.
 
 ##### 안전 경계
 
 일부 실패는 자동으로 재시도되지 않습니다.
 
 - Abort 오류
-- provider 조언이 replay를 안전하지 않다고 표시한 요청
-- replay를 안전하지 않게 만들 방식으로 출력이 이미 시작된 이후의 스트리밍 실행
+- 프로바이더 조언이 재실행을 안전하지 않은 것으로 표시한 요청
+- 출력이 이미 시작되어 재실행이 안전하지 않게 되는 방식으로 진행된 스트리밍 실행
 
-`previous_response_id` 또는 `conversation_id`를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청의 경우 `network_error()` 또는 `http_status([500])` 같은 provider가 아닌 predicate만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통해 provider의 replay-safe 승인이 포함되어야 합니다.
+`previous_response_id` 또는 `conversation_id`를 사용하는 상태 저장형 후속 요청도 더 보수적으로 처리됩니다. 이러한 요청의 경우 `network_error()` 또는 `http_status([500])` 같은 비 프로바이더 조건만으로는 충분하지 않습니다. 재시도 정책에는 일반적으로 `retry_policies.provider_suggested()`를 통한 프로바이더의 재실행 안전성 승인이 포함되어야 합니다.
 
-##### Runner 및 에이전트 병합 동작
+##### Runner와 에이전트 병합 동작
 
-`retry`는 runner 수준과 에이전트 수준의 `ModelSettings` 간에 deep-merge됩니다.
+`retry`는 러너 수준 및 에이전트 수준 `ModelSettings` 사이에서 깊은 병합됩니다.
 
-- 에이전트는 `retry.max_retries`만 재정의하고 runner의 `policy`를 계속 상속할 수 있습니다.
-- 에이전트는 `retry.backoff`의 일부만 재정의하고 runner의 sibling backoff 필드를 유지할 수 있습니다.
-- `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries`와 `backoff`를 유지하지만 콜백 자체는 생략합니다.
+- 에이전트는 `retry.max_retries`만 재정의하고도 러너의 `policy`를 상속할 수 있습니다.
+- 에이전트는 `retry.backoff`의 일부만 재정의하고 러너의 형제 backoff 필드는 유지할 수 있습니다.
+- `policy`는 런타임 전용이므로 직렬화된 `ModelSettings`는 `max_retries` 및 `backoff`를 유지하지만 콜백 자체는 생략합니다.
 
-더 자세한 예시는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예시](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참고하세요.
+더 완전한 예제는 [`examples/basic/retry.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry.py) 및 [어댑터 기반 재시도 예제](https://github.com/openai/openai-agents-python/tree/main/examples/basic/retry_litellm.py)를 참조하세요.
 
-## OpenAI 외 provider 문제 해결
+## 비 OpenAI 프로바이더 문제 해결
 
 ### 트레이싱 클라이언트 오류 401
 
-트레이싱과 관련된 오류가 발생한다면, 이는 trace가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 이를 해결하는 방법은 세 가지입니다.
+트레이싱과 관련된 오류가 발생한다면, 이는 트레이스가 OpenAI 서버에 업로드되는데 OpenAI API 키가 없기 때문입니다. 이를 해결할 수 있는 옵션은 세 가지입니다.
 
 1. 트레이싱을 완전히 비활성화: [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
-2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 trace 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)의 키여야 합니다.
-3. OpenAI가 아닌 trace 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참고하세요.
+2. 트레이싱용 OpenAI 키 설정: [`set_tracing_export_api_key(...)`][agents.set_tracing_export_api_key]. 이 API 키는 트레이스 업로드에만 사용되며 [platform.openai.com](https://platform.openai.com/)에서 발급된 것이어야 합니다.
+3. 비 OpenAI 트레이스 프로세서 사용. [트레이싱 문서](../tracing.md#custom-tracing-processors)를 참조하세요.
 
 ### Responses API 지원
 
-SDK는 기본적으로 Responses API를 사용하지만, 다른 많은 LLM provider는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다.
+SDK는 기본적으로 Responses API를 사용하지만, 다른 많은 LLM 프로바이더는 아직 이를 지원하지 않습니다. 그 결과 404 또는 유사한 문제가 발생할 수 있습니다. 해결 방법은 두 가지입니다.
 
-1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]를 호출합니다. 환경 변수를 통해 `OPENAI_API_KEY`와 `OPENAI_BASE_URL`을 설정하는 경우 작동합니다.
-2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]을 사용합니다. 예시는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다.
+1. [`set_default_openai_api("chat_completions")`][agents.set_default_openai_api]를 호출합니다. 환경 변수를 통해 `OPENAI_API_KEY` 및 `OPENAI_BASE_URL`을 설정하는 경우 작동합니다.
+2. [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]을 사용합니다. 예제는 [여기](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/)에 있습니다.
 
 ### structured outputs 지원
 
-일부 모델 provider는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 유사한 오류가 발생합니다.
+일부 모델 프로바이더는 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 지원하지 않습니다. 이로 인해 때때로 다음과 비슷한 오류가 발생합니다.
 
 ```
 
@@ -474,34 +481,34 @@ BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type'
 
 ```
 
-이는 일부 모델 provider의 한계입니다. JSON 출력은 지원하지만 출력에 사용할 `json_schema`를 지정하도록 허용하지 않습니다. 이 문제를 해결하기 위해 작업 중이지만, 그렇지 않으면 잘못된 JSON 때문에 앱이 자주 중단되므로 JSON schema 출력을 지원하는 provider에 의존하는 것을 권장합니다.
+이는 일부 모델 프로바이더의 한계입니다. 이들은 JSON 출력을 지원하지만 출력에 사용할 `json_schema`를 지정하도록 허용하지 않습니다. 이 문제에 대한 수정 작업을 진행 중이지만, JSON 스키마 출력을 지원하는 프로바이더에 의존하는 것을 권장합니다. 그렇지 않으면 잘못된 형식의 JSON 때문에 앱이 자주 중단될 수 있습니다.
 
-## provider 전반에서 모델 혼합
+## 프로바이더 간 모델 혼합
 
-모델 provider 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 파일 검색 및 웹 검색을 지원하지만, 다른 많은 provider는 이러한 기능을 지원하지 않습니다. 다음 제한 사항을 유의하세요.
+모델 프로바이더 간 기능 차이를 알고 있어야 하며, 그렇지 않으면 오류가 발생할 수 있습니다. 예를 들어 OpenAI는 structured outputs, 멀티모달 입력, 호스티드 file search 및 web search를 지원하지만, 다른 많은 프로바이더는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요.
 
--   이해하지 못하는 provider에 지원되지 않는 `tools`를 보내지 마세요
+-   지원되지 않는 `tools`를 이해하지 못하는 프로바이더에 보내지 마세요
 -   텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하세요
--   structured JSON 출력을 지원하지 않는 provider는 때때로 잘못된 JSON을 생성한다는 점을 유의하세요.
+-   structured JSON 출력을 지원하지 않는 프로바이더는 가끔 유효하지 않은 JSON을 생성할 수 있음을 유의하세요.
 
 ## 서드파티 어댑터
 
-SDK의 기본 제공 provider 통합 지점으로 충분하지 않을 때만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 기본 제공 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 OpenAI가 아닌 provider와 결합해야 하거나, 기본 제공 경로가 제공하지 않는 어댑터 관리 provider 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 업스트림 모델 provider 사이에 또 다른 호환성 계층을 추가하므로, 기능 지원과 요청 의미 체계는 provider에 따라 달라질 수 있습니다. SDK는 현재 Any-LLM과 LiteLLM을 best-effort 베타 어댑터 통합으로 포함합니다.
+SDK의 내장 프로바이더 통합 지점만으로 충분하지 않을 때만 서드파티 어댑터를 사용하세요. 이 SDK로 OpenAI 모델만 사용하는 경우 Any-LLM 또는 LiteLLM 대신 내장 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 경로를 선호하세요. 서드파티 어댑터는 OpenAI 모델을 비 OpenAI 프로바이더와 결합해야 하거나, 내장 경로가 제공하지 않는 어댑터 관리형 프로바이더 범위 또는 라우팅이 필요한 경우를 위한 것입니다. 어댑터는 SDK와 상위 모델 프로바이더 사이에 또 다른 호환성 계층을 추가하므로, 기능 지원과 요청 의미 체계는 프로바이더별로 달라질 수 있습니다. SDK는 현재 Any-LLM 및 LiteLLM을 최선 노력(best-effort) 기반의 베타 어댑터 통합으로 포함합니다.
 
 ### Any-LLM
 
-Any-LLM 지원은 Any-LLM이 관리하는 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 기준으로 포함되어 있습니다.
+Any-LLM 지원은 Any-LLM 관리형 프로바이더 범위 또는 라우팅이 필요한 경우를 위해 최선 노력(best-effort) 기반의 베타로 포함되어 있습니다.
 
-업스트림 provider 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 provider별 호환성 계층을 사용할 수 있습니다.
+상위 프로바이더 경로에 따라 Any-LLM은 Responses API, Chat Completions 호환 API 또는 프로바이더별 호환성 계층을 사용할 수 있습니다.
 
-Any-LLM이 필요하다면 `openai-agents[any-llm]`을 설치한 뒤 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)에서 시작하세요. [`MultiProvider`][agents.MultiProvider]와 함께 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 한다면 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요.
+Any-LLM이 필요하면 `openai-agents[any-llm]`을 설치한 다음 [`examples/model_providers/any_llm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_auto.py) 또는 [`examples/model_providers/any_llm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/any_llm_provider.py)부터 시작하세요. [`MultiProvider`][agents.MultiProvider]와 함께 `any-llm/...` 모델 이름을 사용하거나, `AnyLLMModel`을 직접 인스턴스화하거나, 실행 범위에서 `AnyLLMProvider`를 사용할 수 있습니다. 모델 표면을 명시적으로 고정해야 하는 경우 `AnyLLMModel`을 생성할 때 `api="responses"` 또는 `api="chat_completions"`를 전달하세요.
 
-Any-LLM은 서드파티 어댑터 계층으로 남아 있으므로, provider 종속성과 기능 격차는 SDK가 아니라 Any-LLM이 업스트림에서 정의합니다. 업스트림 provider가 usage metrics를 반환하면 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 usage chunk를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, 도구 호출, usage reporting 또는 Responses-specific 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요.
+Any-LLM은 계속 서드파티 어댑터 계층이므로, 프로바이더 의존성과 기능 격차는 SDK가 아니라 상위의 Any-LLM에 의해 정의됩니다. 상위 프로바이더가 사용량 지표를 반환하면 사용량 지표는 자동으로 전파되지만, 스트리밍 Chat Completions 백엔드는 사용량 청크를 내보내기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다. structured outputs, 도구 호출, 사용량 보고 또는 Responses 특정 동작에 의존한다면 배포하려는 정확한 프로바이더 백엔드를 검증하세요.
 
 ### LiteLLM
 
-LiteLLM 지원은 LiteLLM별 provider 범위 또는 라우팅이 필요한 경우를 위해 best-effort 베타 기준으로 포함되어 있습니다.
+LiteLLM 지원은 LiteLLM 특정 프로바이더 범위 또는 라우팅이 필요한 경우를 위해 최선 노력(best-effort) 기반의 베타로 포함되어 있습니다.
 
-LiteLLM이 필요하다면 `openai-agents[litellm]`을 설치한 뒤 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)에서 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다.
+LiteLLM이 필요하면 `openai-agents[litellm]`을 설치한 다음 [`examples/model_providers/litellm_auto.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_auto.py) 또는 [`examples/model_providers/litellm_provider.py`](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers/litellm_provider.py)부터 시작하세요. `litellm/...` 모델 이름을 사용하거나 [`LitellmModel`][agents.extensions.models.litellm_model.LitellmModel]을 직접 인스턴스화할 수 있습니다.
 
-일부 LiteLLM 기반 provider는 기본적으로 SDK usage metrics를 채우지 않습니다. usage reporting이 필요하다면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, 도구 호출, usage reporting 또는 어댑터별 라우팅 동작에 의존한다면 배포하려는 정확한 provider 백엔드를 검증하세요.
+일부 LiteLLM 기반 프로바이더는 기본적으로 SDK 사용량 지표를 채우지 않습니다. 사용량 보고가 필요하면 `ModelSettings(include_usage=True)`를 전달하고, structured outputs, 도구 호출, 사용량 보고 또는 어댑터 특정 라우팅 동작에 의존하는 경우 배포하려는 정확한 프로바이더 백엔드를 검증하세요.

docs/ko/multi_agent.md

@@ -4,61 +4,61 @@ search:
 ---
 # 에이전트 오케스트레이션
 
-오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트가 실행되고, 어떤 순서로 실행되며, 다음에 무엇이 일어날지를 어떻게 결정할까요? 에이전트를 오케스트레이션하는 주요 방법은 두 가지입니다
+오케스트레이션은 앱에서 에이전트가 흐르는 방식을 의미합니다. 어떤 에이전트가 어떤 순서로 실행되며, 다음에 무엇이 일어날지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 주요 방법은 두 가지입니다.
 
-1. LLM이 의사결정을 하도록 허용: LLM의 지능을 활용해 계획하고, 추론하고, 이를 바탕으로 어떤 단계를 수행할지 결정합니다
-2. 코드를 통한 오케스트레이션: 코드로 에이전트의 흐름을 결정합니다
+1. LLM이 결정을 내리도록 허용: LLM의 지능을 사용해 계획하고, 추론하고, 이를 바탕으로 어떤 단계를 수행할지 결정합니다.
+2. 코드를 통한 오케스트레이션: 코드로 에이전트의 흐름을 결정합니다.
 
-이 패턴들은 함께 조합해 사용할 수 있습니다. 각각에는 아래에 설명된 고유한 트레이드오프가 있습니다
+이러한 패턴은 함께 조합해 사용할 수 있습니다. 각 방식에는 아래에 설명된 고유한 장단점이 있습니다.
 
 ## LLM을 통한 오케스트레이션
 
-에이전트는 instructions, tools, handoffs를 갖춘 LLM입니다. 즉, 개방형 작업이 주어지면 LLM은 도구를 사용해 행동을 수행하고 데이터를 수집하며, 핸드오프를 사용해 하위 에이전트에 작업을 위임하면서 작업을 어떻게 해결할지 자율적으로 계획할 수 있습니다. 예를 들어, 리서치 에이전트에는 다음과 같은 도구를 갖출 수 있습니다
+에이전트는 instructions, tools 및 핸드오프를 갖춘 LLM입니다. 즉, 개방형 작업이 주어지면 LLM은 tools를 사용해 작업을 수행하고 데이터를 얻으며, 핸드오프를 사용해 하위 에이전트에게 작업을 위임하면서, 작업을 어떻게 처리할지 자율적으로 계획할 수 있습니다. 예를 들어 연구 에이전트에는 다음과 같은 도구를 장착할 수 있습니다.
 
--   온라인 정보를 찾기 위한 웹 검색
--   독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색 결과 가져오기
+-   온라인에서 정보를 찾기 위한 웹 검색
+-   독점 데이터와 연결을 검색하기 위한 파일 검색 및 검색
 -   컴퓨터에서 작업을 수행하기 위한 컴퓨터 사용
--   데이터 분석을 수행하기 위한 코드 실행
--   계획 수립, 보고서 작성 등에 뛰어난 전문 에이전트로의 핸드오프
+-   데이터 분석을 위한 코드 실행
+-   기획, 보고서 작성 등에 뛰어난 전문 에이전트로의 핸드오프
 
 ### 핵심 SDK 패턴
 
-Python SDK에서는 두 가지 오케스트레이션 패턴이 가장 자주 사용됩니다
+Python SDK에서는 두 가지 오케스트레이션 패턴이 가장 자주 사용됩니다.
 
-| 패턴 | 작동 방식 | 적합한 경우 |
+| 패턴 | 작동 방식 | 가장 적합한 경우 |
 | --- | --- | --- |
-| Agents as tools | 관리자 에이전트가 대화의 제어권을 유지하고 `Agent.as_tool()`을 통해 전문 에이전트를 호출합니다 | 하나의 에이전트가 최종 답변을 책임지고, 여러 전문 에이전트의 출력을 결합하거나, 공통 가드레일을 한곳에서 적용하고 싶을 때 |
-| 핸드오프 | 트리아지 에이전트가 대화를 전문 에이전트로 라우팅하고, 해당 전문 에이전트가 해당 턴의 나머지 동안 활성 에이전트가 됩니다 | 전문 에이전트가 직접 응답하고, 프롬프트를 집중되게 유지하거나, 관리자가 결과를 설명하지 않고 instructions를 전환하고 싶을 때 |
+| Agents as tools | 관리자 에이전트가 대화의 제어권을 유지하고 `Agent.as_tool()`을 통해 전문 에이전트를 호출합니다. | 하나의 에이전트가 최종 답변을 담당하거나, 여러 전문가의 출력을 결합하거나, 공유 가드레일을 한곳에서 적용하도록 하고 싶을 때 |
+| 핸드오프 | 트리아지 에이전트가 대화를 전문가에게 라우팅하고, 해당 전문가가 나머지 턴 동안 활성 에이전트가 됩니다. | 전문가가 직접 응답하거나, 프롬프트를 집중된 상태로 유지하거나, 관리자가 결과를 설명하지 않고 instructions를 전환하도록 하고 싶을 때 |
 
-전문 에이전트가 제한된 하위 작업을 돕되 사용자 대상 대화를 넘겨받지 않아야 한다면 **agents as tools**를 사용하세요. 라우팅 자체가 워크플로의 일부이고 선택된 전문 에이전트가 다음 상호작용 구간을 맡아야 한다면 **handoffs**를 사용하세요
+전문가가 제한된 하위 작업을 도와야 하지만 사용자와 직접 마주하는 대화를 인수해서는 안 되는 경우 **agents as tools**를 사용합니다. 라우팅 자체가 워크플로의 일부이고 선택된 전문가가 상호작용의 다음 부분을 담당하도록 하고 싶을 때는 **핸드오프**를 사용합니다.
 
-두 가지를 결합할 수도 있습니다. 트리아지 에이전트가 전문 에이전트로 핸드오프한 뒤에도, 해당 전문 에이전트는 좁은 하위 작업을 위해 다른 에이전트를 도구로 호출할 수 있습니다
+두 가지를 조합할 수도 있습니다. 트리아지 에이전트가 전문가에게 핸드오프할 수 있으며, 해당 전문가는 여전히 좁은 범위의 하위 작업을 위해 다른 에이전트를 도구로 호출할 수 있습니다.
 
-이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고 싶을 때 매우 유용합니다. 여기서 가장 중요한 전술은 다음과 같습니다
+이 패턴은 작업이 개방형이고 LLM의 지능에 의존하고자 할 때 유용합니다. 여기서 가장 중요한 전략은 다음과 같습니다.
 
-1. 좋은 프롬프트에 투자하세요. 사용 가능한 도구, 사용 방법, 그리고 반드시 지켜야 하는 매개변수 범위를 명확히 하세요
-2. 앱을 모니터링하고 반복 개선하세요. 문제가 발생하는 지점을 확인하고 프롬프트를 반복 개선하세요
-3. 에이전트가 스스로 점검하고 개선하도록 하세요. 예를 들어 루프로 실행하고 자기 비평을 하게 하거나, 오류 메시지를 제공해 개선하게 하세요
-4. 어떤 작업이든 잘해야 하는 범용 에이전트 하나보다, 단일 작업에 뛰어난 전문 에이전트를 두세요
-5. [evals](https://platform.openai.com/docs/guides/evals)에 투자하세요. 이를 통해 에이전트를 훈련해 작업 수행 능력을 개선하고 향상시킬 수 있습니다
+1. 좋은 프롬프트에 투자합니다. 어떤 도구를 사용할 수 있는지, 어떻게 사용해야 하는지, 어떤 매개변수 범위 내에서 작동해야 하는지 명확히 합니다.
+2. 앱을 모니터링하고 반복적으로 개선합니다. 문제가 발생하는 지점을 파악하고 프롬프트를 반복 개선합니다.
+3. 에이전트가 스스로 성찰하고 개선하도록 허용합니다. 예를 들어 루프 안에서 실행하고 스스로 비평하게 하거나, 오류 메시지를 제공하고 개선하게 합니다.
+4. 무엇이든 잘하도록 기대되는 범용 에이전트보다, 하나의 작업에 탁월한 전문 에이전트를 둡니다.
+5. [평가](https://platform.openai.com/docs/guides/evals)에 투자합니다. 이를 통해 에이전트를 훈련해 작업 수행 능력을 개선하고 향상시킬 수 있습니다.
 
-이 스타일의 오케스트레이션을 뒷받침하는 핵심 SDK 기본 구성 요소를 원한다면 [tools](tools.md), [handoffs](handoffs.md), [running agents](running_agents.md)부터 시작하세요
+이러한 오케스트레이션 방식의 핵심 SDK 기본 구성 요소를 알고 싶다면 [도구](tools.md), [핸드오프](handoffs.md), [에이전트 실행](running_agents.md)부터 시작하세요.
 
 ## 코드를 통한 오케스트레이션
 
-LLM을 통한 오케스트레이션은 강력하지만, 코드를 통한 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정론적이고 예측 가능하게 만듭니다. 여기서의 일반적인 패턴은 다음과 같습니다
+LLM을 통한 오케스트레이션은 강력하지만, 코드를 통한 오케스트레이션은 속도, 비용, 성능 측면에서 작업을 더 결정적이고 예측 가능하게 만듭니다. 여기서 흔히 사용되는 패턴은 다음과 같습니다.
 
--   [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성하기. 예를 들어 에이전트에게 작업을 몇 가지 카테고리로 분류하게 한 다음, 카테고리에 따라 다음 에이전트를 선택할 수 있습니다
--   한 에이전트의 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝하기. 블로그 글 작성 같은 작업을 리서치, 개요 작성, 본문 작성, 비평, 개선 같은 일련의 단계로 분해할 수 있습니다
--   작업을 수행하는 에이전트를 평가 및 피드백을 제공하는 에이전트와 함께 `while` 루프로 실행하고, 평가자가 출력이 특정 기준을 통과한다고 말할 때까지 반복하기
--   여러 에이전트를 병렬로 실행하기(예: `asyncio.gather` 같은 Python 기본 구성 요소 사용). 서로 의존하지 않는 여러 작업이 있을 때 속도 측면에서 유용합니다
+-   [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용해 코드로 검사할 수 있는 적절한 형식의 데이터를 생성합니다. 예를 들어 에이전트에게 작업을 몇 가지 카테고리로 분류하게 한 다음, 해당 카테고리를 바탕으로 다음 에이전트를 선택할 수 있습니다.
+-   하나의 에이전트 출력을 다음 에이전트의 입력으로 변환해 여러 에이전트를 체이닝합니다. 블로그 게시물 작성 같은 작업을 연구하기, 개요 작성하기, 블로그 게시물 작성하기, 비평하기, 개선하기와 같은 일련의 단계로 분해할 수 있습니다.
+-   평가하고 피드백을 제공하는 에이전트와 함께, 작업을 수행하는 에이전트를 `while` 루프에서 실행하여 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복합니다.
+-   여러 에이전트를 병렬로 실행합니다. 예를 들어 `asyncio.gather` 같은 Python 기본 구성 요소를 사용할 수 있습니다. 서로 의존하지 않는 여러 작업이 있을 때 속도 측면에서 유용합니다.
 
-[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 다양한 예제가 있습니다
+[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 코드 예제가 있습니다.
 
 ## 관련 가이드
 
--   구성 패턴과 에이전트 설정은 [Agents](agents.md)를 참고하세요
--   `Agent.as_tool()` 및 관리자 스타일 오케스트레이션은 [Tools](tools.md#agents-as-tools)를 참고하세요
--   전문 에이전트 간 위임은 [Handoffs](handoffs.md)를 참고하세요
--   실행별 오케스트레이션 제어 및 대화 상태는 [Running agents](running_agents.md)를 참고하세요
--   최소한의 엔드투엔드 핸드오프 예제는 [Quickstart](quickstart.md)를 참고하세요
+-   구성 패턴과 에이전트 설정은 [에이전트](agents.md)를 참조하세요.
+-   `Agent.as_tool()` 및 관리자 스타일 오케스트레이션은 [도구](tools.md#agents-as-tools)를 참조하세요.
+-   전문 에이전트 간 위임은 [핸드오프](handoffs.md)를 참조하세요.
+-   실행별 오케스트레이션 제어와 대화 상태는 [에이전트 실행](running_agents.md)을 참조하세요.
+-   최소한의 엔드투엔드 핸드오프 예제는 [빠른 시작](quickstart.md)을 참조하세요.

docs/ko/quickstart.md

@@ -38,7 +38,7 @@ pip install openai-agents # or `uv add openai-agents`, etc
 
 ### OpenAI API 키 설정
 
-키가 없다면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)에 따라 OpenAI API 키를 생성하세요.
+API 키가 없다면 [이 지침](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)에 따라 OpenAI API 키를 생성하세요.
 
 이 명령은 현재 터미널 세션에 키를 설정합니다.
 
@@ -54,7 +54,7 @@ Windows PowerShell:
 $env:OPENAI_API_KEY = "sk-..."
 ```
 
-Windows 명령 프롬프트:
+Windows Command Prompt:
 
 ```cmd
 set "OPENAI_API_KEY=sk-..."
@@ -62,7 +62,7 @@ set "OPENAI_API_KEY=sk-..."
 
 ## 첫 에이전트 생성
 
-에이전트는 instructions, 이름, 특정 모델 같은 선택적 구성으로 정의됩니다.
+에이전트는 instructions, 이름, 특정 모델과 같은 선택적 구성으로 정의됩니다.
 
 ```python
 from agents import Agent
@@ -75,7 +75,7 @@ agent = Agent(
 
 ## 첫 에이전트 실행
 
-에이전트를 실행하고 [`RunResult`][agents.result.RunResult]를 돌려받으려면 [`Runner`][agents.run.Runner]를 사용하세요.
+[`Runner`][agents.run.Runner]를 사용해 에이전트를 실행하고 [`RunResult`][agents.result.RunResult]를 반환받습니다.
 
 ```python
 import asyncio
@@ -94,23 +94,23 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-두 번째 턴에서는 `result.to_input_list()`를 `Runner.run(...)`에 다시 전달하거나, [세션](sessions/index.md)을 연결하거나, `conversation_id` / `previous_response_id`로 OpenAI 서버 관리 상태를 재사용할 수 있습니다. [에이전트 실행](running_agents.md) 가이드에서는 이러한 접근 방식을 비교합니다.
+두 번째 턴에서는 `result.to_input_list()`를 다시 `Runner.run(...)`에 전달하거나, [세션](sessions/index.md)을 연결하거나, `conversation_id` / `previous_response_id`를 사용해 OpenAI 서버 관리 상태를 재사용할 수 있습니다. [에이전트 실행](running_agents.md) 가이드에서는 이러한 접근 방식을 비교합니다.
 
 다음 경험칙을 사용하세요.
 
-| 원하는 경우... | 다음으로 시작하세요... |
+| 원하는 경우... | 시작점... |
 | --- | --- |
-| 완전한 수동 제어와 공급자에 구애받지 않는 기록 | `result.to_input_list()` |
-| SDK가 기록을 로드하고 저장해 주기를 원하는 경우 | [`session=...`](sessions/index.md) |
+| 전체 수동 제어와 제공자에 독립적인 기록 | `result.to_input_list()` |
+| SDK가 기록을 로드하고 저장하도록 함 | [`session=...`](sessions/index.md) |
 | OpenAI가 관리하는 서버 측 이어가기 | `previous_response_id` 또는 `conversation_id` |
 
-트레이드오프와 정확한 동작은 [에이전트 실행](running_agents.md#choose-a-memory-strategy)을 참조하세요.
+절충점과 정확한 동작은 [에이전트 실행](running_agents.md#choose-a-memory-strategy)을 참고하세요.
 
-작업이 주로 프롬프트, 도구, 대화 상태에 머문다면 일반 `Agent`와 `Runner`를 사용하세요. 에이전트가 격리된 워크스페이스에서 실제 파일을 검사하거나 수정해야 한다면 [Sandbox 에이전트 빠른 시작](sandbox_agents.md)으로 이동하세요.
+작업이 주로 프롬프트, 도구, 대화 상태 안에서 이루어진다면 일반 `Agent`와 `Runner`를 사용하세요. 에이전트가 격리된 워크스페이스에서 실제 파일을 검사하거나 수정해야 한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)으로 이동하세요.
 
 ## 에이전트에 도구 제공
 
-에이전트에 정보를 조회하거나 작업을 수행할 도구를 제공할 수 있습니다.
+에이전트에 정보를 조회하거나 작업을 수행할 수 있는 도구를 제공할 수 있습니다.
 
 ```python
 import asyncio
@@ -142,16 +142,16 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## 에이전트 몇 개 추가
+## 에이전트 몇 개 더 추가
 
-멀티 에이전트 패턴을 선택하기 전에 최종 답변의 소유자가 누구인지 결정하세요.
+멀티 에이전트 패턴을 선택하기 전에, 최종 답변을 누가 담당할지 결정하세요.
 
--   **핸드오프**: 해당 턴의 그 부분에 대해 전문가가 대화를 이어받습니다.
--   **Agents as tools**: 오케스트레이터가 제어를 유지하고 전문가를 도구로 호출합니다.
+-   **핸드오프**: 해당 턴의 해당 부분에 대해 전문가가 대화를 이어받습니다.
+-   **Agents as tools**: 오케스트레이터가 제어를 유지하며 전문가를 도구로 호출합니다.
 
-이 빠른 시작에서는 첫 예제로 가장 짧기 때문에 **핸드오프**를 계속 사용합니다. 매니저 스타일 패턴은 [에이전트 오케스트레이션](multi_agent.md) 및 [도구: agents as tools](tools.md#agents-as-tools)를 참조하세요.
+이 빠른 시작에서는 첫 예제로 가장 짧기 때문에 **핸드오프**를 계속 사용합니다. 매니저 스타일 패턴은 [에이전트 오케스트레이션](multi_agent.md) 및 [도구: agents as tools](tools.md#agents-as-tools)를 참고하세요.
 
-추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_description`은 라우팅 에이전트에 언제 위임할지에 대한 추가 컨텍스트를 제공합니다.
+추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_description`은 라우팅 에이전트가 언제 위임할지에 대한 추가 컨텍스트를 제공합니다.
 
 ```python
 from agents import Agent
@@ -171,7 +171,7 @@ math_tutor_agent = Agent(
 
 ## 핸드오프 정의
 
-에이전트에서는 작업을 해결하는 동안 선택할 수 있는 나가는 핸드오프 옵션 목록을 정의할 수 있습니다.
+에이전트에서는 작업을 해결하는 동안 선택할 수 있는 발신 핸드오프 옵션 목록을 정의할 수 있습니다.
 
 ```python
 triage_agent = Agent(
@@ -203,17 +203,17 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## 참조 코드 예제
+## 참조 예제
 
 저장소에는 동일한 핵심 패턴에 대한 전체 스크립트가 포함되어 있습니다.
 
--   첫 실행용 [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py)
--   함수 도구용 [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py)
--   멀티 에이전트 라우팅용 [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py)
+-   [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py): 첫 실행
+-   [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py): 함수 도구
+-   [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py): 멀티 에이전트 라우팅
 
 ## 트레이스 보기
 
-에이전트 실행 중 발생한 일을 검토하려면 [OpenAI Dashboard의 Trace viewer](https://platform.openai.com/traces)로 이동하여 에이전트 실행 트레이스를 확인하세요.
+에이전트 실행 중 발생한 일을 검토하려면 [OpenAI Dashboard의 Trace viewer](https://platform.openai.com/traces)로 이동해 에이전트 실행 트레이스를 확인하세요.
 
 ## 다음 단계
 
@@ -221,5 +221,5 @@ if __name__ == "__main__":
 
 -   [에이전트](agents.md) 구성 방법 알아보기
 -   [에이전트 실행](running_agents.md) 및 [세션](sessions/index.md) 알아보기
--   실제 워크스페이스 안에서 작업이 이루어져야 한다면 [Sandbox 에이전트](sandbox_agents.md) 알아보기
+-   실제 워크스페이스 안에서 작업이 이루어져야 하는 경우 [샌드박스 에이전트](sandbox_agents.md) 알아보기
 -   [도구](tools.md), [가드레일](guardrails.md), [모델](models/index.md) 알아보기

docs/ko/realtime/guide.md

@@ -4,59 +4,59 @@ search:
 ---
 # 실시간 에이전트 가이드
 
-이 가이드는 OpenAI Agents SDK의 실시간 레이어가 OpenAI Realtime API에 어떻게 매핑되는지, 그리고 Python SDK가 그 위에 어떤 추가 동작을 제공하는지 설명합니다
+이 가이드는 OpenAI Agents SDK의 실시간 레이어가 OpenAI Realtime API에 어떻게 대응되는지, 그리고 Python SDK가 그 위에 어떤 추가 동작을 더하는지 설명합니다.
 
 !!! warning "베타 기능"
 
-    실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다
+    실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다.
 
-!!! note "시작 지점"
+!!! note "시작점"
 
-    기본 Python 경로를 원하시면 먼저 [빠른 시작](quickstart.md)을 읽어보세요. 앱이 서버 측 WebSocket 또는 SIP를 사용해야 하는지 결정 중이라면 [실시간 전송](transport.md)을 읽어보세요. 브라우저 WebRTC 전송은 Python SDK에 포함되지 않습니다
+    기본 Python 경로를 원한다면 먼저 [빠른 시작](quickstart.md)을 읽어보세요. 앱에서 서버 측 WebSocket 또는 SIP를 사용해야 할지 결정하는 중이라면 [실시간 전송](transport.md)을 읽어보세요. 브라우저 WebRTC 전송은 Python SDK의 일부가 아닙니다.
 
 ## 개요
 
-실시간 에이전트는 Realtime API에 대한 장기 연결을 유지하여 모델이 텍스트와 오디오를 점진적으로 처리하고, 오디오 출력을 스트리밍하고, 도구를 호출하고, 매 턴마다 새 요청을 다시 시작하지 않고 인터럽션(중단 처리)을 처리할 수 있게 합니다
+실시간 에이전트는 Realtime API에 오래 유지되는 연결을 열어 두어, 모델이 텍스트와 오디오를 점진적으로 처리하고, 오디오 출력을 스트리밍하고, 도구를 호출하고, 매 턴마다 새 요청을 다시 시작하지 않고도 인터럽션(중단 처리)을 처리할 수 있게 합니다.
 
-주요 SDK 구성 요소는 다음과 같습니다:
+주요 SDK 구성 요소는 다음과 같습니다.
 
--   **RealtimeAgent**: 하나의 실시간 전문 에이전트를 위한 instructions, tools, 출력 가드레일, 핸드오프
+-   **RealtimeAgent**: 한 명의 실시간 전문가를 위한 instructions, tools, 출력 가드레일 및 핸드오프
 -   **RealtimeRunner**: 시작 에이전트를 실시간 전송에 연결하는 세션 팩토리
--   **RealtimeSession**: 입력 전송, 이벤트 수신, 히스토리 추적, 도구 실행을 수행하는 라이브 세션
--   **RealtimeModel**: 전송 추상화 계층. 기본값은 OpenAI의 서버 측 WebSocket 구현입니다
+-   **RealtimeSession**: 입력을 보내고, 이벤트를 수신하고, 기록을 추적하고, 도구를 실행하는 라이브 세션
+-   **RealtimeModel**: 전송 추상화입니다. 기본값은 OpenAI의 서버 측 WebSocket 구현입니다.
 
 ## 세션 수명 주기
 
-일반적인 실시간 세션은 다음과 같습니다:
+일반적인 실시간 세션은 다음과 같습니다.
 
-1. 하나 이상의 `RealtimeAgent`를 생성합니다
-2. 시작 에이전트로 `RealtimeRunner`를 생성합니다
-3. `await runner.run()`을 호출해 `RealtimeSession`을 가져옵니다
-4. `async with session:` 또는 `await session.enter()`로 세션에 진입합니다
-5. `send_message()` 또는 `send_audio()`로 사용자 입력을 전송합니다
-6. 대화가 끝날 때까지 세션 이벤트를 반복 처리합니다
+1. 하나 이상의 `RealtimeAgent`를 만듭니다.
+2. 시작 에이전트로 `RealtimeRunner`를 만듭니다.
+3. `await runner.run()`을 호출해 `RealtimeSession`을 가져옵니다.
+4. `async with session:` 또는 `await session.enter()`로 세션에 진입합니다.
+5. `send_message()` 또는 `send_audio()`로 사용자 입력을 보냅니다.
+6. 대화가 끝날 때까지 세션 이벤트를 순회합니다.
 
-텍스트 전용 실행과 달리 `runner.run()`은 즉시 최종 결과를 생성하지 않습니다. 대신 전송 레이어와 동기화된 로컬 히스토리, 백그라운드 도구 실행, 가드레일 상태, 활성 에이전트 구성을 유지하는 라이브 세션 객체를 반환합니다
+텍스트 전용 실행과 달리, `runner.run()`은 최종 결과를 즉시 생성하지 않습니다. 대신 로컬 기록, 백그라운드 도구 실행, 가드레일 상태, 활성 에이전트 구성을 전송 레이어와 동기화해 유지하는 라이브 세션 객체를 반환합니다.
 
-기본적으로 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용하므로, 기본 Python 경로는 Realtime API로의 서버 측 WebSocket 연결입니다. 다른 `RealtimeModel`을 전달해도 동일한 세션 수명 주기와 에이전트 기능이 적용되며, 연결 메커니즘만 달라질 수 있습니다
+기본적으로 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용하므로 기본 Python 경로는 Realtime API에 대한 서버 측 WebSocket 연결입니다. 다른 `RealtimeModel`을 전달하더라도 동일한 세션 수명 주기와 에이전트 기능은 그대로 적용되며, 연결 방식만 달라질 수 있습니다.
 
 ## 에이전트 및 세션 구성
 
-`RealtimeAgent`는 의도적으로 일반 `Agent` 타입보다 범위가 좁습니다:
+`RealtimeAgent`는 일반 `Agent` 타입보다 의도적으로 범위가 더 좁습니다.
 
--   모델 선택은 에이전트별이 아니라 세션 수준에서 구성됩니다
--   structured outputs는 지원되지 않습니다
--   음성은 구성할 수 있지만, 세션이 이미 음성 오디오를 생성한 뒤에는 변경할 수 없습니다
--   Instructions, 함수 도구, 핸드오프, 훅, 출력 가드레일은 모두 계속 동작합니다
+-   모델 선택은 에이전트별이 아니라 세션 수준에서 구성됩니다.
+-   Structured outputs는 지원되지 않습니다.
+-   음성은 구성할 수 있지만, 세션이 이미 음성 오디오를 생성한 후에는 변경할 수 없습니다.
+-   instructions, 함수 도구, 핸드오프, 훅, 출력 가드레일은 모두 계속 작동합니다.
 
-`RealtimeSessionModelSettings`는 최신 중첩 `audio` 구성과 이전 평면 별칭을 모두 지원합니다. 새 코드에서는 중첩 형태를 권장하며, 새 실시간 에이전트는 `gpt-realtime-1.5`로 시작하세요:
+`RealtimeSessionModelSettings`는 최신 중첩 `audio` 구성과 기존 플랫 별칭을 모두 지원합니다. 새 코드에는 중첩 형태를 권장하며, 새 실시간 에이전트에는 `gpt-realtime-2`로 시작하세요.
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",
@@ -71,7 +71,7 @@ runner = RealtimeRunner(
 )
 ```
 
-유용한 세션 수준 설정은 다음과 같습니다:
+유용한 세션 수준 설정은 다음과 같습니다.
 
 -   `audio.input.format`, `audio.output.format`
 -   `audio.input.transcription`
@@ -83,7 +83,7 @@ runner = RealtimeRunner(
 -   `prompt`
 -   `tracing`
 
-`RealtimeRunner(config=...)`의 유용한 실행 수준 설정은 다음과 같습니다:
+`RealtimeRunner(config=...)`에서 사용할 수 있는 유용한 실행 수준 설정은 다음과 같습니다.
 
 -   `async_tool_calls`
 -   `output_guardrails`
@@ -91,13 +91,13 @@ runner = RealtimeRunner(
 -   `tool_error_formatter`
 -   `tracing_disabled`
 
-전체 타입 표면은 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참고하세요
+전체 타입 지정 인터페이스는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참고하세요.
 
-## 입력과 출력
+## 입력 및 출력
 
 ### 텍스트 및 구조화된 사용자 메시지
 
-일반 텍스트 또는 구조화된 실시간 메시지에는 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용하세요
+일반 텍스트 또는 구조화된 실시간 메시지를 보내려면 [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message]를 사용하세요.
 
 ```python
 from agents.realtime import RealtimeUserInputMessage
@@ -115,31 +115,31 @@ message: RealtimeUserInputMessage = {
 await session.send_message(message)
 ```
 
-구조화된 메시지는 실시간 대화에 이미지 입력을 포함하는 주요 방법입니다. [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)의 웹 데모 예제는 `input_image` 메시지를 이 방식으로 전달합니다
+구조화된 메시지는 실시간 대화에 이미지 입력을 포함하는 주된 방법입니다. [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)의 예제 웹 데모는 이러한 방식으로 `input_image` 메시지를 전달합니다.
 
 ### 오디오 입력
 
-원문 오디오 바이트를 스트리밍하려면 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요:
+원문 오디오 바이트를 스트리밍하려면 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요.
 
 ```python
 await session.send_audio(audio_bytes)
 ```
 
-서버 측 턴 감지가 비활성화된 경우, 턴 경계를 표시하는 책임은 사용자에게 있습니다. 고수준 편의 방식은 다음과 같습니다:
+서버 측 턴 감지가 비활성화되어 있으면 턴 경계를 표시할 책임은 사용자에게 있습니다. 고수준 편의 메서드는 다음과 같습니다.
 
 ```python
 await session.send_audio(audio_bytes, commit=True)
 ```
 
-더 낮은 수준의 제어가 필요하면, 기본 모델 전송을 통해 `input_audio_buffer.commit` 같은 원문 클라이언트 이벤트도 보낼 수 있습니다
+더 낮은 수준의 제어가 필요하다면 기본 모델 전송을 통해 `input_audio_buffer.commit` 같은 원문 클라이언트 이벤트도 보낼 수 있습니다.
 
 ### 수동 응답 제어
 
-`session.send_message()`는 고수준 경로로 사용자 입력을 전송하고 응답을 자동으로 시작합니다. 원문 오디오 버퍼링은 모든 구성에서 **항상** 동일하게 자동 동작하지는 않습니다
+`session.send_message()`는 고수준 경로를 사용해 사용자 입력을 보내고 응답을 시작합니다. 원문 오디오 버퍼링은 모든 구성에서 이와 동일한 작업을 자동으로 수행하지는 **않습니다**.
 
-Realtime API 수준에서 수동 턴 제어는 원문 `session.update`로 `turn_detection`을 비운 뒤, `input_audio_buffer.commit`과 `response.create`를 직접 전송하는 것을 의미합니다
+Realtime API 수준에서 수동 턴 제어란 원문 `session.update`로 `turn_detection`을 지운 다음, `input_audio_buffer.commit` 및 `response.create`를 직접 보내는 것을 의미합니다.
 
-수동으로 턴을 관리하는 경우, 모델 전송을 통해 원문 클라이언트 이벤트를 보낼 수 있습니다:
+턴을 수동으로 관리하고 있다면 모델 전송을 통해 원문 클라이언트 이벤트를 보낼 수 있습니다.
 
 ```python
 from agents.realtime.model_inputs import RealtimeModelSendRawMessage
@@ -153,19 +153,19 @@ await session.model.send_event(
 )
 ```
 
-이 패턴은 다음과 같은 경우 유용합니다:
+이 패턴은 다음과 같은 경우에 유용합니다.
 
--   `turn_detection`이 비활성화되어 있고 모델이 응답할 시점을 직접 결정하고 싶은 경우
--   응답 트리거 전에 사용자 입력을 검사하거나 게이트 처리하고 싶은 경우
+-   `turn_detection`이 비활성화되어 있고 모델이 언제 응답해야 할지 직접 결정하려는 경우
+-   응답을 트리거하기 전에 사용자 입력을 검사하거나 게이트하려는 경우
 -   대역 외 응답을 위한 사용자 지정 프롬프트가 필요한 경우
 
-[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)의 SIP 예제는 원문 `response.create`를 사용해 시작 인사말을 강제로 보냅니다
+[`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)의 SIP 예제는 원문 `response.create`를 사용해 시작 인사를 강제로 생성합니다.
 
-## 이벤트, 히스토리, 인터럽션(중단 처리)
+## 이벤트, 기록 및 인터럽션(중단 처리)
 
-`RealtimeSession`은 필요 시 원문 모델 이벤트를 그대로 전달하면서도 더 높은 수준의 SDK 이벤트를 방출합니다
+`RealtimeSession`은 필요할 때 원문 모델 이벤트를 계속 전달하면서도 더 높은 수준의 SDK 이벤트를 내보냅니다.
 
-가치가 높은 세션 이벤트는 다음과 같습니다:
+유용한 세션 이벤트는 다음과 같습니다.
 
 -   `audio`, `audio_end`, `audio_interrupted`
 -   `agent_start`, `agent_end`
@@ -177,21 +177,21 @@ await session.model.send_event(
 -   `error`
 -   `raw_model_event`
 
-UI 상태에 가장 유용한 이벤트는 보통 `history_added`와 `history_updated`입니다. 이 이벤트들은 사용자 메시지, 어시스턴트 메시지, 도구 호출을 포함한 세션의 로컬 히스토리를 `RealtimeItem` 객체로 노출합니다
+UI 상태에 가장 유용한 이벤트는 일반적으로 `history_added`와 `history_updated`입니다. 이 이벤트들은 사용자 메시지, 어시스턴트 메시지, 도구 호출을 포함해 세션의 로컬 기록을 `RealtimeItem` 객체로 노출합니다.
 
 ### 인터럽션(중단 처리) 및 재생 추적
 
-사용자가 어시스턴트를 인터럽트하면 세션은 `audio_interrupted`를 방출하고 히스토리를 업데이트하여, 서버 측 대화가 사용자가 실제로 들은 내용과 일치하도록 유지합니다
+사용자가 어시스턴트를 중단하면 세션은 `audio_interrupted`를 내보내고, 사용자가 실제로 들은 내용과 서버 측 대화가 일치하도록 기록을 업데이트합니다.
 
-지연이 낮은 로컬 재생에서는 기본 재생 추적기로 충분한 경우가 많습니다. 원격 또는 지연 재생 시나리오, 특히 전화 통신에서는 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]를 사용해 인터럽션 절단이 생성된 오디오를 모두 이미 들었다고 가정하지 않고 실제 재생 진행률에 기반하도록 하세요
+지연 시간이 낮은 로컬 재생에서는 기본 재생 추적기로 충분한 경우가 많습니다. 원격 또는 지연된 재생 시나리오, 특히 전화 통신에서는 생성된 모든 오디오를 이미 들었다고 가정하는 대신 실제 재생 진행률을 기준으로 인터럽션(중단 처리) 잘라내기가 수행되도록 [`RealtimePlaybackTracker`][agents.realtime.model.RealtimePlaybackTracker]를 사용하세요.
 
-[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py)의 Twilio 예제가 이 패턴을 보여줍니다
+[`examples/realtime/twilio/twilio_handler.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio/twilio_handler.py)의 Twilio 예제는 이 패턴을 보여줍니다.
 
-## 도구, 승인, 핸드오프, 가드레일
+## 도구, 승인, 핸드오프 및 가드레일
 
 ### 함수 도구
 
-실시간 에이전트는 라이브 대화 중 함수 도구를 지원합니다:
+실시간 에이전트는 라이브 대화 중 함수 도구를 지원합니다.
 
 ```python
 from agents import function_tool
@@ -212,7 +212,7 @@ agent = RealtimeAgent(
 
 ### 도구 승인
 
-함수 도구는 실행 전에 사람의 승인을 요구할 수 있습니다. 이 경우 세션은 `tool_approval_required`를 방출하고 `approve_tool_call()` 또는 `reject_tool_call()`을 호출할 때까지 도구 실행을 일시 중지합니다
+함수 도구는 실행 전에 사람의 승인을 요구할 수 있습니다. 이 경우 세션은 `tool_approval_required`를 내보내고, `approve_tool_call()` 또는 `reject_tool_call()`을 호출할 때까지 도구 실행을 일시 중지합니다.
 
 ```python
 async for event in session:
@@ -220,11 +220,11 @@ async for event in session:
         await session.approve_tool_call(event.call_id)
 ```
 
-구체적인 서버 측 승인 루프는 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)를 참고하세요. 휴먼인더루프 (HITL) 문서도 [Human in the loop](../human_in_the_loop.md)에서 이 흐름을 다시 안내합니다
+구체적인 서버 측 승인 루프는 [`examples/realtime/app/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app/server.py)를 참고하세요. 휴먼인더루프 (HITL) 문서의 [휴먼인더루프 (HITL)](../human_in_the_loop.md) 섹션에서도 이 흐름을 참조합니다.
 
 ### 핸드오프
 
-실시간 핸드오프를 사용하면 한 에이전트가 라이브 대화를 다른 전문 에이전트로 전환할 수 있습니다:
+실시간 핸드오프를 사용하면 한 에이전트가 라이브 대화를 다른 전문가에게 넘길 수 있습니다.
 
 ```python
 from agents.realtime import RealtimeAgent, realtime_handoff
@@ -241,11 +241,11 @@ main_agent = RealtimeAgent(
 )
 ```
 
-기본 `RealtimeAgent` 핸드오프는 자동으로 래핑되며, `realtime_handoff(...)`를 사용하면 이름, 설명, 검증, 콜백, 가용성을 사용자 지정할 수 있습니다. 실시간 핸드오프는 일반 핸드오프의 `input_filter`를 지원하지 **않습니다**
+단독 `RealtimeAgent` 핸드오프는 자동으로 래핑되며, `realtime_handoff(...)`를 사용하면 이름, 설명, 검증, 콜백, 사용 가능 여부를 사용자 지정할 수 있습니다. 실시간 핸드오프는 일반 핸드오프의 `input_filter`를 지원하지 **않습니다**.
 
 ### 가드레일
 
-실시간 에이전트에서는 출력 가드레일만 지원됩니다. 이는 부분 토큰마다가 아니라 디바운스된 전사 누적값에 대해 실행되며, 예외를 발생시키는 대신 `guardrail_tripped`를 방출합니다
+실시간 에이전트는 출력 가드레일만 지원합니다. 출력 가드레일은 모든 부분 토큰마다가 아니라 디바운스된 트랜스크립트 누적에 대해 실행되며, 예외를 발생시키는 대신 `guardrail_tripped`를 내보냅니다.
 
 ```python
 from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail
@@ -265,11 +265,17 @@ agent = RealtimeAgent(
 )
 ```
 
+실시간 출력 가드레일이 발동하면 세션은 활성 응답을 중단하고,
+`response.cancel`을 강제하며, `guardrail_tripped`를 내보내고, 트리거된 가드레일의 이름을 포함한
+후속 사용자 메시지를 보내 모델이 대체 응답을 생성할 수 있게 합니다. 가드레일은
+디바운스된 트랜스크립트 텍스트에서 실행되고 트립와이어가 작동할 때 일부 오디오가 이미 버퍼링되어 있을 수 있으므로, 오디오 플레이어는 여전히
+`audio_interrupted`를 수신하고 로컬 재생을 즉시 중지해야 합니다.
+
 ## SIP 및 전화 통신
 
-Python SDK에는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]을 통한 일급 SIP 연결 흐름이 포함되어 있습니다
+Python SDK에는 [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel]를 통한 일급 SIP 연결(attach) 흐름이 포함되어 있습니다.
 
-Realtime Calls API를 통해 통화가 도착했고, 결과 `call_id`에 에이전트 세션을 연결하려면 이를 사용하세요:
+Realtime Calls API를 통해 전화가 들어오고 그 결과 `call_id`에 에이전트 세션을 연결하려는 경우 사용하세요.
 
 ```python
 from agents.realtime import RealtimeRunner
@@ -286,20 +292,20 @@ async with await runner.run(
         ...
 ```
 
-먼저 통화를 수락해야 하고 수락 payload를 에이전트 기반 세션 구성과 일치시키고 싶다면 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`를 사용하세요. 전체 흐름은 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)에 나와 있습니다
+먼저 전화를 수락해야 하고 accept 페이로드가 에이전트에서 파생된 세션 구성과 일치하길 원한다면 `OpenAIRealtimeSIPModel.build_initial_session_payload(...)`를 사용하세요. 전체 흐름은 [`examples/realtime/twilio_sip/server.py`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip/server.py)에 나와 있습니다.
 
 ## 저수준 접근 및 사용자 지정 엔드포인트
 
-`session.model`을 통해 기본 전송 객체에 접근할 수 있습니다
+`session.model`을 통해 기본 전송 객체에 접근할 수 있습니다.
 
-다음이 필요할 때 사용하세요:
+다음이 필요할 때 사용하세요.
 
 -   `session.model.add_listener(...)`를 통한 사용자 지정 리스너
 -   `response.create` 또는 `session.update` 같은 원문 클라이언트 이벤트
--   `model_config`를 통한 사용자 지정 `url`, `headers`, `api_key` 처리
--   기존 실시간 통화에 대한 `call_id` 연결
+-   `model_config`를 통한 사용자 지정 `url`, `headers` 또는 `api_key` 처리
+-   기존 실시간 호출에 대한 `call_id` 연결
 
-`RealtimeModelConfig`는 다음을 지원합니다:
+`RealtimeModelConfig`는 다음을 지원합니다.
 
 -   `api_key`
 -   `url`
@@ -308,9 +314,9 @@ async with await runner.run(
 -   `playback_tracker`
 -   `call_id`
 
-이 저장소에서 제공되는 `call_id` 예제는 SIP입니다. 더 넓은 Realtime API에서도 일부 서버 측 제어 흐름에 `call_id`를 사용하지만, 여기서는 Python 예제로 제공되지 않습니다
+이 리포지토리에 포함되어 제공되는 `call_id` 예제는 SIP입니다. 더 넓은 Realtime API에서도 일부 서버 측 제어 흐름에 `call_id`를 사용하지만, 여기에는 Python 예제로 패키징되어 있지 않습니다.
 
-Azure OpenAI에 연결할 때는 GA Realtime 엔드포인트 URL과 명시적 헤더를 전달하세요. 예를 들면 다음과 같습니다:
+Azure OpenAI에 연결할 때는 GA Realtime 엔드포인트 URL과 명시적인 헤더를 전달하세요. 예를 들면 다음과 같습니다.
 
 ```python
 session = await runner.run(
@@ -321,7 +327,7 @@ session = await runner.run(
 )
 ```
 
-토큰 기반 인증의 경우 `headers`에 bearer 토큰을 사용하세요:
+토큰 기반 인증에는 `headers`에 베어러 토큰을 사용하세요.
 
 ```python
 session = await runner.run(
@@ -332,9 +338,9 @@ session = await runner.run(
 )
 ```
 
-`headers`를 전달하면 SDK가 `Authorization`을 자동으로 추가하지 않습니다. 실시간 에이전트에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요
+`headers`를 전달하면 SDK가 `Authorization`을 자동으로 추가하지 않습니다. 실시간 에이전트에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요.
 
-## 추가 읽을거리
+## 추가 자료
 
 -   [실시간 전송](transport.md)
 -   [빠른 시작](quickstart.md)

docs/ko/realtime/quickstart.md

@@ -4,25 +4,25 @@ search:
 ---
 # 빠른 시작
 
-Python SDK 의 실시간 에이전트는 WebSocket 전송을 통해 OpenAI Realtime API 위에서 구축된 서버 측 저지연 에이전트입니다
+Realtime agents는 WebSocket 전송을 통한 OpenAI Realtime API 기반의 서버 측 저지연 에이전트입니다.
 
 !!! warning "베타 기능"
 
-    실시간 에이전트는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다.
+    Realtime agents는 베타입니다. 구현을 개선하는 과정에서 일부 호환성이 깨지는 변경이 있을 수 있습니다.
 
 !!! note "Python SDK 범위"
 
-    Python SDK 는 브라우저 WebRTC 전송을 제공하지 **않습니다**. 이 페이지는 서버 측 WebSocket 을 통한 Python 관리 실시간 세션만 다룹니다. 이 SDK 는 서버 측 오케스트레이션, 도구, 승인, 전화 연동에 사용하세요. [실시간 전송](transport.md)도 참고하세요.
+    Python SDK는 브라우저 WebRTC 전송을 **제공하지 않습니다**. 이 페이지에서는 서버 측 WebSocket을 통한 Python 관리 실시간 세션만 다룹니다. 서버 측 오케스트레이션, 도구, 승인, 전화 통신 통합에는 이 SDK를 사용하세요. [Realtime 전송](transport.md)도 참조하세요.
 
 ## 사전 요구 사항
 
 -   Python 3.10 이상
 -   OpenAI API 키
--   OpenAI Agents SDK 에 대한 기본적인 이해
+-   OpenAI Agents SDK에 대한 기본적인 이해
 
 ## 설치
 
-아직 설치하지 않았다면 OpenAI Agents SDK 를 설치하세요:
+아직 설치하지 않았다면 OpenAI Agents SDK를 설치하세요:
 
 ```bash
 pip install openai-agents
@@ -30,7 +30,7 @@ pip install openai-agents
 
 ## 서버 측 실시간 세션 생성
 
-### 1. 실시간 구성 요소 가져오기
+### 1. realtime 구성 요소 가져오기
 
 ```python
 import asyncio
@@ -47,16 +47,16 @@ agent = RealtimeAgent(
 )
 ```
 
-### 3. runner 구성
+### 3. 러너 구성
 
-새 코드에서는 중첩된 `audio.input` / `audio.output` 세션 설정 형태를 권장합니다. 새 실시간 에이전트는 `gpt-realtime-1.5`로 시작하세요.
+새 코드에서는 중첩된 `audio.input` / `audio.output` 세션 설정 형식을 사용하는 것이 좋습니다. 새 Realtime agents에서는 `gpt-realtime-2`로 시작하세요.
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",
@@ -78,7 +78,7 @@ runner = RealtimeRunner(
 
 ### 4. 세션 시작 및 입력 전송
 
-`runner.run()`은 `RealtimeSession`을 반환합니다. 세션 컨텍스트에 들어가면 연결이 열립니다.
+`runner.run()`은 `RealtimeSession`을 반환합니다. 세션 컨텍스트에 진입하면 연결이 열립니다.
 
 ```python
 async def main() -> None:
@@ -104,41 +104,41 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-`session.send_message()`는 일반 문자열 또는 구조화된 실시간 메시지를 받습니다. 원문 오디오 청크에는 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요.
+`session.send_message()`는 일반 문자열 또는 구조화된 실시간 메시지를 허용합니다. 원문 오디오 청크의 경우 [`session.send_audio()`][agents.realtime.session.RealtimeSession.send_audio]를 사용하세요.
 
-## 이 빠른 시작에 포함되지 않은 내용
+## 이 빠른 시작에 포함되지 않는 내용
 
--   마이크 캡처 및 스피커 재생 코드. [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 실시간 코드 예제를 참고하세요.
--   SIP / 전화 연동 attach 흐름. [실시간 전송](transport.md) 및 [SIP 섹션](guide.md#sip-and-telephony)을 참고하세요.
+-   마이크 캡처 및 스피커 재생 코드. [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 실시간 코드 예제를 참조하세요.
+-   SIP / 전화 통신 연결 흐름. [Realtime 전송](transport.md) 및 [SIP 섹션](guide.md#sip-and-telephony)을 참조하세요.
 
 ## 주요 설정
 
-기본 세션이 동작하면, 다음으로 가장 많이 사용하는 설정은 다음과 같습니다:
+기본 세션이 작동하면 대부분 다음 설정을 살펴봅니다:
 
 -   `model_name`
 -   `audio.input.format`, `audio.output.format`
 -   `audio.input.transcription`
 -   `audio.input.noise_reduction`
--   자동 턴 감지를 위한 `audio.input.turn_detection`
+-   `audio.input.turn_detection`: 자동 턴 감지용
 -   `audio.output.voice`
 -   `tool_choice`, `prompt`, `tracing`
 -   `async_tool_calls`, `guardrails_settings.debounce_text_length`, `tool_error_formatter`
 
-`input_audio_format`, `output_audio_format`, `input_audio_transcription`, `turn_detection` 같은 기존의 평면 별칭도 여전히 동작하지만, 새 코드에서는 중첩 `audio` 설정이 권장됩니다.
+`input_audio_format`, `output_audio_format`, `input_audio_transcription`, `turn_detection` 같은 이전 플랫 별칭도 계속 작동하지만, 새 코드에는 중첩된 `audio` 설정을 사용하는 것이 좋습니다.
 
-수동 턴 제어의 경우 [실시간 에이전트 가이드](guide.md#manual-response-control)에 설명된 대로 원문 `session.update` / `input_audio_buffer.commit` / `response.create` 흐름을 사용하세요.
+수동 턴 제어에는 [Realtime agents 가이드](guide.md#manual-response-control)에 설명된 원문 `session.update` / `input_audio_buffer.commit` / `response.create` 흐름을 사용하세요.
 
-전체 스키마는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참고하세요.
+전체 스키마는 [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] 및 [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings]를 참조하세요.
 
 ## 연결 옵션
 
-환경 변수에 API 키를 설정하세요:
+환경에 API 키를 설정하세요:
 
 ```bash
 export OPENAI_API_KEY="your-api-key-here"
 ```
 
-또는 세션 시작 시 직접 전달하세요:
+또는 세션을 시작할 때 직접 전달하세요:
 
 ```python
 session = await runner.run(model_config={"api_key": "your-api-key"})
@@ -148,15 +148,15 @@ session = await runner.run(model_config={"api_key": "your-api-key"})
 
 -   `url`: 사용자 지정 WebSocket 엔드포인트
 -   `headers`: 사용자 지정 요청 헤더
--   `call_id`: 기존 실시간 통화에 attach. 이 저장소에서 문서화된 attach 흐름은 SIP 입니다.
--   `playback_tracker`: 사용자가 실제로 들은 오디오 양 보고
+-   `call_id`: 기존 실시간 호출에 연결합니다. 이 리포지토리에서 문서화된 연결 흐름은 SIP입니다.
+-   `playback_tracker`: 사용자가 실제로 들은 오디오의 양을 보고합니다
 
-`headers`를 명시적으로 전달하면 SDK 는 `Authorization` 헤더를 자동으로 주입하지 **않습니다**.
+`headers`를 명시적으로 전달하면 SDK가 `Authorization` 헤더를 **삽입하지 않습니다**.
 
-Azure OpenAI 에 연결할 때는 `model_config["url"]`에 GA Realtime 엔드포인트 URL 을 전달하고 명시적 헤더를 사용하세요. 실시간 에이전트에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요. 자세한 내용은 [실시간 에이전트 가이드](guide.md#low-level-access-and-custom-endpoints)를 참고하세요.
+Azure OpenAI에 연결할 때는 `model_config["url"]`에 GA Realtime 엔드포인트 URL과 명시적 헤더를 전달하세요. Realtime agents에서는 레거시 베타 경로(`/openai/realtime?api-version=...`)를 피하세요. 자세한 내용은 [Realtime agents 가이드](guide.md#low-level-access-and-custom-endpoints)를 참조하세요.
 
 ## 다음 단계
 
--   서버 측 WebSocket 과 SIP 중에서 선택하려면 [실시간 전송](transport.md)을 읽어보세요.
--   수명 주기, 구조화된 입력, 승인, 핸드오프, 가드레일, 저수준 제어는 [실시간 에이전트 가이드](guide.md)를 읽어보세요.
--   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 예제를 살펴보세요.
+-   서버 측 WebSocket과 SIP 중 선택하려면 [Realtime 전송](transport.md)을 읽어보세요.
+-   생명주기, 구조화된 입력, 승인, 핸드오프, 가드레일, 저수준 제어는 [Realtime agents 가이드](guide.md)를 읽어보세요.
+-   [`examples/realtime`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime)의 코드 예제를 살펴보세요.

docs/ko/realtime/transport.md

@@ -2,75 +2,75 @@
 search:
   exclude: true
 ---
-# 실시간 전송
+# 실시간 전송 방식
 
-이 페이지를 사용해 실시간 에이전트가 Python 애플리케이션에 어떻게 맞는지 결정하세요
+이 페이지를 사용하여 실시간 에이전트가 Python 애플리케이션에 어떻게 적합한지 결정하세요.
 
 !!! note "Python SDK 경계"
 
-    Python SDK에는 브라우저 WebRTC 전송이 **포함되지 않습니다**. 이 페이지는 Python SDK 전송 선택지만 다룹니다: 서버 측 WebSocket 및 SIP 연결 플로우. 브라우저 WebRTC는 별도의 플랫폼 주제이며, 공식 [WebRTC와 함께하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 가이드에 문서화되어 있습니다.
+    Python SDK에는 브라우저 WebRTC 전송이 **포함되지 않습니다**. 이 페이지는 Python SDK 전송 선택지, 즉 서버 측 WebSocket 및 SIP 연결 플로우만 다룹니다. 브라우저 WebRTC는 별도의 플랫폼 주제이며, 공식 [WebRTC를 사용하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 가이드에 문서화되어 있습니다.
 
 ## 결정 가이드
 
-| 목표 | 시작점 | 이유 |
+| 목표 | 시작 위치 | 이유 |
 | --- | --- | --- |
-| 서버에서 관리하는 실시간 앱 구축 | [빠른 시작](quickstart.md) | 기본 Python 경로는 `RealtimeRunner`가 관리하는 서버 측 WebSocket 세션입니다. |
-| 어떤 전송 및 배포 형태를 선택할지 이해 | 이 페이지 | 전송 또는 배포 형태를 확정하기 전에 이 페이지를 사용하세요. |
-| 전화 또는 SIP 통화에 에이전트 연결 | [실시간 가이드](guide.md) 및 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 이 저장소는 `call_id`로 구동되는 SIP 연결 플로우를 제공합니다. |
+| 서버가 관리하는 실시간 앱 빌드 | [빠른 시작](quickstart.md) | 기본 Python 경로는 `RealtimeRunner`가 관리하는 서버 측 WebSocket 세션입니다. |
+| 어떤 전송 방식과 배포 형태를 선택해야 하는지 이해 | 이 페이지 | 전송 방식이나 배포 형태를 확정하기 전에 이 페이지를 사용하세요. |
+| 에이전트를 전화 또는 SIP 통화에 연결 | [실시간 가이드](guide.md) 및 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip) | 이 저장소에는 `call_id`로 구동되는 SIP 연결 플로우가 포함되어 있습니다. |
 
-## 서버 측 WebSocket 기본 Python 경로
+## 기본 Python 경로인 서버 측 WebSocket
 
-`RealtimeRunner`는 사용자 정의 `RealtimeModel`을 전달하지 않는 한 `OpenAIRealtimeWebSocketModel`을 사용합니다.
+커스텀 `RealtimeModel`을 전달하지 않으면 `RealtimeRunner`는 `OpenAIRealtimeWebSocketModel`을 사용합니다.
 
-즉, 표준 Python 토폴로지는 다음과 같습니다:
+즉, 표준 Python 토폴로지는 다음과 같습니다.
 
 1. Python 서비스가 `RealtimeRunner`를 생성합니다.
 2. `await runner.run()`이 `RealtimeSession`을 반환합니다.
-3. 세션에 진입하고 텍스트, structured outputs 메시지 또는 오디오를 전송합니다.
-4. `RealtimeSessionEvent` 항목을 소비하고 오디오 또는 전사본을 애플리케이션으로 전달합니다.
+3. 세션에 진입하여 텍스트, 구조화된 메시지 또는 오디오를 전송합니다.
+4. `RealtimeSessionEvent` 항목을 소비하고 오디오 또는 대본을 애플리케이션으로 전달합니다.
 
-이 토폴로지는 핵심 데모 앱, CLI 예제, Twilio Media Streams 예제에서 사용됩니다:
+이 토폴로지는 핵심 데모 앱, CLI 예제, Twilio Media Streams 예제에서 사용됩니다.
 
 -   [`examples/realtime/app`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/app)
 -   [`examples/realtime/cli`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/cli)
 -   [`examples/realtime/twilio`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio)
 
-서버가 오디오 파이프라인, 도구 실행, 승인 플로우, 히스토리 처리를 소유하는 경우 이 경로를 사용하세요.
+서버가 오디오 파이프라인, 도구 실행, 승인 플로우, 기록 처리를 담당할 때 이 경로를 사용하세요.
 
-## SIP 연결 전화 통신 경로
+## 전화 통신 경로인 SIP 연결
 
-이 저장소에 문서화된 전화 통신 플로우에서는 Python SDK가 `call_id`를 통해 기존 실시간 통화에 연결됩니다.
+이 저장소에 문서화된 전화 통신 플로우에서 Python SDK는 `call_id`를 통해 기존 실시간 통화에 연결합니다.
 
-이 토폴로지는 다음과 같습니다:
+이 토폴로지는 다음과 같습니다.
 
-1. OpenAI가 `realtime.call.incoming` 같은 webhook을 서비스로 보냅니다.
+1. OpenAI가 `realtime.call.incoming`과 같은 웹훅을 서비스로 보냅니다.
 2. 서비스가 Realtime Calls API를 통해 통화를 수락합니다.
-3. Python 서비스가 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`를 시작합니다.
-4. 세션이 `model_config={"call_id": ...}`로 연결된 뒤, 다른 실시간 세션과 동일하게 이벤트를 처리합니다.
+3. Python 서비스가 `RealtimeRunner(..., model=OpenAIRealtimeSIPModel())`을 시작합니다.
+4. 세션이 `model_config={"call_id": ...}`로 연결된 다음, 다른 실시간 세션과 마찬가지로 이벤트를 처리합니다.
 
 이 토폴로지는 [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip)에 나와 있습니다.
 
 더 넓은 Realtime API도 일부 서버 측 제어 패턴에 `call_id`를 사용하지만, 이 저장소에서 제공되는 연결 예제는 SIP입니다.
 
-## 이 SDK 범위 외 브라우저 WebRTC
+## 이 SDK 범위 밖의 브라우저 WebRTC
 
-앱의 기본 클라이언트가 Realtime WebRTC를 사용하는 브라우저인 경우:
+앱의 주 클라이언트가 Realtime WebRTC를 사용하는 브라우저인 경우:
 
--   이 저장소의 Python SDK 문서 범위 밖으로 간주하세요
--   클라이언트 측 플로우와 이벤트 모델은 공식 [WebRTC와 함께하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 및 [Realtime conversations](https://developers.openai.com/api/docs/guides/realtime-conversations/) 문서를 사용하세요
--   브라우저 WebRTC 클라이언트 위에 사이드밴드 서버 연결이 필요하면 공식 [Realtime server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 가이드를 사용하세요
--   이 저장소에서 브라우저 측 `RTCPeerConnection` 추상화나 즉시 사용 가능한 브라우저 WebRTC 샘플을 제공한다고 기대하지 마세요
+-   이 저장소의 Python SDK 문서 범위 밖으로 간주하세요.
+-   클라이언트 측 플로우와 이벤트 모델에는 공식 [WebRTC를 사용하는 Realtime API](https://developers.openai.com/api/docs/guides/realtime-webrtc/) 및 [실시간 대화](https://developers.openai.com/api/docs/guides/realtime-conversations/) 문서를 사용하세요.
+-   브라우저 WebRTC 클라이언트 위에 사이드밴드 서버 연결이 필요한 경우 공식 [실시간 서버 측 제어](https://developers.openai.com/api/docs/guides/realtime-server-controls/) 가이드를 사용하세요.
+-   이 저장소가 브라우저 측 `RTCPeerConnection` 추상화나 바로 사용할 수 있는 브라우저 WebRTC 샘플을 제공한다고 기대하지 마세요.
 
 또한 이 저장소는 현재 브라우저 WebRTC와 Python 사이드밴드를 함께 사용하는 예제를 제공하지 않습니다.
 
-## 사용자 정의 엔드포인트 및 연결 지점
+## 커스텀 엔드포인트 및 연결 지점
 
-[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig]의 전송 구성 표면을 통해 기본 경로를 조정할 수 있습니다:
+[`RealtimeModelConfig`][agents.realtime.model.RealtimeModelConfig]의 전송 구성 인터페이스를 사용하면 기본 경로를 조정할 수 있습니다.
 
 -   `url`: WebSocket 엔드포인트 재정의
--   `headers`: Azure 인증 헤더 같은 명시적 헤더 제공
+-   `headers`: Azure 인증 헤더와 같은 명시적 헤더 제공
 -   `api_key`: API 키를 직접 또는 콜백을 통해 전달
--   `call_id`: 기존 실시간 통화에 연결. 이 저장소에서 문서화된 예제는 SIP입니다
+-   `call_id`: 기존 실시간 통화에 연결. 이 저장소에서 문서화된 예제는 SIP입니다.
 -   `playback_tracker`: 인터럽션(중단 처리)을 위해 실제 재생 진행 상황 보고
 
-토폴로지를 선택한 후 자세한 수명 주기 및 기능 표면은 [실시간 에이전트 가이드](guide.md)를 참조하세요.
+토폴로지를 선택한 후의 상세한 생명주기와 기능 범위는 [실시간 에이전트 가이드](guide.md)를 참조하세요.

docs/ko/release.md

@@ -6,28 +6,76 @@ search:
 
 이 프로젝트는 `0.Y.Z` 형식을 사용하는 시맨틱 버저닝의 약간 수정된 버전을 따릅니다. 앞의 `0`은 SDK가 아직 빠르게 발전하고 있음을 나타냅니다. 각 구성 요소는 다음과 같이 증가시킵니다.
 
-## 마이너(`Y`) 버전
+## 마이너 (`Y`) 버전
 
-베타로 표시되지 않은 모든 공개 인터페이스의 **호환성을 깨는 변경 사항**에 대해 마이너 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 이동할 때 호환성을 깨는 변경 사항이 포함될 수 있습니다.
+베타로 표시되지 않은 모든 공개 인터페이스에 대한 **호환성을 깨는 변경 사항**이 있을 때 마이너 버전 `Y`를 올립니다. 예를 들어 `0.0.x`에서 `0.1.x`로 이동할 때 호환성을 깨는 변경 사항이 포함될 수 있습니다.
 
-호환성을 깨는 변경 사항을 원하지 않는다면, 프로젝트에서 `0.0.x` 버전으로 고정하는 것을 권장합니다.
+호환성을 깨는 변경 사항을 원하지 않는다면 프로젝트에서 `0.0.x` 버전으로 고정하는 것을 권장합니다.
 
-## 패치(`Z`) 버전
+## 패치 (`Z`) 버전
 
-호환성을 깨지 않는 변경 사항에 대해 `Z`를 증가시킵니다.
+호환성을 깨지 않는 변경 사항에는 `Z`를 증가시킵니다.
 
-- 버그 수정
-- 새 기능
-- 비공개 인터페이스 변경
-- 베타 기능 업데이트
+-   버그 수정
+-   새 기능
+-   비공개 인터페이스 변경
+-   베타 기능 업데이트
 
 ## 호환성을 깨는 변경 사항 변경 로그
 
+### 0.17.0
+
+이 버전에서는 샌드박스 로컬 소스 구체화가 소스 경로가 `Manifest.extra_path_grants`에 포함되지 않는 한 `LocalFile.src`와 `LocalDir.src`를 구체화 `base_dir` 내에 유지합니다. `base_dir`는 매니페스트가 적용될 때 SDK 프로세스의 현재 작업 디렉터리입니다. 상대 로컬 소스는 이 디렉터리를 기준으로 해석되며, 절대 로컬 소스는 이미 그 안에 있거나 명시적 허용 범위 아래에 있어야 합니다. 이는 로컬 아티팩트 경계 문제를 해결하지만, 해당 기본 디렉터리 밖의 신뢰할 수 있는 호스트 파일이나 디렉터리를 샌드박스 워크스페이스로 의도적으로 복사하는 애플리케이션에는 영향을 줄 수 있습니다.
+
+마이그레이션하려면 매니페스트 수준에서 `SandboxPathGrant`로 신뢰할 수 있는 호스트 루트를 허용하세요. 샌드박스가 해당 파일을 읽기만 하면 되는 경우 읽기 전용으로 설정하는 것이 좋습니다.
+
+```python
+from pathlib import Path
+
+from agents.sandbox import Manifest, SandboxPathGrant
+from agents.sandbox.entries import Dir, LocalDir
+
+# This is an absolute host path outside the SDK process base_dir.
+TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")
+
+manifest = Manifest(
+    extra_path_grants=(
+        # This host root is outside the SDK process base_dir, so the manifest must grant it.
+        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
+    ),
+    entries={
+        # No grant is needed for local sources that stay under the SDK process base_dir.
+        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
+        # This entry reads from the granted host root and copies it into the sandbox workspace.
+        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
+        # Dir creates a sandbox workspace directory; it does not read from the host filesystem.
+        "output": Dir(description="Generated artifacts."),
+    },
+)
+```
+
+`extra_path_grants`를 신뢰할 수 있는 애플리케이션 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인한 경우가 아니라면 모델 출력이나 기타 신뢰할 수 없는 매니페스트 입력에서 허용 범위를 채우지 마세요.
+
+### 0.16.0
+
+이 버전에서는 SDK 기본 모델이 `gpt-4.1` 대신 `gpt-5.4-mini`로 변경되었습니다. 이는 모델을 명시적으로 설정하지 않은 에이전트와 실행에 영향을 줍니다. 새 기본값이 GPT-5 모델이므로, 암시적 기본 모델 설정에는 이제 `reasoning.effort="none"` 및 `verbosity="low"` 같은 GPT-5 기본값이 포함됩니다.
+
+이전 기본 모델 동작을 유지해야 하는 경우 에이전트나 실행 구성에서 모델을 명시적으로 설정하거나 `OPENAI_DEFAULT_MODEL` 환경 변수를 설정하세요.
+
+```python
+agent = Agent(name="Assistant", model="gpt-4.1")
+```
+
+주요 사항:
+
+-   이제 `Runner.run`, `Runner.run_sync`, `Runner.run_streamed`는 턴 제한을 비활성화하기 위해 `max_turns=None`을 허용합니다.
+-   이제 샌드박스 워크스페이스 하이드레이션은 로컬, Docker, 공급자 기반 샌드박스 구현 전반에서 절대 심볼릭 링크 대상을 포함해 아카이브 루트 밖을 가리키는 심볼릭 링크가 있는 tar 아카이브를 거부합니다.
+
 ### 0.15.0
 
-이 버전에서는 모델 거부가 이제 빈 텍스트 출력으로 처리되거나, structured outputs의 경우 실행 루프가 `MaxTurnsExceeded`에 도달할 때까지 재시도하게 하는 대신, `ModelRefusalError`로 명시적으로 표시됩니다.
+이 버전에서는 모델 거부가 빈 텍스트 출력으로 처리되거나, structured outputs의 경우 실행 루프가 `MaxTurnsExceeded`까지 재시도하게 하는 대신 `ModelRefusalError`로 명시적으로 노출됩니다.
 
-이 변경 사항은 이전에 거부만 포함된 모델 응답이 `final_output == ""`로 완료된다고 기대하던 코드에 영향을 줍니다. 예외를 발생시키지 않고 거부를 처리하려면 `model_refusal` 실행 오류 핸들러를 제공하세요.
+이전에는 거부만 포함된 모델 응답이 `final_output == ""`로 완료되기를 기대하던 코드에 영향을 줍니다. 예외를 발생시키지 않고 거부를 처리하려면 `model_refusal` 실행 오류 핸들러를 제공하세요.
 
 ```python
 result = Runner.run_sync(
@@ -37,81 +85,81 @@ result = Runner.run_sync(
 )
 ```
 
-structured outputs 에이전트의 경우, 핸들러는 에이전트의 출력 스키마와 일치하는 값을 반환할 수 있으며, SDK는 다른 실행 오류 핸들러의 최종 출력과 마찬가지로 이를 검증합니다.
+structured-output 에이전트의 경우 핸들러는 에이전트의 출력 스키마와 일치하는 값을 반환할 수 있으며, SDK는 다른 실행 오류 핸들러의 최종 출력과 마찬가지로 이를 검증합니다.
 
 ### 0.14.0
 
-이 마이너 릴리스는 **호환성을 깨는 변경 사항을 도입하지 않지만**, 주요 새 베타 기능 영역인 샌드박스 에이전트와 이를 로컬, 컨테이너화된 환경, 호스팅 환경 전반에서 사용하는 데 필요한 런타임, 백엔드, 문서 지원을 추가합니다.
+이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, 주요 새 베타 기능 영역인 샌드박스 에이전트와 이를 로컬, 컨테이너화된 환경, 호스팅 환경 전반에서 사용하는 데 필요한 런타임, 백엔드, 문서 지원을 추가합니다.
 
-주요 내용:
+주요 사항:
 
-- `SandboxAgent`, `Manifest`, `SandboxRunConfig`를 중심으로 하는 새로운 베타 샌드박스 런타임 표면을 추가하여, 에이전트가 파일, 디렉터리, Git 저장소, 마운트, 스냅샷, 재개 지원이 있는 영속적인 격리 워크스페이스 안에서 작업할 수 있게 했습니다.
-- `UnixLocalSandboxClient`와 `DockerSandboxClient`를 통한 로컬 및 컨테이너화 개발용 샌드박스 실행 백엔드를 추가했으며, 선택적 extras를 통해 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel의 호스팅 제공자 통합을 추가했습니다.
-- 향후 실행에서 이전 실행의 교훈을 재사용할 수 있도록 샌드박스 메모리 지원을 추가했으며, 점진적 공개, 멀티턴 그룹화, 구성 가능한 격리 경계, S3 기반 워크플로를 포함한 영속 메모리 예제를 제공합니다.
-- 로컬 및 합성 워크스페이스 항목, S3/R2/GCS/Azure Blob Storage/S3 Files용 원격 스토리지 마운트, 이식 가능한 스냅샷, `RunState`, `SandboxSessionState` 또는 저장된 스냅샷을 통한 재개 흐름을 포함하여 더 광범위한 워크스페이스 및 재개 모델을 추가했습니다.
-- `examples/sandbox/` 아래에 기술을 활용한 코딩 작업, 핸드오프, 메모리, 제공자별 설정, 코드 리뷰, 데이터룸 QA, 웹사이트 클로닝 같은 엔드투엔드 워크플로를 다루는 풍부한 샌드박스 예제와 튜토리얼을 추가했습니다.
-- 샌드박스를 인식하는 세션 준비, 기능 바인딩, 상태 직렬화, 통합 트레이싱, 프롬프트 캐시 키 기본값, 더 안전한 민감 MCP 출력 마스킹으로 코어 런타임과 트레이싱 스택을 확장했습니다.
+-   `SandboxAgent`, `Manifest`, `SandboxRunConfig`를 중심으로 하는 새로운 베타 샌드박스 런타임 표면을 추가하여 에이전트가 파일, 디렉터리, Git 리포지토리, 마운트, 스냅샷, 재개 지원이 있는 지속적인 격리 워크스페이스 내에서 작업할 수 있게 했습니다.
+-   `UnixLocalSandboxClient`와 `DockerSandboxClient`를 통한 로컬 및 컨테이너화된 개발용 샌드박스 실행 백엔드를 추가했으며, 선택적 extras를 통해 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel용 호스팅 공급자 통합을 추가했습니다.
+-   이후 실행에서 이전 실행의 교훈을 재사용할 수 있도록 샌드박스 메모리 지원을 추가했으며, 점진적 공개, 멀티턴 그룹화, 구성 가능한 격리 경계, S3 기반 워크플로를 포함한 지속 메모리 예제를 제공합니다.
+-   로컬 및 합성 워크스페이스 항목, S3/R2/GCS/Azure Blob Storage/S3 Files용 원격 스토리지 마운트, 이식 가능한 스냅샷, `RunState`, `SandboxSessionState` 또는 저장된 스냅샷을 통한 재개 흐름을 포함하여 더 넓은 워크스페이스 및 재개 모델을 추가했습니다.
+-   `examples/sandbox/` 아래에 풍부한 샌드박스 코드 예제와 튜토리얼을 추가했으며, 스킬, 핸드오프, 메모리, 공급자별 설정을 사용하는 코딩 작업과 코드 리뷰, 데이터룸 QA, 웹사이트 클로닝 같은 엔드투엔드 워크플로를 다룹니다.
+-   샌드박스를 인식하는 세션 준비, 기능 바인딩, 상태 직렬화, 통합 트레이싱, 프롬프트 캐시 키 기본값, 더 안전한 민감한 MCP 출력 가리기를 통해 코어 런타임과 트레이싱 스택을 확장했습니다.
 
 ### 0.13.0
 
-이 마이너 릴리스는 **호환성을 깨는 변경 사항을 도입하지 않지만**, 주목할 만한 Realtime 기본값 업데이트와 새로운 MCP 기능, 런타임 안정성 수정이 포함되어 있습니다.
+이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, 주목할 만한 Realtime 기본값 업데이트와 새로운 MCP 기능, 런타임 안정성 수정이 포함되어 있습니다.
 
-주요 내용:
+주요 사항:
 
-- 기본 websocket Realtime 모델이 이제 `gpt-realtime-1.5`이므로, 새 Realtime 에이전트 설정은 추가 구성 없이 더 새로운 모델을 사용합니다.
-- 이제 `MCPServer`는 `list_resources()`, `list_resource_templates()`, `read_resource()`를 노출하며, `MCPServerStreamableHttp`는 `session_id`를 노출하여 재연결 또는 무상태 워커 전반에서 스트리밍 가능한 HTTP 세션을 재개할 수 있습니다.
-- 이제 Chat Completions 통합은 `should_replay_reasoning_content`를 통해 추론 콘텐츠 재생을 선택할 수 있어, LiteLLM/DeepSeek 같은 어댑터에서 제공자별 추론/도구 호출 연속성이 개선됩니다.
-- `SQLAlchemySession`의 동시 최초 쓰기, reasoning 제거 후 고아가 된 assistant 메시지 ID가 포함된 압축 요청, `remove_all_tools()`가 MCP/reasoning 항목을 남기는 문제, 함수 도구 배치 실행기의 경쟁 상태 등 여러 런타임 및 세션 엣지 케이스를 수정했습니다.
+-   기본 websocket Realtime 모델이 이제 `gpt-realtime-1.5`이므로, 새 Realtime 에이전트 설정은 추가 구성 없이 더 새로운 모델을 사용합니다.
+-   이제 `MCPServer`는 `list_resources()`, `list_resource_templates()`, `read_resource()`를 노출하며, `MCPServerStreamableHttp`는 `session_id`를 노출하여 streamable HTTP 세션을 재연결 또는 상태 비저장 워커 전반에서 재개할 수 있습니다.
+-   이제 Chat Completions 통합은 `should_replay_reasoning_content`를 통해 추론 콘텐츠 재생을 선택할 수 있으며, LiteLLM/DeepSeek 같은 어댑터에서 공급자별 reasoning/tool-call 연속성을 개선합니다.
+-   `SQLAlchemySession`의 동시 최초 쓰기, reasoning 제거 후 고아가 된 어시스턴트 메시지 ID가 있는 압축 요청, `remove_all_tools()`가 MCP/reasoning 항목을 남기는 문제, 함수 도구 배치 실행기의 레이스를 포함한 여러 런타임 및 세션 엣지 케이스를 수정했습니다.
 
 ### 0.12.0
 
-이 마이너 릴리스는 **호환성을 깨는 변경 사항을 도입하지 않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)를 확인하세요.
+이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.12.0)를 확인하세요.
 
 ### 0.11.0
 
-이 마이너 릴리스는 **호환성을 깨는 변경 사항을 도입하지 않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)를 확인하세요.
+이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않습니다**. 주요 기능 추가 사항은 [릴리스 노트](https://github.com/openai/openai-agents-python/releases/tag/v0.11.0)를 확인하세요.
 
 ### 0.10.0
 
-이 마이너 릴리스는 **호환성을 깨는 변경 사항을 도입하지 않지만**, OpenAI Responses 사용자를 위한 중요한 새 기능 영역인 Responses API의 websocket 전송 지원을 포함합니다.
+이 마이너 릴리스는 호환성을 깨는 변경 사항을 도입하지 **않지만**, OpenAI Responses 사용자에게 중요한 새 기능 영역인 Responses API용 websocket 전송 지원을 포함합니다.
 
-주요 내용:
+주요 사항:
 
-- OpenAI Responses 모델에 대한 websocket 전송 지원을 추가했습니다(선택 사항이며, HTTP는 기본 전송으로 유지됩니다).
-- 멀티턴 실행 전반에서 공유 websocket 가능 제공자와 `RunConfig`를 재사용하기 위한 `responses_websocket_session()` 헬퍼 / `ResponsesWebSocketSession`을 추가했습니다.
-- 스트리밍, 도구, 승인, 후속 턴을 다루는 새로운 websocket 스트리밍 예제(`examples/basic/stream_ws.py`)를 추가했습니다.
+-   OpenAI Responses 모델에 대한 websocket 전송 지원을 추가했습니다(옵트인 방식이며, HTTP는 기본 전송으로 유지됩니다).
+-   멀티턴 실행 전반에서 websocket을 사용할 수 있는 공유 공급자와 `RunConfig`를 재사용하기 위한 `responses_websocket_session()` 헬퍼 / `ResponsesWebSocketSession`을 추가했습니다.
+-   스트리밍, 도구, 승인, 후속 턴을 다루는 새 websocket 스트리밍 예제(`examples/basic/stream_ws.py`)를 추가했습니다.
 
 ### 0.9.0
 
-이 버전에서는 Python 3.9가 더 이상 지원되지 않습니다. 이 메이저 버전은 3개월 전에 EOL에 도달했기 때문입니다. 더 새로운 런타임 버전으로 업그레이드하세요.
+이 버전에서는 Python 3.9가 더 이상 지원되지 않습니다. 이 주요 버전은 3개월 전에 EOL에 도달했기 때문입니다. 더 새로운 런타임 버전으로 업그레이드하세요.
 
-또한 `Agent#as_tool()` 메서드에서 반환되는 값의 타입 힌트가 `Tool`에서 `FunctionTool`로 좁혀졌습니다. 이 변경은 일반적으로 호환성 문제를 일으키지 않지만, 코드가 더 넓은 유니언 타입에 의존한다면 일부 조정이 필요할 수 있습니다.
+또한 `Agent#as_tool()` 메서드에서 반환되는 값의 타입 힌트가 `Tool`에서 `FunctionTool`로 좁혀졌습니다. 이 변경 사항은 일반적으로 호환성 문제를 일으키지 않지만, 코드가 더 넓은 유니언 타입에 의존하는 경우에는 일부 조정이 필요할 수 있습니다.
 
 ### 0.8.0
 
 이 버전에서는 두 가지 런타임 동작 변경으로 인해 마이그레이션 작업이 필요할 수 있습니다.
 
-- **동기** Python 호출 가능 객체를 래핑하는 함수 도구는 이제 이벤트 루프 스레드에서 실행되는 대신 `asyncio.to_thread(...)`를 통해 워커 스레드에서 실행됩니다. 도구 로직이 스레드 로컬 상태 또는 스레드에 종속적인 리소스에 의존한다면, 비동기 도구 구현으로 마이그레이션하거나 도구 코드에서 스레드 종속성을 명시적으로 처리하세요.
-- 로컬 MCP 도구 실패 처리를 이제 구성할 수 있으며, 기본 동작은 전체 실행을 실패시키는 대신 모델에 표시되는 오류 출력을 반환할 수 있습니다. 빠른 실패 의미론에 의존한다면 `mcp_config={"failure_error_function": None}`를 설정하세요. 서버 수준의 `failure_error_function` 값은 에이전트 수준 설정을 재정의하므로, 명시적 핸들러가 있는 각 로컬 MCP 서버에서 `failure_error_function=None`을 설정하세요.
+- **동기** Python 호출 가능 객체를 래핑하는 함수 도구는 이제 이벤트 루프 스레드에서 실행되는 대신 `asyncio.to_thread(...)`를 통해 워커 스레드에서 실행됩니다. 도구 로직이 스레드 로컬 상태 또는 스레드 종속 리소스에 의존하는 경우 비동기 도구 구현으로 마이그레이션하거나 도구 코드에서 스레드 종속성을 명시하세요.
+- 로컬 MCP 도구 실패 처리를 이제 구성할 수 있으며, 기본 동작은 전체 실행을 실패시키는 대신 모델에 표시되는 오류 출력을 반환할 수 있습니다. fail-fast 동작에 의존하는 경우 `mcp_config={"failure_error_function": None}`을 설정하세요. 서버 수준 `failure_error_function` 값은 에이전트 수준 설정을 재정의하므로, 명시적 핸들러가 있는 각 로컬 MCP 서버에서 `failure_error_function=None`을 설정하세요.
 
 ### 0.7.0
 
-이 버전에는 기존 애플리케이션에 영향을 줄 수 있는 몇 가지 동작 변경이 있었습니다.
+이 버전에서는 기존 애플리케이션에 영향을 줄 수 있는 몇 가지 동작 변경이 있었습니다.
 
 - 중첩 핸드오프 기록은 이제 **옵트인**입니다(기본적으로 비활성화됨). v0.6.x의 기본 중첩 동작에 의존했다면 `RunConfig(nest_handoff_history=True)`를 명시적으로 설정하세요.
-- `gpt-5.1` / `gpt-5.2`의 기본 `reasoning.effort`가 `"none"`으로 변경되었습니다(SDK 기본값으로 구성된 이전 기본값 `"low"`에서 변경). 프롬프트나 품질/비용 프로필이 `"low"`에 의존했다면 `model_settings`에서 명시적으로 설정하세요.
+- `gpt-5.1` / `gpt-5.2`의 기본 `reasoning.effort`가 `"none"`으로 변경되었습니다(SDK 기본값으로 구성되던 이전 기본값 `"low"`에서 변경). 프롬프트나 품질/비용 프로필이 `"low"`에 의존했다면 `model_settings`에서 이를 명시적으로 설정하세요.
 
 ### 0.6.0
 
-이 버전에서는 기본 핸드오프 기록이 원문 사용자/assistant 턴을 노출하는 대신 단일 assistant 메시지로 패키징되어, 다운스트림 에이전트에 간결하고 예측 가능한 요약을 제공합니다.
-- 기존 단일 메시지 핸드오프 transcript는 이제 기본적으로 `<CONVERSATION HISTORY>` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하므로, 다운스트림 에이전트는 명확하게 레이블링된 요약을 받습니다.
+이 버전에서는 기본 핸드오프 기록이 원문 사용자/어시스턴트 턴을 노출하는 대신 단일 어시스턴트 메시지로 패키징되어, 다운스트림 에이전트에 간결하고 예측 가능한 요약을 제공합니다
+- 기존 단일 메시지 핸드오프 트랜스크립트는 이제 기본적으로 `<CONVERSATION HISTORY>` 블록 앞에 "For context, here is the conversation so far between the user and the previous agent:"로 시작하므로, 다운스트림 에이전트는 명확히 라벨링된 요약을 받습니다.
 
 ### 0.5.0
 
-이 버전은 눈에 보이는 호환성을 깨는 변경 사항을 도입하지 않지만, 새로운 기능과 내부의 몇 가지 중요한 업데이트를 포함합니다.
+이 버전은 눈에 보이는 호환성을 깨는 변경 사항을 도입하지 않지만, 내부적으로 새 기능과 몇 가지 중요한 업데이트를 포함합니다.
 
 - `RealtimeRunner`가 [SIP 프로토콜 연결](https://platform.openai.com/docs/guides/realtime-sip)을 처리하도록 지원을 추가했습니다.
-- Python 3.14 호환성을 위해 `Runner#run_sync`의 내부 로직을 크게 개정했습니다.
+- Python 3.14 호환성을 위해 `Runner#run_sync`의 내부 로직을 크게 수정했습니다.
 
 ### 0.4.0
 
@@ -123,8 +171,8 @@ structured outputs 에이전트의 경우, 핸들러는 에이전트의 출력
 
 ### 0.2.0
 
-이 버전에서는 이전에 `Agent`를 인자로 받던 몇몇 위치가 이제 대신 `AgentBase`를 인자로 받습니다. 예를 들어 MCP 서버의 `list_tools()` 호출이 있습니다. 이는 순수한 타이핑 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트하려면 `Agent`를 `AgentBase`로 바꿔 타입 오류만 수정하면 됩니다.
+이 버전에서는 이전에 `Agent`를 인자로 받던 몇몇 위치가 이제 대신 `AgentBase`를 인자로 받습니다. 예를 들어 MCP 서버의 `list_tools()` 호출이 있습니다. 이는 순수 타입 지정 변경이며, 여전히 `Agent` 객체를 받게 됩니다. 업데이트하려면 `Agent`를 `AgentBase`로 교체하여 타입 오류만 수정하면 됩니다.
 
 ### 0.1.0
 
-이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 `run_context`와 `agent`라는 두 개의 새 매개변수가 추가되었습니다. `MCPServer`를 서브클래싱하는 모든 클래스에 이 매개변수를 추가해야 합니다.
+이 버전에서는 [`MCPServer.list_tools()`][agents.mcp.server.MCPServer]에 두 개의 새 매개변수 `run_context`와 `agent`가 추가되었습니다. `MCPServer`를 서브클래싱하는 모든 클래스에 이 매개변수들을 추가해야 합니다.

docs/ko/repl.md

@@ -4,7 +4,8 @@ search:
 ---
 # REPL 유틸리티
 
-SDK는 터미널에서 에이전트의 동작을 빠르고 대화형으로 테스트할 수 있도록 `run_demo_loop`를 제공합니다.
+SDK는 터미널에서 직접 에이전트의 동작을 빠르게 대화형으로 테스트할 수 있도록 `run_demo_loop`를 제공합니다.
+
 
 ```python
 import asyncio
@@ -18,6 +19,6 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-`run_demo_loop`는 루프에서 사용자 입력을 요청하고, 턴 간 대화 기록을 유지합니다. 기본적으로 모델 출력이 생성되는 대로 스트리밍합니다. 위 예제를 실행하면 run_demo_loop가 대화형 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 간 전체 대화 기록을 기억하여(에이전트가 어떤 내용이 논의되었는지 알 수 있도록) 생성되는 즉시 에이전트의 응답을 실시간으로 자동 스트리밍합니다.
+`run_demo_loop`는 루프 안에서 사용자 입력을 요청하며, 턴 사이의 대화 기록을 유지합니다. 기본적으로 모델 출력이 생성되는 대로 스트리밍합니다. 위 예제를 실행하면 run_demo_loop가 대화형 채팅 세션을 시작합니다. 계속해서 입력을 요청하고, 턴 사이의 전체 대화 기록을 기억하며(따라서 에이전트는 지금까지 논의된 내용을 알 수 있습니다), 에이전트의 응답이 생성되는 즉시 실시간으로 자동 스트리밍해 제공합니다.
 
-이 채팅 세션을 종료하려면 `quit` 또는 `exit`를 입력하고 Enter 키를 누르거나 `Ctrl-D` 키보드 단축키를 사용하세요.
+이 채팅 세션을 종료하려면 `quit` 또는 `exit`를 입력한 뒤 Enter를 누르거나 `Ctrl-D` 키보드 단축키를 사용하면 됩니다.

docs/ko/results.md

@@ -9,90 +9,90 @@ search:
 -   `Runner.run(...)` 또는 `Runner.run_sync(...)`의 [`RunResult`][agents.result.RunResult]
 -   `Runner.run_streamed(...)`의 [`RunResultStreaming`][agents.result.RunResultStreaming]
 
-둘 다 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()` 같은 공통 결과 표면을 노출합니다.
+둘 다 [`RunResultBase`][agents.result.RunResultBase]를 상속하며, `final_output`, `new_items`, `last_agent`, `raw_responses`, `to_state()`와 같은 공통 결과 접근 지점을 제공합니다.
 
-`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어를 추가합니다.
+`RunResultStreaming`은 [`stream_events()`][agents.result.RunResultStreaming.stream_events], [`current_agent`][agents.result.RunResultStreaming.current_agent], [`is_complete`][agents.result.RunResultStreaming.is_complete], [`cancel(...)`][agents.result.RunResultStreaming.cancel] 같은 스트리밍 전용 제어 기능을 추가합니다.
 
-## 적절한 결과 표면 선택
+## 적절한 결과 접근 지점 선택
 
 대부분의 애플리케이션에는 몇 가지 결과 속성이나 헬퍼만 필요합니다.
 
-| 필요한 경우... | 사용 |
+| 필요한 항목 | 사용 |
 | --- | --- |
 | 사용자에게 보여줄 최종 답변 | `final_output` |
-| 전체 로컬 transcript가 포함된, 재생 준비가 된 다음 턴 입력 목록 | `to_input_list()` |
+| 전체 로컬 대화 기록이 포함된, 재생 가능한 다음 턴 입력 목록 | `to_input_list()` |
 | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 실행 항목 | `new_items` |
 | 일반적으로 다음 사용자 턴을 처리해야 하는 에이전트 | `last_agent` |
 | `previous_response_id`를 사용한 OpenAI Responses API 체이닝 | `last_response_id` |
-| 대기 중인 승인과 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` |
-| 현재 중첩된 `Agent.as_tool()` 호출에 대한 메타데이터 | `agent_tool_invocation` |
+| 대기 중인 승인 및 재개 가능한 스냅샷 | `interruptions` 및 `to_state()` |
+| 현재 중첩 `Agent.as_tool()` 호출에 대한 메타데이터 | `agent_tool_invocation` |
 | 원문 모델 호출 또는 가드레일 진단 | `raw_responses` 및 가드레일 결과 배열 |
 
 ## 최종 출력
 
-[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 들어 있습니다. 이는 다음 중 하나입니다.
+[`final_output`][agents.result.RunResultBase.final_output] 속성에는 마지막으로 실행된 에이전트의 최종 출력이 포함됩니다. 이는 다음 중 하나입니다.
 
--   마지막 에이전트에 정의된 `output_type`이 없는 경우 `str`
--   마지막 에이전트에 정의된 출력 타입이 있는 경우 `last_agent.output_type` 타입의 객체
+-   마지막 에이전트에 `output_type`이 정의되어 있지 않았다면 `str`
+-   마지막 에이전트에 출력 타입이 정의되어 있었다면 `last_agent.output_type` 타입의 객체
 -   예를 들어 승인 인터럽션(중단 처리)에서 일시 중지되어 최종 출력이 생성되기 전에 실행이 중단된 경우 `None`
 
 !!! note
 
-    `final_output`은 `Any`로 타입이 지정되어 있습니다. 핸드오프는 어떤 에이전트가 실행을 완료하는지 바꿀 수 있으므로, SDK는 가능한 전체 출력 타입 집합을 정적으로 알 수 없습니다.
+    `final_output`은 `Any` 타입으로 지정되어 있습니다. 핸드오프는 어떤 에이전트가 실행을 완료할지 바꿀 수 있으므로, SDK는 가능한 출력 타입의 전체 집합을 정적으로 알 수 없습니다.
 
-스트리밍 모드에서는 스트림 처리가 완료될 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [스트리밍](streaming.md)을 참조하세요.
+스트리밍 모드에서는 스트림 처리가 완료될 때까지 `final_output`이 `None`으로 유지됩니다. 이벤트별 흐름은 [스트리밍](streaming.md)을 참고하세요.
 
-## 입력, 다음 턴 히스토리, 새 항목
+## 입력, 다음 턴 기록 및 새 항목
 
-이 표면들은 서로 다른 질문에 답합니다.
+이 접근 지점들은 서로 다른 질문에 답합니다.
 
-| 속성 또는 헬퍼 | 포함 내용 | 최적의 용도 |
+| 속성 또는 헬퍼 | 포함 내용 | 적합한 용도 |
 | --- | --- | --- |
-| [`input`][agents.result.RunResultBase.input] | 이 실행 구간의 기본 입력입니다. 핸드오프 입력 필터가 히스토리를 다시 썼다면, 실행이 계속된 필터링된 입력을 반영합니다. | 이 실행이 실제로 입력으로 사용한 내용을 감사 |
-| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 항목 뷰입니다. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 히스토리를 유지합니다. `mode="normalized"`는 핸드오프 필터링이 모델 히스토리를 다시 쓸 때 표준 계속 입력을 우선합니다. | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 항목 히스토리 검사 |
+| [`input`][agents.result.RunResultBase.input] | 이 실행 구간의 기본 입력입니다. 핸드오프 입력 필터가 기록을 다시 작성한 경우, 실행이 이어서 사용한 필터링된 입력을 반영합니다. | 이 실행이 실제로 입력으로 사용한 내용 감사 |
+| [`to_input_list()`][agents.result.RunResultBase.to_input_list] | 실행의 입력 항목 뷰입니다. 기본 `mode="preserve_all"`은 `new_items`에서 변환된 전체 기록을 유지합니다. `mode="normalized"`는 핸드오프 필터링이 모델 기록을 다시 작성할 때 표준 이어가기 입력을 우선합니다. | 수동 채팅 루프, 클라이언트 관리 대화 상태, 일반 항목 기록 검사 |
 | [`new_items`][agents.result.RunResultBase.new_items] | 에이전트, 도구, 핸드오프, 승인 메타데이터가 포함된 풍부한 [`RunItem`][agents.items.RunItem] 래퍼입니다. | 로그, UI, 감사, 디버깅 |
-| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행 중 각 모델 호출에서 나온 원문 [`ModelResponse`][agents.items.ModelResponse] 객체입니다. | 제공자 수준 진단 또는 원문 응답 검사 |
+| [`raw_responses`][agents.result.RunResultBase.raw_responses] | 실행의 각 모델 호출에서 나온 원문 [`ModelResponse`][agents.items.ModelResponse] 객체입니다. | 프로바이더 수준 진단 또는 원문 응답 검사 |
 
-실제로는 다음과 같습니다.
+실제로는 다음과 같이 사용합니다.
 
--   실행의 일반 입력 항목 뷰가 필요할 때는 `to_input_list()`를 사용하세요.
--   핸드오프 필터링 또는 중첩 핸드오프 히스토리 재작성 후 다음 `Runner.run(..., input=...)` 호출을 위한 표준 로컬 입력이 필요할 때는 `to_input_list(mode="normalized")`를 사용하세요.
--   SDK가 히스토리를 로드하고 저장해 주기를 원할 때는 [`session=...`](sessions/index.md)을 사용하세요.
--   `conversation_id` 또는 `previous_response_id`로 OpenAI 서버 관리 상태를 사용하는 경우, 일반적으로 `to_input_list()`를 다시 보내는 대신 새 사용자 입력만 전달하고 저장된 ID를 재사용하세요.
--   로그, UI, 감사에 사용할 전체 변환 히스토리가 필요할 때는 기본 `to_input_list()` 모드 또는 `new_items`를 사용하세요.
+-   실행의 일반 입력 항목 뷰가 필요할 때는 `to_input_list()`를 사용합니다.
+-   핸드오프 필터링 또는 중첩 핸드오프 기록 재작성 이후 다음 `Runner.run(..., input=...)` 호출에 사용할 표준 로컬 입력이 필요할 때는 `to_input_list(mode="normalized")`를 사용합니다.
+-   SDK가 기록을 로드하고 저장해 주기를 원할 때는 [`session=...`](sessions/index.md)을 사용합니다.
+-   `conversation_id` 또는 `previous_response_id`와 함께 OpenAI 서버 관리 상태를 사용하는 경우, 보통 `to_input_list()`를 다시 보내는 대신 새 사용자 입력만 전달하고 저장된 ID를 재사용합니다.
+-   로그, UI, 감사에 사용할 변환된 전체 기록이 필요할 때는 기본 `to_input_list()` 모드 또는 `new_items`를 사용합니다.
 
 JavaScript SDK와 달리 Python은 모델 형태의 델타만을 위한 별도의 `output` 속성을 노출하지 않습니다. SDK 메타데이터가 필요할 때는 `new_items`를 사용하고, 원문 모델 페이로드가 필요할 때는 `raw_responses`를 검사하세요.
 
-컴퓨터 도구 재생은 원문 Responses 페이로드 형태를 따릅니다. 프리뷰 모델 `computer_call` 항목은 단일 `action`을 보존하는 반면, `gpt-5.5` 컴퓨터 호출은 배치된 `actions[]`를 보존할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 transcript가 프리뷰 및 GA 컴퓨터 도구 호출 모두에서 계속 작동합니다. 로컬 실행 결과는 여전히 `new_items`에 `computer_call_output` 항목으로 표시됩니다.
+컴퓨터 도구 재생은 원문 Responses 페이로드 형태를 따릅니다. 프리뷰 모델의 `computer_call` 항목은 단일 `action`을 보존하고, `gpt-5.5` 컴퓨터 호출은 배치된 `actions[]`를 보존할 수 있습니다. [`to_input_list()`][agents.result.RunResultBase.to_input_list]와 [`RunState`][agents.run_state.RunState]는 모델이 생성한 형태를 그대로 유지하므로, 수동 재생, 일시 중지/재개 흐름, 저장된 대화 기록이 프리뷰 및 GA 컴퓨터 도구 호출 모두에서 계속 작동합니다. 로컬 실행 결과는 여전히 `new_items`의 `computer_call_output` 항목으로 나타납니다.
 
 ### 새 항목
 
-[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 일어난 일을 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다.
+[`new_items`][agents.result.RunResultBase.new_items]는 실행 중 발생한 일을 가장 풍부하게 보여줍니다. 일반적인 항목 타입은 다음과 같습니다.
 
 -   어시스턴트 메시지용 [`MessageOutputItem`][agents.items.MessageOutputItem]
 -   추론 항목용 [`ReasoningItem`][agents.items.ReasoningItem]
 -   Responses 도구 검색 요청 및 로드된 도구 검색 결과용 [`ToolSearchCallItem`][agents.items.ToolSearchCallItem] 및 [`ToolSearchOutputItem`][agents.items.ToolSearchOutputItem]
 -   도구 호출 및 그 결과용 [`ToolCallItem`][agents.items.ToolCallItem] 및 [`ToolCallOutputItem`][agents.items.ToolCallOutputItem]
--   승인 대기 중 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
--   핸드오프 요청 및 완료된 전환용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
+-   승인을 위해 일시 중지된 도구 호출용 [`ToolApprovalItem`][agents.items.ToolApprovalItem]
+-   핸드오프 요청 및 완료된 전달용 [`HandoffCallItem`][agents.items.HandoffCallItem] 및 [`HandoffOutputItem`][agents.items.HandoffOutputItem]
 
-에이전트 연결, 도구 출력, 핸드오프 경계 또는 승인 경계가 필요할 때마다 `to_input_list()` 대신 `new_items`를 선택하세요.
+에이전트 연결, 도구 출력, 핸드오프 경계 또는 승인 경계가 필요할 때는 항상 `to_input_list()`보다 `new_items`를 선택하세요.
 
-호스티드 툴 검색을 사용할 때는 모델이 내보낸 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을 검사하고, 해당 턴에 로드된 네임스페이스, 함수 또는 호스티드 MCP 서버를 보려면 `ToolSearchOutputItem.raw_item`을 검사하세요.
+호스티드 툴 검색을 사용할 때는 모델이 내보낸 검색 요청을 보려면 `ToolSearchCallItem.raw_item`을 검사하고, 해당 턴에 어떤 네임스페이스, 함수 또는 호스티드 MCP 서버가 로드되었는지 보려면 `ToolSearchOutputItem.raw_item`을 검사하세요.
 
 ## 대화 계속 또는 재개
 
 ### 다음 턴 에이전트
 
-[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 들어 있습니다. 이는 핸드오프 후 다음 사용자 턴에 재사용하기 가장 좋은 에이전트인 경우가 많습니다.
+[`last_agent`][agents.result.RunResultBase.last_agent]에는 마지막으로 실행된 에이전트가 포함됩니다. 이는 핸드오프 후 다음 사용자 턴에 재사용하기 가장 좋은 에이전트인 경우가 많습니다.
 
-스트리밍 모드에서는 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 실행 진행에 따라 업데이트되므로, 스트림이 끝나기 전에 핸드오프를 관찰할 수 있습니다.
+스트리밍 모드에서는 실행이 진행됨에 따라 [`RunResultStreaming.current_agent`][agents.result.RunResultStreaming.current_agent]가 업데이트되므로, 스트림이 끝나기 전에 핸드오프를 관찰할 수 있습니다.
 
 ### 인터럽션(중단 처리) 및 실행 상태
 
-도구에 승인이 필요한 경우, 대기 중인 승인은 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구, 핸드오프 후 도달한 도구 또는 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다.
+도구에 승인이 필요한 경우, 대기 중인 승인은 [`RunResult.interruptions`][agents.result.RunResult.interruptions] 또는 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. 여기에는 직접 도구, 핸드오프 후 도달한 도구 또는 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 발생한 승인이 포함될 수 있습니다.
 
-[`to_state()`][agents.result.RunResult.to_state]를 호출해 재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하고, 대기 중인 항목을 승인하거나 거부한 다음 `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요.
+[`to_state()`][agents.result.RunResult.to_state]를 호출하여 재개 가능한 [`RunState`][agents.run_state.RunState]를 캡처하고, 대기 중인 항목을 승인하거나 거부한 다음 `Runner.run(...)` 또는 `Runner.run_streamed(...)`로 재개하세요.
 
 ```python
 from agents import Agent, Runner
@@ -107,48 +107,48 @@ if result.interruptions:
     result = await Runner.run(agent, state)
 ```
 
-스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음 `result.interruptions`를 검사하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md)를 참조하세요.
+스트리밍 실행의 경우 먼저 [`stream_events()`][agents.result.RunResultStreaming.stream_events] 소비를 완료한 다음, `result.interruptions`를 검사하고 `result.to_state()`에서 재개하세요. 전체 승인 흐름은 [휴먼인더루프 (HITL)](human_in_the_loop.md)를 참고하세요.
 
-### 서버 관리 계속
+### 서버 관리 지속
 
-[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행의 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 계속하려면 다음 턴에서 `previous_response_id`로 다시 전달하세요.
+[`last_response_id`][agents.result.RunResultBase.last_response_id]는 실행에서 나온 최신 모델 응답 ID입니다. OpenAI Responses API 체인을 계속하려면 다음 턴에 이를 `previous_response_id`로 다시 전달하세요.
 
-이미 `to_input_list()`, `session` 또는 `conversation_id`로 대화를 계속하고 있다면 일반적으로 `last_response_id`가 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하다면 대신 `raw_responses`를 검사하세요.
+이미 `to_input_list()`, `session` 또는 `conversation_id`로 대화를 계속하고 있다면 보통 `last_response_id`가 필요하지 않습니다. 다단계 실행의 모든 모델 응답이 필요하면 대신 `raw_responses`를 검사하세요.
 
 ## Agent-as-tool 메타데이터
 
-결과가 중첩 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 외부 도구 호출에 대한 불변 메타데이터를 노출합니다.
+결과가 중첩된 [`Agent.as_tool()`][agents.agent.Agent.as_tool] 실행에서 나온 경우, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]은 외부 도구 호출에 대한 불변 메타데이터를 노출합니다.
 
 -   `tool_name`
 -   `tool_call_id`
 -   `tool_arguments`
 
-일반적인 최상위 실행의 경우 `agent_tool_invocation`은 `None`입니다.
+일반적인 최상위 실행에서는 `agent_tool_invocation`이 `None`입니다.
 
-이는 중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 수 있는 `custom_output_extractor` 내부에서 특히 유용합니다. 관련 `Agent.as_tool()` 패턴은 [도구](tools.md)를 참조하세요.
+이는 특히 `custom_output_extractor` 내부에서 유용합니다. 중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 수 있기 때문입니다. 관련 `Agent.as_tool()` 패턴은 [도구](tools.md)를 참고하세요.
 
-해당 중첩 실행의 파싱된 structured input도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 [`RunState`][agents.run_state.RunState]가 중첩 도구 입력을 일반적으로 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출에 대한 실시간 결과 접근자입니다.
+해당 중첩 실행의 파싱된 구조화 입력도 필요하다면 `context_wrapper.tool_input`을 읽으세요. 이는 [`RunState`][agents.run_state.RunState]가 중첩 도구 입력을 위해 일반화하여 직렬화하는 필드이며, `agent_tool_invocation`은 현재 중첩 호출에 대한 라이브 결과 접근자입니다.
 
 ## 스트리밍 수명 주기 및 진단
 
-[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 표면을 상속하지만, 스트리밍 전용 제어를 추가합니다.
+[`RunResultStreaming`][agents.result.RunResultStreaming]은 위와 동일한 결과 접근 지점을 상속하지만, 스트리밍 전용 제어 기능을 추가합니다.
 
--   의미론적 스트림 이벤트를 소비하기 위한 [`stream_events()`][agents.result.RunResultStreaming.stream_events]
--   실행 중 활성 에이전트를 추적하기 위한 [`current_agent`][agents.result.RunResultStreaming.current_agent]
--   스트리밍된 실행이 완전히 완료되었는지 확인하기 위한 [`is_complete`][agents.result.RunResultStreaming.is_complete]
--   실행을 즉시 또는 현재 턴 이후 중지하기 위한 [`cancel(...)`][agents.result.RunResultStreaming.cancel]
+-   의미론적 스트림 이벤트를 소비하는 [`stream_events()`][agents.result.RunResultStreaming.stream_events]
+-   실행 중 활성 에이전트를 추적하는 [`current_agent`][agents.result.RunResultStreaming.current_agent]
+-   스트리밍 실행이 완전히 끝났는지 확인하는 [`is_complete`][agents.result.RunResultStreaming.is_complete]
+-   실행을 즉시 또는 현재 턴 이후에 중지하는 [`cancel(...)`][agents.result.RunResultStreaming.cancel]
 
-비동기 이터레이터가 끝날 때까지 `stream_events()` 소비를 계속하세요. 스트리밍 실행은 해당 이터레이터가 종료되기 전까지 완료되지 않으며, `final_output`, `interruptions`, `raw_responses` 같은 요약 속성과 세션 지속성 부작용은 마지막으로 보이는 토큰이 도착한 후에도 아직 정리 중일 수 있습니다.
+비동기 이터레이터가 끝날 때까지 `stream_events()`를 계속 소비하세요. 해당 이터레이터가 종료되기 전까지 스트리밍 실행은 완료된 것이 아니며, `final_output`, `interruptions`, `raw_responses` 같은 요약 속성과 세션 영속화 부수 효과는 마지막으로 보이는 토큰이 도착한 뒤에도 아직 확정되는 중일 수 있습니다.
 
-`cancel()`을 호출했다면 취소와 정리가 올바르게 완료될 수 있도록 `stream_events()` 소비를 계속하세요.
+`cancel()`을 호출한 경우에도 취소와 정리가 올바르게 완료될 수 있도록 `stream_events()`를 계속 소비하세요.
 
-Python은 별도의 스트리밍된 `completed` promise나 `error` 속성을 노출하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외를 발생시키는 방식으로 표시되며, `is_complete`는 실행이 최종 상태에 도달했는지 여부를 반영합니다.
+Python은 별도의 스트리밍 `completed` 프라미스나 `error` 속성을 노출하지 않습니다. 최종 스트리밍 실패는 `stream_events()`에서 예외가 발생하는 방식으로 표면화되며, `is_complete`는 실행이 종료 상태에 도달했는지 여부를 반영합니다.
 
 ### 원문 응답
 
-[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원문 모델 응답이 들어 있습니다. 다단계 실행은 예를 들어 핸드오프 또는 반복되는 모델/도구/모델 사이클 전반에서 둘 이상의 응답을 생성할 수 있습니다.
+[`raw_responses`][agents.result.RunResultBase.raw_responses]에는 실행 중 수집된 원문 모델 응답이 포함됩니다. 다단계 실행은 예를 들어 핸드오프 또는 반복되는 모델/도구/모델 사이클을 거치며 둘 이상의 응답을 생성할 수 있습니다.
 
-[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목에서 나온 ID일 뿐입니다.
+[`last_response_id`][agents.result.RunResultBase.last_response_id]는 `raw_responses`의 마지막 항목에서 가져온 ID일 뿐입니다.
 
 ### 가드레일 결과
 
@@ -156,10 +156,10 @@ Python은 별도의 스트리밍된 `completed` promise나 `error` 속성을 노
 
 도구 가드레일은 [`tool_input_guardrail_results`][agents.result.RunResultBase.tool_input_guardrail_results] 및 [`tool_output_guardrail_results`][agents.result.RunResultBase.tool_output_guardrail_results]로 별도로 노출됩니다.
 
-이 배열들은 실행 전반에 걸쳐 누적되므로, 의사결정 로깅, 추가 가드레일 메타데이터 저장 또는 실행이 차단된 이유 디버깅에 유용합니다.
+이 배열들은 실행 전반에 걸쳐 누적되므로, 결정 사항을 기록하거나 추가 가드레일 메타데이터를 저장하거나 실행이 차단된 이유를 디버깅하는 데 유용합니다.
 
 ### 컨텍스트 및 사용량
 
 [`context_wrapper`][agents.result.RunResultBase.context_wrapper]는 승인, 사용량, 중첩 `tool_input` 같은 SDK 관리 런타임 메타데이터와 함께 앱 컨텍스트를 노출합니다.
 
-사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행의 경우 사용량 합계는 스트림의 마지막 청크가 처리될 때까지 지연될 수 있습니다. 전체 래퍼 형태와 지속성 관련 주의사항은 [컨텍스트 관리](context.md)를 참조하세요.
+사용량은 `context_wrapper.usage`에서 추적됩니다. 스트리밍 실행의 경우 스트림의 최종 청크가 처리될 때까지 사용량 합계가 지연될 수 있습니다. 전체 래퍼 형태와 지속성 관련 주의 사항은 [컨텍스트 관리](context.md)를 참고하세요.

docs/ko/running_agents.md

@@ -4,10 +4,10 @@ search:
 ---
 # 에이전트 실행
 
-[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 3가지 옵션이 있습니다.
+[`Runner`][agents.run.Runner] 클래스를 통해 에이전트를 실행할 수 있습니다. 세 가지 옵션이 있습니다.
 
 1. [`Runner.run()`][agents.run.Runner.run]: 비동기로 실행되며 [`RunResult`][agents.result.RunResult]를 반환합니다.
-2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드이며 내부적으로는 `.run()`을 실행합니다.
+2. [`Runner.run_sync()`][agents.run.Runner.run_sync]: 동기 메서드이며 내부적으로 `.run()`을 실행합니다.
 3. [`Runner.run_streamed()`][agents.run.Runner.run_streamed]: 비동기로 실행되며 [`RunResultStreaming`][agents.result.RunResultStreaming]을 반환합니다. 스트리밍 모드로 LLM을 호출하고, 수신되는 이벤트를 그대로 스트리밍합니다.
 
 ```python
@@ -23,7 +23,7 @@ async def main():
     # Infinite loop's dance
 ```
 
-자세한 내용은 [결과 가이드](results.md)를 참고하세요.
+자세한 내용은 [결과 가이드](results.md)를 참조하세요.
 
 ## Runner 수명 주기와 구성
 
@@ -35,34 +35,34 @@ async def main():
 -   OpenAI Responses API 형식의 입력 항목 목록
 -   중단된 실행을 재개할 때의 [`RunState`][agents.run_state.RunState]
 
-그러면 runner는 루프를 실행합니다.
+그런 다음 runner는 루프를 실행합니다.
 
-1. 현재 입력을 사용하여 현재 에이전트에 대해 LLM을 호출합니다.
+1. 현재 입력으로 현재 에이전트에 대해 LLM을 호출합니다.
 2. LLM이 출력을 생성합니다.
     1. LLM이 `final_output`을 반환하면 루프가 종료되고 결과를 반환합니다.
     2. LLM이 핸드오프를 수행하면 현재 에이전트와 입력을 업데이트하고 루프를 다시 실행합니다.
-    3. LLM이 도구 호출을 생성하면 해당 도구 호출을 실행하고 결과를 추가한 뒤 루프를 다시 실행합니다.
-3. 전달된 `max_turns`를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생시킵니다.
+    3. LLM이 도구 호출을 생성하면 해당 도구 호출을 실행하고, 결과를 추가한 뒤 루프를 다시 실행합니다.
+3. 전달된 `max_turns`를 초과하면 [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] 예외를 발생시킵니다. 이 턴 제한을 비활성화하려면 `max_turns=None`을 전달하세요.
 
 !!! note
 
-    LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고, 도구 호출이 없어야 한다는 것입니다.
+    LLM 출력이 "최종 출력"으로 간주되는 규칙은 원하는 타입의 텍스트 출력을 생성하고 도구 호출이 없는 경우입니다.
 
 ### 스트리밍
 
-스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트를 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에는 생성된 모든 새 출력을 포함해 실행에 대한 전체 정보가 담깁니다. 스트리밍 이벤트는 `.stream_events()`를 호출해 받을 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참고하세요.
+스트리밍을 사용하면 LLM이 실행되는 동안 스트리밍 이벤트도 추가로 받을 수 있습니다. 스트림이 완료되면 [`RunResultStreaming`][agents.result.RunResultStreaming]에 생성된 모든 새 출력을 포함하여 실행에 대한 전체 정보가 포함됩니다. 스트리밍 이벤트를 받으려면 `.stream_events()`를 호출할 수 있습니다. 자세한 내용은 [스트리밍 가이드](streaming.md)를 참조하세요.
 
 #### Responses WebSocket 전송(선택적 헬퍼)
 
-OpenAI Responses websocket 전송을 활성화하면 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼를 권장하지만 필수는 아닙니다.
+OpenAI Responses websocket 전송을 활성화해도 일반 `Runner` API를 계속 사용할 수 있습니다. 연결 재사용을 위해 websocket 세션 헬퍼 사용을 권장하지만 필수는 아닙니다.
 
-이는 [Realtime API](realtime/guide.md)가 아니라 websocket 전송을 통한 Responses API입니다.
+이는 websocket 전송을 통한 Responses API이며, [Realtime API](realtime/guide.md)가 아닙니다.
 
-전송 선택 규칙과 구체적인 모델 객체 또는 사용자 지정 공급자 관련 주의 사항은 [모델](models/index.md#responses-websocket-transport)을 참고하세요.
+구체적인 모델 객체 또는 사용자 지정 provider와 관련된 전송 선택 규칙 및 주의 사항은 [모델](models/index.md#responses-websocket-transport)을 참조하세요.
 
-##### 패턴 1: 세션 헬퍼 없음(동작함)
+##### 패턴 1: 세션 헬퍼 없음(작동)
 
-websocket 전송만 필요하고 SDK가 공유 공급자/세션을 관리할 필요가 없을 때 사용하세요.
+websocket 전송만 필요하고 SDK가 공유 provider/session을 관리할 필요가 없을 때 사용하세요.
 
 ```python
 import asyncio
@@ -85,11 +85,11 @@ async def main():
 asyncio.run(main())
 ```
 
-이 패턴은 단일 실행에는 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복해서 호출하면 동일한 `RunConfig` / 공급자 인스턴스를 수동으로 재사용하지 않는 한 각 실행마다 다시 연결될 수 있습니다.
+이 패턴은 단일 실행에는 적합합니다. `Runner.run()` / `Runner.run_streamed()`를 반복 호출하면 동일한 `RunConfig` / provider 인스턴스를 수동으로 재사용하지 않는 한 각 실행에서 다시 연결할 수 있습니다.
 
-##### 패턴 2: `responses_websocket_session()` 사용(멀티턴 재사용에 권장)
+##### 패턴 2: `responses_websocket_session()` 사용(멀티턴 재사용 권장)
 
-여러 실행(동일한 `run_config`를 상속하는 중첩 에이전트-as-tool 호출 포함)에서 공유 websocket 지원 공급자와 `RunConfig`를 원할 때 [`responses_websocket_session()`][agents.responses_websocket_session]을 사용하세요.
+여러 실행(동일한 `run_config`를 상속하는 중첩 agent-as-tool 호출 포함)에서 공유 websocket 지원 provider와 `RunConfig`를 원할 때 [`responses_websocket_session()`][agents.responses_websocket_session]를 사용하세요.
 
 ```python
 import asyncio
@@ -100,7 +100,9 @@ from agents import Agent, responses_websocket_session
 async def main():
     agent = Agent(name="Assistant", instructions="Be concise.")
 
-    async with responses_websocket_session() as ws:
+    async with responses_websocket_session(
+        responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
+    ) as ws:
         first = ws.run_streamed(agent, "Say hello in one short sentence.")
         async for _event in first.stream_events():
             pass
@@ -117,7 +119,9 @@ async def main():
 asyncio.run(main())
 ```
 
-컨텍스트가 종료되기 전에 스트리밍 결과 소비를 완료하세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다.
+컨텍스트가 종료되기 전에 스트리밍된 결과 소비를 완료하세요. websocket 요청이 아직 진행 중일 때 컨텍스트를 종료하면 공유 연결이 강제로 닫힐 수 있습니다.
+
+긴 reasoning 턴에서 websocket keepalive timeout이 발생하면 `ping_timeout`을 늘리거나 `ping_timeout=None`으로 설정해 heartbeat timeout을 비활성화하세요. websocket 지연 시간보다 안정성이 더 중요한 실행에는 HTTP/SSE 전송을 사용하세요.
 
 ### 실행 구성
 
@@ -127,53 +131,76 @@ asyncio.run(main())
 
 각 에이전트 정의를 변경하지 않고 단일 실행의 동작을 재정의하려면 `RunConfig`를 사용하세요.
 
-##### 모델, 공급자 및 세션 기본값
+##### 모델, provider, 세션 기본값
 
--   [`model`][agents.run.RunConfig.model]: 각 Agent가 가진 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다.
--   [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름을 조회하기 위한 모델 공급자이며, 기본값은 OpenAI입니다.
+-   [`model`][agents.run.RunConfig.model]: 각 에이전트가 가진 `model`과 관계없이 사용할 전역 LLM 모델을 설정할 수 있습니다.
+-   [`model_provider`][agents.run.RunConfig.model_provider]: 모델 이름을 조회하기 위한 모델 provider이며, 기본값은 OpenAI입니다.
 -   [`model_settings`][agents.run.RunConfig.model_settings]: 에이전트별 설정을 재정의합니다. 예를 들어 전역 `temperature` 또는 `top_p`를 설정할 수 있습니다.
--   [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 기록을 검색할 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다.
--   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions를 사용할 때 각 턴 전에 새 사용자 입력을 세션 기록과 병합하는 방식을 사용자 지정합니다. 콜백은 동기 또는 비동기일 수 있습니다.
+-   [`session_settings`][agents.run.RunConfig.session_settings]: 실행 중 기록을 가져올 때 세션 수준 기본값(예: `SessionSettings(limit=...)`)을 재정의합니다.
+-   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Sessions를 사용할 때 각 턴 전에 새 사용자 입력이 세션 기록과 병합되는 방식을 사용자 지정합니다. 콜백은 동기 또는 비동기일 수 있습니다.
 
-##### 가드레일, 핸드오프 및 모델 입력 구성
+##### 가드레일, 핸드오프, 모델 입력 구성
 
 -   [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: 모든 실행에 포함할 입력 또는 출력 가드레일 목록입니다.
--   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 이미 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 문서를 참고하세요.
--   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 transcript를 단일 assistant 메시지로 접는 옵트인 베타 기능입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하고, 원문 transcript를 그대로 전달하려면 `False`로 둡니다. [Runner 메서드][agents.run.Runner]는 사용자가 전달하지 않으면 자동으로 `RunConfig`를 생성하므로 quickstart와 예제는 기본값인 꺼짐 상태를 유지하며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다.
--   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 선택할 때마다 정규화된 transcript(기록 + 핸드오프 항목)를 받는 선택적 callable입니다. 다음 에이전트로 전달할 정확한 입력 항목 목록을 반환해야 하며, 이를 통해 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다.
--   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 훅입니다. 예를 들어 기록을 줄이거나 시스템 프롬프트를 삽입하는 데 사용할 수 있습니다.
--   [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 보존할지 생략할지 제어합니다.
+-   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: 핸드오프에 아직 필터가 없는 경우 모든 핸드오프에 적용할 전역 입력 필터입니다. 입력 필터를 사용하면 새 에이전트로 전송되는 입력을 편집할 수 있습니다. 자세한 내용은 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter]의 문서를 참조하세요.
+-   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: 다음 에이전트를 호출하기 전에 이전 transcript를 단일 assistant 메시지로 축소하는 선택형 베타 기능입니다. 중첩 핸드오프를 안정화하는 동안 기본적으로 비활성화되어 있습니다. 활성화하려면 `True`로 설정하고, 원문 transcript를 그대로 전달하려면 `False`로 둡니다. 모든 [Runner 메서드][agents.run.Runner]는 전달된 값이 없을 때 자동으로 `RunConfig`를 생성하므로 quickstart와 예제에서는 기본값이 꺼진 상태로 유지되며, 명시적인 [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] 콜백은 계속 이를 재정의합니다. 개별 핸드오프는 [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]를 통해 이 설정을 재정의할 수 있습니다.
+-   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: `nest_handoff_history`를 선택했을 때마다 정규화된 transcript(기록 + 핸드오프 항목)를 받는 선택적 callable입니다. 다음 에이전트로 전달할 입력 항목의 정확한 목록을 반환해야 하며, 이를 통해 전체 핸드오프 필터를 작성하지 않고도 내장 요약을 대체할 수 있습니다.
+-   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: 모델 호출 직전에 완전히 준비된 모델 입력(instructions 및 입력 항목)을 편집하는 후크입니다. 예를 들어 기록을 줄이거나 시스템 프롬프트를 주입할 수 있습니다.
+-   [`reasoning_item_id_policy`][agents.run.RunConfig.reasoning_item_id_policy]: runner가 이전 출력을 다음 턴 모델 입력으로 변환할 때 reasoning 항목 ID를 보존할지 생략할지를 제어합니다.
 
-##### 트레이싱 및 관찰 가능성
+##### 트레이싱과 관찰 가능성
 
 -   [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: 전체 실행에 대해 [트레이싱](tracing.md)을 비활성화할 수 있습니다.
 -   [`tracing`][agents.run.RunConfig.tracing]: 실행별 트레이싱 API 키와 같은 trace 내보내기 설정을 재정의하려면 [`TracingConfig`][agents.tracing.TracingConfig]를 전달합니다.
--   [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace에 LLM 및 도구 호출 입력/출력과 같은 잠재적으로 민감한 데이터가 포함될지 여부를 구성합니다.
--   [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID, trace group ID를 설정합니다. 최소한 `workflow_name`을 설정하는 것을 권장합니다. group ID는 여러 실행 간 trace를 연결할 수 있는 선택적 필드입니다.
+-   [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: trace에 LLM 및 도구 호출 입력/출력과 같이 잠재적으로 민감한 데이터를 포함할지 여부를 구성합니다.
+-   [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: 실행의 트레이싱 워크플로 이름, trace ID 및 trace group ID를 설정합니다. 최소한 `workflow_name`은 설정하는 것을 권장합니다. group ID는 여러 실행 간 trace를 연결할 수 있게 해주는 선택적 필드입니다.
 -   [`trace_metadata`][agents.run.RunConfig.trace_metadata]: 모든 trace에 포함할 메타데이터입니다.
 
-##### 도구 승인 및 도구 오류 동작
+##### 도구 실행, 승인, 도구 오류 동작
 
--   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 흐름 중 도구 호출이 거부될 때 모델에 표시되는 메시지를 사용자 지정합니다.
+-   [`tool_execution`][agents.run.RunConfig.tool_execution]: 한 번에 실행되는 함수 도구 수 제한 등 로컬 도구 호출에 대한 SDK 측 실행 동작을 구성합니다.
+-   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: 승인 플로 중 도구 호출이 거부되었을 때 모델에 표시되는 메시지를 사용자 지정합니다.
 
-중첩 핸드오프는 옵트인 베타로 제공됩니다. `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 `handoff(..., nest_handoff_history=True)`를 설정하여 접힌 transcript 동작을 활성화하세요. 원문 transcript를 유지하려면(기본값) 플래그를 설정하지 않거나 필요한 방식으로 대화를 정확히 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에서 사용되는 래퍼 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값을 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]).
+중첩 핸드오프는 선택형 베타로 제공됩니다. 축소된 transcript 동작을 활성화하려면 `RunConfig(nest_handoff_history=True)`를 전달하거나 특정 핸드오프에 대해 켜려면 `handoff(..., nest_handoff_history=True)`를 설정하세요. 원문 transcript를 유지하려는 경우(기본값), 플래그를 설정하지 않거나 필요한 방식으로 대화를 정확히 전달하는 `handoff_input_filter`(또는 `handoff_history_mapper`)를 제공하세요. 사용자 지정 mapper를 작성하지 않고 생성된 요약에 사용되는 wrapper 텍스트를 변경하려면 [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers]를 호출하세요(기본값을 복원하려면 [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] 호출).
 
 #### 실행 구성 세부 정보
 
+##### `tool_execution`
+
+SDK가 실행에 대해 로컬 함수 도구 동시성을 제한하도록 하려면 `tool_execution`을 사용하세요.
+
+```python
+from agents import Agent, RunConfig, Runner, ToolExecutionConfig
+
+agent = Agent(name="Assistant", tools=[...])
+
+result = await Runner.run(
+    agent,
+    "Run the required tool calls.",
+    run_config=RunConfig(
+        tool_execution=ToolExecutionConfig(max_function_tool_concurrency=2),
+    ),
+)
+```
+
+`max_function_tool_concurrency=None`은 기본 동작을 유지합니다. 모델이 한 턴에서 여러 함수 도구 호출을 내보내면 SDK는 내보낸 모든 로컬 함수 도구 호출을 시작합니다. 정수 값을 설정하면 동시에 실행되는 로컬 함수 도구 수를 제한할 수 있습니다.
+
+이는 provider 측 [`ModelSettings.parallel_tool_calls`][agents.model_settings.ModelSettings.parallel_tool_calls]와 별개입니다. `parallel_tool_calls`는 모델이 단일 응답에서 여러 도구 호출을 내보낼 수 있는지 제어합니다. `tool_execution.max_function_tool_concurrency`는 모델이 도구 호출을 내보낸 후 SDK가 로컬 함수 도구 호출을 실행하는 방식을 제어합니다.
+
 ##### `tool_error_formatter`
 
-승인 흐름에서 도구 호출이 거부될 때 모델에 반환되는 메시지를 사용자 지정하려면 `tool_error_formatter`를 사용하세요.
+승인 플로에서 도구 호출이 거부되었을 때 모델에 반환되는 메시지를 사용자 지정하려면 `tool_error_formatter`를 사용하세요.
 
 formatter는 다음을 포함하는 [`ToolErrorFormatterArgs`][agents.run_config.ToolErrorFormatterArgs]를 받습니다.
 
 -   `kind`: 오류 카테고리입니다. 현재는 `"approval_rejected"`입니다.
--   `tool_type`: 도구 런타임입니다(`"function"`, `"computer"`, `"shell"`, `"apply_patch"` 또는 `"custom"`).
+-   `tool_type`: 도구 런타임(`"function"`, `"computer"`, `"shell"`, `"apply_patch"` 또는 `"custom"`)입니다.
 -   `tool_name`: 도구 이름입니다.
 -   `call_id`: 도구 호출 ID입니다.
 -   `default_message`: SDK의 기본 모델 표시 메시지입니다.
--   `run_context`: 활성 실행 컨텍스트 래퍼입니다.
+-   `run_context`: 활성 실행 컨텍스트 wrapper입니다.
 
-메시지를 대체할 문자열을 반환하거나, SDK 기본값을 사용하려면 `None`을 반환합니다.
+메시지를 대체하려면 문자열을 반환하고, SDK 기본값을 사용하려면 `None`을 반환하세요.
 
 ```python
 from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs
@@ -198,56 +225,56 @@ result = Runner.run_sync(
 
 ##### `reasoning_item_id_policy`
 
-`reasoning_item_id_policy`는 runner가 기록을 다음으로 전달할 때 reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다(예: `RunResult.to_input_list()` 또는 세션 기반 실행 사용 시).
+`reasoning_item_id_policy`는 runner가 기록을 앞으로 전달할 때(예: `RunResult.to_input_list()` 또는 세션 기반 실행을 사용할 때) reasoning 항목이 다음 턴 모델 입력으로 변환되는 방식을 제어합니다.
 
 -   `None` 또는 `"preserve"`(기본값): reasoning 항목 ID를 유지합니다.
 -   `"omit"`: 생성된 다음 턴 입력에서 reasoning 항목 ID를 제거합니다.
 
-`"omit"`는 주로 reasoning 항목이 `id`와 함께 전송되었지만 필요한 후속 항목 없이 전송되는 경우 발생하는 Responses API 400 오류 클래스에 대한 옵트인 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`).
+`"omit"`은 주로 reasoning 항목이 `id`와 함께 전송되지만 필수 후속 항목 없이 전송되는 경우 발생하는 Responses API 400 오류 계열에 대한 선택적 완화책으로 사용하세요(예: `Item 'rs_...' of type 'reasoning' was provided without its required following item.`).
 
-이는 SDK가 이전 출력에서 후속 입력을 구성하는 멀티턴 에이전트 실행에서 발생할 수 있습니다(세션 지속성, 서버 관리 conversation delta, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함). reasoning 항목 ID가 보존되었지만 공급자가 해당 ID가 대응되는 후속 항목과 쌍을 이루어 유지되도록 요구하는 경우입니다.
+이는 SDK가 이전 출력에서 후속 입력을 구성할 때(세션 영속성, 서버 관리 대화 delta, 스트리밍/비스트리밍 후속 턴, 재개 경로 포함) reasoning 항목 ID가 보존되지만 provider가 해당 ID가 대응하는 후속 항목과 계속 쌍을 이루도록 요구하는 멀티턴 에이전트 실행에서 발생할 수 있습니다.
 
-`reasoning_item_id_policy="omit"`를 설정하면 reasoning 내용은 유지하되 reasoning 항목 `id`를 제거하여 SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 방지합니다.
+`reasoning_item_id_policy="omit"`을 설정하면 reasoning 콘텐츠는 유지하되 reasoning 항목 `id`를 제거하여 SDK가 생성한 후속 입력에서 해당 API 불변 조건이 트리거되는 것을 방지합니다.
 
 범위 참고:
 
--   이는 SDK가 후속 입력을 빌드할 때 SDK가 생성/전달한 reasoning 항목만 변경합니다.
+-   이는 SDK가 후속 입력을 빌드할 때 생성/전달하는 reasoning 항목만 변경합니다.
 -   사용자가 제공한 초기 입력 항목은 다시 작성하지 않습니다.
--   이 정책이 적용된 후에도 `call_model_input_filter`는 의도적으로 reasoning ID를 다시 도입할 수 있습니다.
+-   `call_model_input_filter`는 이 정책이 적용된 후에도 의도적으로 reasoning ID를 다시 도입할 수 있습니다.
 
-## 상태 및 대화 관리
+## 상태와 대화 관리
 
 ### 메모리 전략 선택
 
 상태를 다음 턴으로 전달하는 일반적인 방법은 네 가지입니다.
 
-| 전략 | 상태가 저장되는 위치 | 적합한 용도 | 다음 턴에 전달하는 것 |
+| 전략 | 상태가 위치하는 곳 | 적합한 경우 | 다음 턴에 전달하는 것 |
 | --- | --- | --- | --- |
-| `result.to_input_list()` | 애플리케이션 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 공급자 | `result.to_input_list()`의 목록과 다음 사용자 메시지 |
-| `session` | 사용자의 스토리지와 SDK | 지속적인 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 |
+| `result.to_input_list()` | 앱 메모리 | 작은 채팅 루프, 완전한 수동 제어, 모든 provider | `result.to_input_list()`의 목록과 다음 사용자 메시지 |
+| `session` | 사용자의 저장소와 SDK | 영속적인 채팅 상태, 재개 가능한 실행, 사용자 지정 저장소 | 동일한 `session` 인스턴스 또는 같은 저장소를 가리키는 다른 인스턴스 |
 | `conversation_id` | OpenAI Conversations API | 작업자나 서비스 간에 공유하려는 이름 있는 서버 측 대화 | 동일한 `conversation_id`와 새 사용자 턴만 |
-| `previous_response_id` | OpenAI Responses API | conversation 리소스를 만들지 않는 경량 서버 관리 continuation | `result.last_response_id`와 새 사용자 턴만 |
+| `previous_response_id` | OpenAI Responses API | 대화 리소스를 만들지 않는 경량 서버 관리 연속 처리 | `result.last_response_id`와 새 사용자 턴만 |
 
-`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 conversation마다 하나의 지속성 전략을 선택하세요. 두 계층을 의도적으로 조정하는 경우가 아니라면 클라이언트 관리 기록과 OpenAI 관리 상태를 혼합하면 컨텍스트가 중복될 수 있습니다.
+`result.to_input_list()`와 `session`은 클라이언트 관리 방식입니다. `conversation_id`와 `previous_response_id`는 OpenAI 관리 방식이며 OpenAI Responses API를 사용할 때만 적용됩니다. 대부분의 애플리케이션에서는 대화마다 하나의 영속성 전략을 선택하세요. 두 계층을 의도적으로 조정하지 않는 한 클라이언트 관리 기록과 OpenAI 관리 상태를 섞으면 컨텍스트가 중복될 수 있습니다.
 
 !!! note
 
-    세션 지속성은 같은 실행에서 서버 관리 conversation 설정
+    세션 영속성은 동일한 실행에서 서버 관리 대화 설정
     (`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`)과
-    함께 사용할 수 없습니다. 호출마다 하나의 접근 방식을 선택하세요.
+    결합할 수 없습니다. 호출마다 하나의 접근 방식을 선택하세요.
 
-### Conversations/채팅 스레드
+### 대화/채팅 스레드
 
-run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있고(따라서 하나 이상의 LLM 호출이 발생할 수 있음), 이는 채팅 conversation의 단일 논리적 턴을 나타냅니다. 예를 들어:
+run 메서드 중 하나를 호출하면 하나 이상의 에이전트가 실행될 수 있으므로 하나 이상의 LLM 호출이 발생할 수 있지만, 이는 채팅 대화의 단일 논리 턴을 나타냅니다. 예를 들어:
 
-1. 사용자 턴: 사용자가 텍스트를 입력합니다
-2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고, 도구를 실행하고, 두 번째 에이전트로 핸드오프를 수행한 뒤, 두 번째 에이전트가 더 많은 도구를 실행하고 출력을 생성합니다.
+1. 사용자 턴: 사용자가 텍스트 입력
+2. Runner 실행: 첫 번째 에이전트가 LLM을 호출하고, 도구를 실행하고, 두 번째 에이전트로 핸드오프하며, 두 번째 에이전트가 더 많은 도구를 실행한 다음 출력을 생성합니다.
 
 에이전트 실행이 끝나면 사용자에게 무엇을 보여줄지 선택할 수 있습니다. 예를 들어 에이전트가 생성한 모든 새 항목을 사용자에게 보여주거나 최종 출력만 보여줄 수 있습니다. 어느 쪽이든 사용자가 후속 질문을 할 수 있으며, 이 경우 run 메서드를 다시 호출할 수 있습니다.
 
 #### 수동 대화 관리
 
-다음 턴의 입력을 얻기 위해 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용하여 conversation 기록을 수동으로 관리할 수 있습니다.
+다음 턴의 입력을 가져오려면 [`RunResultBase.to_input_list()`][agents.result.RunResultBase.to_input_list] 메서드를 사용해 대화 기록을 수동으로 관리할 수 있습니다.
 
 ```python
 async def main():
@@ -267,9 +294,9 @@ async def main():
         # California
 ```
 
-#### 세션을 사용한 자동 대화 관리
+#### 세션을 통한 자동 대화 관리
 
-더 간단한 접근 방식으로 [Sessions](sessions/index.md)를 사용하여 `.to_input_list()`를 수동으로 호출하지 않고 conversation 기록을 자동으로 처리할 수 있습니다.
+더 간단한 접근 방식으로 [Sessions](sessions/index.md)를 사용하면 `.to_input_list()`를 수동으로 호출하지 않고도 대화 기록을 자동으로 처리할 수 있습니다.
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -295,22 +322,22 @@ async def main():
 
 Sessions는 자동으로 다음을 수행합니다.
 
--   각 실행 전에 conversation 기록 검색
+-   각 실행 전에 대화 기록 가져오기
 -   각 실행 후 새 메시지 저장
--   서로 다른 세션 ID에 대해 별도의 conversation 유지
+-   서로 다른 세션 ID에 대해 별도의 대화 유지
 
-자세한 내용은 [Sessions 문서](sessions/index.md)를 참고하세요.
+자세한 내용은 [Sessions 문서](sessions/index.md)를 참조하세요.
 
 
 #### 서버 관리 대화
 
-`to_input_list()` 또는 `Sessions`를 사용해 로컬에서 처리하는 대신, OpenAI conversation state 기능이 서버 측에서 conversation 상태를 관리하도록 할 수도 있습니다. 이렇게 하면 과거 메시지를 모두 수동으로 다시 전송하지 않고도 conversation 기록을 보존할 수 있습니다. 아래 서버 관리 방식 중 하나를 사용할 때는 각 요청에 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참고하세요.
+`to_input_list()` 또는 `Sessions`로 로컬에서 처리하는 대신 OpenAI 대화 상태 기능이 서버 측에서 대화 상태를 관리하도록 할 수도 있습니다. 이를 통해 모든 과거 메시지를 수동으로 다시 보내지 않고도 대화 기록을 보존할 수 있습니다. 아래의 서버 관리 접근 방식 중 어느 것을 사용하든 각 요청에는 새 턴의 입력만 전달하고 저장된 ID를 재사용하세요. 자세한 내용은 [OpenAI 대화 상태 가이드](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)를 참조하세요.
 
 OpenAI는 턴 간 상태를 추적하는 두 가지 방법을 제공합니다.
 
 ##### 1. `conversation_id` 사용
 
-먼저 OpenAI Conversations API를 사용해 conversation을 만들고 이후 모든 호출에서 해당 ID를 재사용합니다.
+먼저 OpenAI Conversations API를 사용해 대화를 생성한 다음 이후 모든 호출에서 해당 ID를 재사용합니다.
 
 ```python
 from agents import Agent, Runner
@@ -333,7 +360,7 @@ async def main():
 
 ##### 2. `previous_response_id` 사용
 
-또 다른 옵션은 **response chaining**으로, 각 턴이 이전 턴의 response ID에 명시적으로 연결됩니다.
+또 다른 옵션은 각 턴이 이전 턴의 응답 ID에 명시적으로 연결되는 **응답 체이닝**입니다.
 
 ```python
 from agents import Agent, Runner
@@ -358,32 +385,33 @@ async def main():
         print(f"Assistant: {result.final_output}")
 ```
 
-승인을 위해 실행이 일시 중지되고 [`RunState`][agents.run_state.RunState]에서 재개하는 경우,
+실행이 승인을 위해 일시 중지되고 [`RunState`][agents.run_state.RunState]에서 재개하는 경우,
 SDK는 저장된 `conversation_id` / `previous_response_id` / `auto_previous_response_id`
-설정을 유지하여 재개된 턴이 동일한 서버 관리 conversation에서 계속되도록 합니다.
+설정을 유지하므로 재개된 턴은 동일한 서버 관리 대화에서 계속됩니다.
 
-`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간에 공유할 수 있는 이름 있는 conversation 리소스를 원하면 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API continuation 기본 구성 요소를 원하면 `previous_response_id`를 사용하세요.
+`conversation_id`와 `previous_response_id`는 상호 배타적입니다. 시스템 간에 공유할 수 있는 이름 있는 대화 리소스를 원하면 `conversation_id`를 사용하세요. 한 턴에서 다음 턴으로 이어지는 가장 가벼운 Responses API 연속 처리 기본 구성 요소를 원하면 `previous_response_id`를 사용하세요.
 
 !!! note
 
     SDK는 `conversation_locked` 오류를 backoff와 함께 자동으로 재시도합니다. 서버 관리
-    conversation 실행에서는 같은 준비된 항목을 깔끔하게 다시 전송할 수 있도록 재시도 전에
-    내부 conversation-tracker 입력을 되감습니다.
+    대화 실행에서는 재시도 전에 내부 대화 추적기 입력을 되감아 동일한 준비된 항목을
+    깔끔하게 다시 전송할 수 있게 합니다.
 
-    로컬 세션 기반 실행(`conversation_id`, `previous_response_id` 또는
-    `auto_previous_response_id`와 함께 사용할 수 없음)에서도 SDK는 재시도 후 기록 항목 중복을
-    줄이기 위해 최근 지속된 입력 항목을 최선 노력 방식으로 롤백합니다.
+    로컬 세션 기반 실행(`conversation_id`,
+    `previous_response_id` 또는 `auto_previous_response_id`와 결합할 수 없음)에서도 SDK는 재시도 후
+    중복 기록 항목을 줄이기 위해 최근 영속화된 입력 항목을 best-effort 방식으로
+    롤백합니다.
 
-    이 호환성 재시도는 `ModelSettings.retry`를 구성하지 않은 경우에도 발생합니다. 모델 요청에 대한
-    더 광범위한 옵트인 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참고하세요.
+    이 호환성 재시도는 `ModelSettings.retry`를 구성하지 않아도 발생합니다. 모델 요청에 대한
+    더 넓은 선택형 재시도 동작은 [Runner 관리 재시도](models/index.md#runner-managed-retries)를 참조하세요.
 
-## 훅 및 사용자 지정
+## 후크와 사용자 지정
 
-### 모델 입력 필터 호출
+### 모델 호출 입력 필터
 
-모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 훅은 현재 에이전트, 컨텍스트, 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새 `ModelInputData`를 반환합니다.
+모델 호출 직전에 모델 입력을 편집하려면 `call_model_input_filter`를 사용하세요. 이 후크는 현재 에이전트, 컨텍스트 및 결합된 입력 항목(있는 경우 세션 기록 포함)을 받고 새 `ModelInputData`를 반환합니다.
 
-반환 값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다.
+반환값은 [`ModelInputData`][agents.run.ModelInputData] 객체여야 합니다. 해당 `input` 필드는 필수이며 입력 항목 목록이어야 합니다. 다른 형태를 반환하면 `UserError`가 발생합니다.
 
 ```python
 from agents import Agent, Runner, RunConfig
@@ -402,19 +430,19 @@ result = Runner.run_sync(
 )
 ```
 
-runner는 준비된 입력 목록의 복사본을 훅에 전달하므로 호출자의 원본 목록을 제자리에서 변경하지 않고 잘라내거나, 대체하거나, 재정렬할 수 있습니다.
+runner는 준비된 입력 목록의 복사본을 후크에 전달하므로 호출자의 원래 목록을 제자리에서 변경하지 않고도 줄이거나, 대체하거나, 순서를 바꿀 수 있습니다.
 
-세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후 실행됩니다. 그보다 이른 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요.
+세션을 사용하는 경우 `call_model_input_filter`는 세션 기록이 이미 로드되어 현재 턴과 병합된 후에 실행됩니다. 더 이른 병합 단계 자체를 사용자 지정하려면 [`session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요.
 
-OpenAI 서버 관리 conversation 상태를 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 사용하는 경우, 훅은 다음 Responses API 호출을 위해 준비된 payload에서 실행됩니다. 해당 payload는 이전 기록의 전체 재생이 아니라 이미 새 턴 delta만 나타낼 수 있습니다. 반환한 항목만 해당 서버 관리 continuation에 전송된 것으로 표시됩니다.
+`conversation_id`, `previous_response_id` 또는 `auto_previous_response_id`와 함께 OpenAI 서버 관리 대화 상태를 사용하는 경우, 후크는 다음 Responses API 호출을 위해 준비된 payload에서 실행됩니다. 해당 payload는 이전 기록의 전체 replay가 아니라 새 턴 delta만 이미 나타낼 수 있습니다. 반환한 항목만 해당 서버 관리 연속 처리에 전송된 것으로 표시됩니다.
 
-민감한 데이터를 redact하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 삽입하려면 `run_config`를 통해 실행별로 훅을 설정하세요.
+민감한 데이터를 redact하거나, 긴 기록을 줄이거나, 추가 시스템 지침을 주입하려면 `run_config`를 통해 실행별로 후크를 설정하세요.
 
-## 오류 및 복구
+## 오류와 복구
 
 ### 오류 처리기
 
-모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 허용합니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하고 싶을 때 사용하세요.
+모든 `Runner` 진입점은 오류 종류를 키로 하는 dict인 `error_handlers`를 허용합니다. 지원되는 키는 `"max_turns"`와 `"model_refusal"`입니다. `MaxTurnsExceeded` 또는 `ModelRefusalError`를 발생시키는 대신 제어된 최종 출력을 반환하려는 경우 사용하세요.
 
 ```python
 from agents import (
@@ -443,9 +471,9 @@ result = Runner.run_sync(
 print(result.final_output)
 ```
 
-fallback 출력이 conversation 기록에 추가되지 않도록 하려면 `include_in_history=False`를 설정하세요.
+대체 출력이 대화 기록에 추가되는 것을 원하지 않으면 `include_in_history=False`를 설정하세요.
 
-모델 거부가 `ModelRefusalError`로 실행을 종료하는 대신 애플리케이션별 fallback을 생성해야 하는 경우 `"model_refusal"`을 사용하세요.
+모델 거부가 `ModelRefusalError`로 실행을 종료하는 대신 애플리케이션별 대체 출력을 생성해야 하는 경우 `"model_refusal"`을 사용하세요.
 
 ```python
 from pydantic import BaseModel
@@ -477,33 +505,37 @@ result = Runner.run_sync(
 print(result.final_output)
 ```
 
-## 지속 실행 통합 및 휴먼인더루프
+## 내구성 있는 실행 통합과 휴먼인더루프 (HITL)
 
-도구 승인 일시 중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)부터 시작하세요.
-아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸쳐 이어질 수 있는 지속 오케스트레이션을 위한 것입니다.
+도구 승인 일시 중지/재개 패턴은 전용 [휴먼인더루프 가이드](human_in_the_loop.md)에서 시작하세요.
+아래 통합은 실행이 긴 대기, 재시도 또는 프로세스 재시작에 걸쳐 이어질 수 있는 경우의 내구성 있는 오케스트레이션을 위한 것입니다.
+
+### Dapr
+
+Agents SDK [Dapr](https://dapr.io) Diagrid 통합을 사용하면 휴먼인더루프 지원으로 장애에서 자동 복구되는 내구성 있고 장시간 실행되는 에이전트를 실행할 수 있습니다. Dapr는 벤더 중립적인 [CNCF](https://cncf.io) 워크플로 오케스트레이터입니다. Dapr와 OpenAI 에이전트 시작하기는 [여기](https://docs.diagrid.io/getting-started/quickstarts/ai-agents/?agentframework=openai)에서 확인하세요.
 
 ### Temporal
 
-Agents SDK [Temporal](https://temporal.io/) 통합을 사용하여 휴먼인더루프 작업을 포함한 지속적이고 장기 실행되는 워크플로를 실행할 수 있습니다. 장기 실행 작업을 완료하기 위해 Temporal과 Agents SDK가 함께 동작하는 데모는 [이 동영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 볼 수 있으며, [문서는 여기에서 확인할 수 있습니다](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents).
+Agents SDK [Temporal](https://temporal.io/) 통합을 사용하면 휴먼인더루프 작업을 포함한 내구성 있고 장시간 실행되는 워크플로를 실행할 수 있습니다. Temporal과 Agents SDK가 함께 동작하여 장시간 실행 작업을 완료하는 데모는 [이 동영상](https://www.youtube.com/watch?v=fFBZqzT4DD8)에서 확인하고, [문서는 여기](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents)에서 확인하세요. 
 
 ### Restate
 
-Agents SDK [Restate](https://restate.dev/) 통합을 사용하여 사람 승인, 핸드오프 및 세션 관리를 포함한 경량의 지속 에이전트를 사용할 수 있습니다. 이 통합은 종속성으로 Restate의 단일 바이너리 런타임이 필요하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다.
-자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)를 읽거나 [문서](https://docs.restate.dev/ai)를 참고하세요.
+Agents SDK [Restate](https://restate.dev/) 통합을 사용하면 사람 승인, 핸드오프, 세션 관리를 포함한 경량의 내구성 있는 에이전트를 실행할 수 있습니다. 이 통합은 Restate의 단일 바이너리 런타임을 의존성으로 필요로 하며, 에이전트를 프로세스/컨테이너 또는 서버리스 함수로 실행하는 것을 지원합니다.
+자세한 내용은 [개요](https://www.restate.dev/blog/durable-orchestration-for-ai-agents-with-restate-and-openai-sdk)를 읽거나 [문서](https://docs.restate.dev/ai)를 참조하세요.
 
 ### DBOS
 
-Agents SDK [DBOS](https://dbos.dev/) 통합을 사용하여 실패와 재시작 전반에서 진행 상황을 보존하는 신뢰성 높은 에이전트를 실행할 수 있습니다. 장기 실행 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 참고하세요.
+Agents SDK [DBOS](https://dbos.dev/) 통합을 사용하면 장애와 재시작 전반에 걸쳐 진행 상황을 보존하는 신뢰성 있는 에이전트를 실행할 수 있습니다. 장시간 실행되는 에이전트, 휴먼인더루프 워크플로, 핸드오프를 지원합니다. 동기 및 비동기 메서드를 모두 지원합니다. 이 통합에는 SQLite 또는 Postgres 데이터베이스만 필요합니다. 자세한 내용은 통합 [repo](https://github.com/dbos-inc/dbos-openai-agents)와 [문서](https://docs.dbos.dev/integrations/openai-agents)를 참조하세요.
 
 ## 예외
 
 SDK는 특정 경우에 예외를 발생시킵니다. 전체 목록은 [`agents.exceptions`][]에 있습니다. 개요는 다음과 같습니다.
 
 -   [`AgentsException`][agents.exceptions.AgentsException]: SDK 내에서 발생하는 모든 예외의 기본 클래스입니다. 다른 모든 특정 예외가 파생되는 일반 타입 역할을 합니다.
--   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 이 예외는 에이전트 실행이 `Runner.run`, `Runner.run_sync` 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 한도를 초과할 때 발생합니다. 지정된 상호작용 턴 수 내에 에이전트가 작업을 완료하지 못했음을 나타냅니다.
--   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기본 모델(LLM)이 예상치 못했거나 유효하지 않은 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다.
-    -   잘못된 JSON: 모델이 도구 호출 또는 직접 출력에서, 특히 특정 `output_type`이 정의된 경우, 잘못된 JSON 구조를 제공할 때
-    -   예기치 않은 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못할 때
--   [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 이 예외는 함수 도구 호출이 구성된 timeout을 초과하고 해당 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다.
--   [`UserError`][agents.exceptions.UserError]: 이 예외는 SDK를 사용하는 코드 작성자인 사용자가 SDK 사용 중 오류를 만들 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성 또는 SDK API 오용으로 인해 발생합니다.
+-   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: 이 예외는 에이전트 실행이 `Runner.run`, `Runner.run_sync` 또는 `Runner.run_streamed` 메서드에 전달된 `max_turns` 제한을 초과할 때 발생합니다. 이는 에이전트가 지정된 상호작용 턴 수 내에 작업을 완료할 수 없었음을 나타냅니다. 제한을 비활성화하려면 `max_turns=None`을 설정하세요.
+-   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: 이 예외는 기반 모델(LLM)이 예상치 못한 출력 또는 유효하지 않은 출력을 생성할 때 발생합니다. 여기에는 다음이 포함될 수 있습니다.
+    -   잘못된 형식의 JSON: 모델이 도구 호출 또는 직접 출력에서 잘못된 형식의 JSON 구조를 제공하는 경우, 특히 특정 `output_type`이 정의된 경우
+    -   예상치 못한 도구 관련 실패: 모델이 예상된 방식으로 도구를 사용하지 못하는 경우
+-   [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]: 이 예외는 함수 도구 호출이 구성된 timeout을 초과하고 도구가 `timeout_behavior="raise_exception"`을 사용할 때 발생합니다.
+-   [`UserError`][agents.exceptions.UserError]: 이 예외는 SDK를 사용하는 코드를 작성하는 사용자(개발자)가 SDK 사용 중 오류를 만들었을 때 발생합니다. 일반적으로 잘못된 코드 구현, 유효하지 않은 구성 또는 SDK API의 오용으로 인해 발생합니다.
 -   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: 이 예외는 각각 입력 가드레일 또는 출력 가드레일의 조건이 충족될 때 발생합니다. 입력 가드레일은 처리 전에 들어오는 메시지를 확인하고, 출력 가드레일은 전달 전에 에이전트의 최종 응답을 확인합니다.

docs/ko/sandbox/clients.md

@@ -4,40 +4,40 @@ search:
 ---
 # 샌드박스 클라이언트
 
-이 페이지를 사용해 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 동일하게 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경됩니다.
+이 페이지를 사용하여 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 `SandboxAgent` 정의는 그대로 두고, [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 클라이언트별 옵션만 변경합니다.
 
 !!! warning "베타 기능"
 
-    샌드박스 에이전트는 베타입니다. 정식 출시 전까지 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+    샌드박스 에이전트는 베타입니다. API의 세부 사항, 기본값, 지원 기능은 정식 출시 전 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다.
 
-## 선택 가이드
+## 결정 가이드
 
 <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-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로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하면 됩니다.
+Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하세요.
 
 ```python
 from docker import from_env as docker_from_env
@@ -54,74 +54,74 @@ run_config = RunConfig(
 )
 ```
 
-컨테이너 격리 또는 이미지 일치가 필요할 때 이 방식을 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
+컨테이너 격리 또는 이미지 동등성이 필요할 때 사용하세요. [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
 
 ## 마운트와 원격 스토리지
 
-마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 내장 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스팅 공급자 전략은 `agents.extensions.sandbox` 또는 공급자별 확장 패키지에서 사용할 수 있습니다.
+마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 기본 제공 마운트 항목과 일반 전략은 `agents.sandbox.entries`에서 가져오세요. 호스티드 제공자 전략은 `agents.extensions.sandbox` 또는 제공자별 확장 패키지에서 사용할 수 있습니다.
 
 일반적인 마운트 옵션:
 
 - `mount_path`: 샌드박스에서 스토리지가 나타나는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다.
-- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 하는 경우에만 `False`로 설정하세요.
+- `read_only`: 기본값은 `True`입니다. 샌드박스가 마운트된 스토리지에 다시 써야 할 때만 `False`로 설정하세요.
 - `mount_strategy`: 필수입니다. 마운트 항목과 샌드박스 백엔드 모두에 맞는 전략을 사용하세요.
 
-마운트는 일시적인 작업공간 항목으로 처리됩니다. 스냅샷 및 영속화 흐름에서는 마운트된 원격 스토리지를 저장된 작업공간에 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
+마운트는 임시 워크스페이스 항목으로 취급됩니다. 스냅샷 및 지속성 플로우는 마운트된 원격 스토리지를 저장된 워크스페이스로 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
 
 일반 로컬/컨테이너 전략:
 
 <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) |
-| `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` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `ModalCloudBucketMountStrategy`를 사용한 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름 있는 Modal Secret을 사용할 수 있습니다. |
-| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증된 `GCSMount`에서 `CloudflareBucketMountStrategy`를 사용한 Cloudflare 버킷 마운트를 지원합니다. |
-| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`를 사용한 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 사용한 영구 Blaxel Drive도 지원합니다. |
-| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`를 사용한 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
-| `VercelSandboxClient` | 현재 호스팅 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소 또는 기타 작업공간 입력을 사용하세요. |
+| Docker | `InContainerMountStrategy` 및 `DockerVolumeMountStrategy` 같은 로컬 전략으로 `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount`를 지원합니다. |
+| `ModalSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `ModalCloudBucketMountStrategy`로 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다. |
+| `CloudflareSandboxClient` | `S3Mount`, `R2Mount`, HMAC 인증 `GCSMount`에서 `CloudflareBucketMountStrategy`로 Cloudflare 버킷 마운트를 지원합니다. |
+| `BlaxelSandboxClient` | `S3Mount`, `R2Mount`, `GCSMount`에서 `BlaxelCloudBucketMountStrategy`로 클라우드 버킷 마운트를 지원합니다. 또한 `agents.extensions.sandbox.blaxel`의 `BlaxelDriveMount` 및 `BlaxelDriveMountStrategy`를 통해 영구 Blaxel Drives도 지원합니다. |
+| `DaytonaSandboxClient` | `DaytonaCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `E2BSandboxClient` | `E2BCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `RunloopSandboxClient` | `RunloopCloudBucketMountStrategy`로 rclone 기반 클라우드 스토리지 마운트를 지원합니다. `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`와 함께 사용하세요. |
+| `VercelSandboxClient` | 현재 노출된 호스티드 전용 마운트 전략은 없습니다. 대신 매니페스트 파일, 리포지토리 또는 기타 워크스페이스 입력을 사용하세요. |
 
 </div>
 
-아래 표는 각 백엔드가 어떤 원격 스토리지 항목을 직접 마운트할 수 있는지 요약합니다.
+아래 표는 각 백엔드가 직접 마운트할 수 있는 원격 스토리지 항목을 요약합니다.
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
@@ -138,4 +138,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)를 둘러보세요.

docs/ko/sandbox/guide.md

@@ -6,35 +6,35 @@ search:
 
 !!! warning "베타 기능"
 
-    Sandbox 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+    샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
 
-최신 에이전트는 파일시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. **Sandbox 에이전트**는 특수 도구와 셸 명령을 사용해 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 에이전트가 사용자를 대신해 작업하는 데 사용할 수 있는 지속적 워크스페이스를 모델에 제공합니다. Agents SDK의 Sandbox 에이전트는 샌드박스 환경과 결합된 에이전트를 쉽게 실행하도록 도와주며, 적절한 파일을 파일시스템에 배치하고 샌드박스를 오케스트레이션하여 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다.
+현대적인 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. **샌드박스 에이전트**는 특화된 도구와 셸 명령을 사용하여 대규모 문서 세트를 검색 및 조작하고, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 모델에 지속적인 작업 공간을 제공하며, 에이전트는 이를 사용해 사용자를 대신하여 작업을 수행할 수 있습니다. Agents SDK의 샌드박스 에이전트는 샌드박스 환경과 결합된 에이전트를 쉽게 실행할 수 있도록 도와주며, 파일 시스템에 적절한 파일을 배치하고 샌드박스를 조율하여 대규모로 작업을 쉽게 시작, 중지, 재개할 수 있게 합니다.
 
-에이전트가 필요로 하는 데이터를 중심으로 워크스페이스를 정의합니다. GitHub 저장소, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일시스템, 그리고 사용자가 제공하는 다른 샌드박스 입력에서 시작할 수 있습니다.
+에이전트가 필요로 하는 데이터를 중심으로 작업 공간을 정의합니다. GitHub 리포지토리, 로컬 파일 및 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일 시스템, 그리고 사용자가 제공하는 기타 샌드박스 입력에서 시작할 수 있습니다.
 
 <div class="sandbox-harness-image" markdown="1">
 
-![컴퓨트가 포함된 Sandbox 에이전트 하니스](../assets/images/harness_with_compute.png)
+![컴퓨팅이 포함된 샌드박스 에이전트 하네스](../assets/images/harness_with_compute.png)
 
 </div>
 
-`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.
+`SandboxAgent`는 여전히 `Agent`입니다. `instructions`, `prompt`, `tools`, `handoffs`, `mcp_servers`, `model_settings`, `output_type`, 가드레일, 훅 같은 일반적인 에이전트 표면을 유지하며, 여전히 일반 `Runner` API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다:
 
-- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값, 파일시스템 도구, 셸 접근, 스킬, 메모리 또는 컴팩션 같은 기능을 포함합니다.
-- `Manifest`는 파일, 저장소, 마운트, 환경을 포함하여 새 샌드박스 워크스페이스의 원하는 시작 콘텐츠와 레이아웃을 선언합니다.
+- `SandboxAgent`는 에이전트 자체를 정의합니다. 일반적인 에이전트 구성에 더해 `default_manifest`, `base_instructions`, `run_as` 같은 샌드박스별 기본값과 파일 시스템 도구, 셸 접근, 스킬, 메모리, 컴팩션 같은 기능을 포함합니다.
+- `Manifest`는 파일, 리포지토리, 마운트, 환경을 포함하여 새 샌드박스 작업 공간의 원하는 시작 콘텐츠와 레이아웃을 선언합니다.
 - 샌드박스 세션은 명령이 실행되고 파일이 변경되는 라이브 격리 환경입니다.
-- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 실행이 해당 샌드박스 세션을 어떻게 얻을지 결정합니다. 예를 들어 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성할 수 있습니다.
-- 저장된 샌드박스 상태와 스냅샷을 통해 이후 실행이 이전 작업에 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시작할 수 있습니다.
+- [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성하는 방식으로 실행이 해당 샌드박스 세션을 얻는 방법을 결정합니다.
+- 저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 시드할 수 있습니다.
 
-`Manifest`는 새 세션 워크스페이스 계약이지, 모든 라이브 샌드박스에 대한 전체 진실의 원천은 아닙니다. 실행의 실제 워크스페이스는 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시 선택된 스냅샷에서 올 수도 있습니다.
+`Manifest`는 새 세션 작업 공간 계약이지, 모든 라이브 샌드박스에 대한 전체 기준 정보는 아닙니다. 실행의 유효 작업 공간은 대신 재사용된 샌드박스 세션, 직렬화된 샌드박스 세션 상태, 또는 실행 시 선택된 스냅샷에서 올 수 있습니다.
 
 이 페이지 전체에서 "샌드박스 세션"은 샌드박스 클라이언트가 관리하는 라이브 실행 환경을 의미합니다. 이는 [Sessions](../sessions/index.md)에 설명된 SDK의 대화형 [`Session`][agents.memory.session.Session] 인터페이스와 다릅니다.
 
-외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 북키핑을 소유합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 소유합니다. 이 분리는 모델의 핵심 부분입니다.
+외부 런타임은 여전히 승인, 트레이싱, 핸드오프, 재개 bookkeeping을 담당합니다. 샌드박스 세션은 명령, 파일 변경, 환경 격리를 담당합니다. 이러한 분리는 이 모델의 핵심입니다.
 
-### 구성 요소의 조합
+### 구성 요소의 결합 방식
 
-샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. runner는 에이전트를 준비하고 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
+샌드박스 실행은 에이전트 정의와 실행별 샌드박스 구성을 결합합니다. runner는 에이전트를 준비하고, 라이브 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.
 
 ```mermaid
 flowchart LR
@@ -52,31 +52,31 @@ flowchart LR
 
 샌드박스별 기본값은 `SandboxAgent`에 유지됩니다. 실행별 샌드박스 세션 선택은 `SandboxRunConfig`에 유지됩니다.
 
-라이프사이클을 세 단계로 생각해 보세요.
+수명 주기를 세 단계로 생각해 보세요:
 
-1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 워크스페이스 계약을 정의합니다.
-2. 샌드박스 세션을 주입, 재개 또는 생성하는 `SandboxRunConfig`를 `Runner`에 제공하여 실행을 수행합니다.
-3. runner가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 워크스페이스 스냅샷에서 나중에 이어서 진행합니다.
+1. `SandboxAgent`, `Manifest`, 기능으로 에이전트와 새 작업 공간 계약을 정의합니다.
+2. `Runner`에 샌드박스 세션을 주입, 재개, 또는 생성하는 `SandboxRunConfig`를 제공하여 실행을 수행합니다.
+3. runner가 관리하는 `RunState`, 명시적 샌드박스 `session_state`, 또는 저장된 작업 공간 스냅샷에서 나중에 이어서 진행합니다.
 
-셸 접근이 가끔 사용하는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부일 때 샌드박스 에이전트를 사용하세요.
+셸 접근이 가끔 사용하는 도구 하나에 불과하다면 [도구 가이드](../tools.md)의 호스티드 셸로 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택, 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 선택하세요.
 
 ## 사용 시점
 
-샌드박스 에이전트는 다음과 같은 워크스페이스 중심 워크플로에 적합합니다.
+샌드박스 에이전트는 작업 공간 중심 워크플로에 적합합니다. 예를 들면 다음과 같습니다:
 
-- 코딩 및 디버깅. 예를 들어 GitHub 저장소의 이슈 보고서에 대한 자동 수정 오케스트레이션과 대상 테스트 실행
-- 문서 처리 및 편집. 예를 들어 사용자의 금융 문서에서 정보를 추출하고 작성된 세금 양식 초안 생성
-- 파일 기반 검토 또는 분석. 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 아티팩트 번들 확인
-- 격리된 다중 에이전트 패턴. 예를 들어 각 리뷰어 또는 코딩 하위 에이전트에 자체 워크스페이스 제공
-- 다단계 워크스페이스 작업. 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개
+- 코딩 및 디버깅, 예를 들어 GitHub 리포지토리의 이슈 보고에 대한 자동 수정 조율과 대상 테스트 실행
+- 문서 처리 및 편집, 예를 들어 사용자의 재무 문서에서 정보를 추출하고 완성된 세금 양식 초안 작성
+- 파일 기반 검토 또는 분석, 예를 들어 답변 전에 온보딩 패킷, 생성된 보고서, 아티팩트 번들 확인
+- 격리된 멀티 에이전트 패턴, 예를 들어 각 검토자나 코딩 하위 에이전트에 자체 작업 공간 제공
+- 다단계 작업 공간 태스크, 예를 들어 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개
 
-파일이나 살아 있는 파일시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 워크스페이스 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
+파일이나 살아 있는 파일 시스템에 접근할 필요가 없다면 `Agent`를 계속 사용하세요. 셸 접근이 가끔 필요한 기능 하나라면 호스티드 셸을 추가하세요. 작업 공간 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.
 
 ## 샌드박스 클라이언트 선택
 
-로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리 또는 이미지 동등성이 필요할 때 `DockerSandboxClient`로 이동하세요. 제공자 관리 실행이 필요할 때 호스티드 제공자로 이동하세요.
+로컬 개발에는 `UnixLocalSandboxClient`로 시작하세요. 컨테이너 격리나 이미지 일관성이 필요하면 `DockerSandboxClient`로 이동하세요. 제공자 관리 실행이 필요하면 호스티드 제공자로 이동하세요.
 
-대부분의 경우 `SandboxAgent` 정의는 그대로 두고, 샌드박스 클라이언트와 해당 옵션만 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 변경합니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
+대부분의 경우 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에서 샌드박스 클라이언트와 그 옵션만 변경되며, `SandboxAgent` 정의는 그대로 유지됩니다. 로컬, Docker, 호스티드, 원격 마운트 옵션은 [샌드박스 클라이언트](clients.md)를 참고하세요.
 
 ## 핵심 구성 요소
 
@@ -84,167 +84,171 @@ flowchart LR
 
 | 계층 | 주요 SDK 구성 요소 | 답하는 질문 |
 | --- | --- | --- |
-| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 워크스페이스 계약에서 시작해야 하나요? |
-| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 어떻게 라이브 샌드박스 세션을 얻으며, 작업은 어디서 실행되나요? |
-| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠에서 새 샌드박스 세션을 시작하나요? |
+| 에이전트 정의 | `SandboxAgent`, `Manifest`, 기능 | 어떤 에이전트가 실행되며, 어떤 새 세션 작업 공간 계약에서 시작해야 하나요? |
+| 샌드박스 실행 | `SandboxRunConfig`, 샌드박스 클라이언트, 라이브 샌드박스 세션 | 이 실행은 어떻게 라이브 샌드박스 세션을 얻으며, 작업은 어디에서 실행되나요? |
+| 저장된 샌드박스 상태 | `RunState` 샌드박스 페이로드, `session_state`, 스냅샷 | 이 워크플로는 어떻게 이전 샌드박스 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 시드하나요? |
 
 </div>
 
-주요 SDK 구성 요소는 다음과 같이 이러한 계층에 매핑됩니다.
+주요 SDK 구성 요소는 이러한 계층에 다음과 같이 대응됩니다:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 구성 요소 | 소유 대상 | 질문 |
+| 구성 요소 | 담당 범위 | 질문 |
 | --- | --- | --- |
 | [`SandboxAgent`][agents.sandbox.sandbox_agent.SandboxAgent] | 에이전트 정의 | 이 에이전트는 무엇을 해야 하며, 어떤 기본값이 함께 이동해야 하나요? |
-| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 워크스페이스 파일과 폴더 | 실행 시작 시 파일시스템에 어떤 파일과 폴더가 있어야 하나요? |
-| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 이 에이전트에 어떤 도구, instruction 조각, 또는 런타임 동작을 연결해야 하나요? |
-| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트와 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 생성 중 무엇으로 처리해야 하나요? |
-| [`RunState`][agents.run_state.RunState] | runner가 관리하는 저장된 샌드박스 상태 | 이전 runner 관리 워크플로를 재개하고 그 샌드박스 상태를 자동으로 이어가고 있나요? |
+| [`Manifest`][agents.sandbox.manifest.Manifest] | 새 세션 작업 공간 파일 및 폴더 | 실행이 시작될 때 파일 시스템에 어떤 파일과 폴더가 있어야 하나요? |
+| [`Capability`][agents.sandbox.capabilities.capability.Capability] | 샌드박스 네이티브 동작 | 이 에이전트에 어떤 도구, 지침 조각, 또는 런타임 동작을 연결해야 하나요? |
+| [`SandboxRunConfig`][agents.run_config.SandboxRunConfig] | 실행별 샌드박스 클라이언트 및 샌드박스 세션 소스 | 이 실행은 샌드박스 세션을 주입, 재개, 또는 생성해야 하나요? |
+| [`RunState`][agents.run_state.RunState] | runner가 관리하는 저장된 샌드박스 상태 | 이전 runner 관리 워크플로를 재개하고 그 샌드박스 상태를 자동으로 이어받고 있나요? |
 | [`SandboxRunConfig.session_state`][agents.run_config.SandboxRunConfig.session_state] | 명시적으로 직렬화된 샌드박스 세션 상태 | `RunState` 외부에서 이미 직렬화한 샌드박스 상태에서 재개하고 싶나요? |
-| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션을 위한 저장된 워크스페이스 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하나요? |
+| [`SandboxRunConfig.snapshot`][agents.run_config.SandboxRunConfig.snapshot] | 새 샌드박스 세션을 위한 저장된 작업 공간 콘텐츠 | 새 샌드박스 세션이 저장된 파일과 아티팩트에서 시작해야 하나요? |
 
 </div>
 
-실용적인 설계 순서는 다음과 같습니다.
+실용적인 설계 순서는 다음과 같습니다:
 
-1. `Manifest`로 새 세션 워크스페이스 계약을 정의합니다.
+1. `Manifest`로 새 세션 작업 공간 계약을 정의합니다.
 2. `SandboxAgent`로 에이전트를 정의합니다.
-3. 내장 또는 사용자 지정 기능을 추가합니다.
-4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 어떻게 얻을지 결정합니다.
+3. 기본 제공 또는 사용자 지정 기능을 추가합니다.
+4. 각 실행이 `RunConfig(sandbox=SandboxRunConfig(...))`에서 샌드박스 세션을 얻는 방식을 결정합니다.
 
 ## 샌드박스 실행 준비 방식
 
-실행 시 runner는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.
+실행 시 runner는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다:
 
-1. `SandboxRunConfig`에서 샌드박스 세션을 해석합니다.
+1. `SandboxRunConfig`에서 샌드박스 세션을 확인합니다.
    `session=...`을 전달하면 해당 라이브 샌드박스 세션을 재사용합니다.
    그렇지 않으면 `client=...`를 사용해 세션을 생성하거나 재개합니다.
-2. 실행의 실제 워크스페이스 입력을 결정합니다.
-   실행이 샌드박스 세션을 주입하거나 재개하면 해당 기존 샌드박스 상태가 우선합니다.
-   그렇지 않으면 runner는 일회성 manifest 재정의 또는 `agent.default_manifest`에서 시작합니다.
-   이것이 `Manifest`만으로는 모든 실행의 최종 라이브 워크스페이스를 정의하지 않는 이유입니다.
-3. 기능이 결과 manifest를 처리하도록 합니다.
-   이를 통해 최종 에이전트가 준비되기 전에 기능이 파일, 마운트 또는 다른 워크스페이스 범위 동작을 추가할 수 있습니다.
-4. 고정된 순서로 최종 instructions를 구성합니다.
-   SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 `base_instructions`, 그다음 `instructions`, 그다음 기능 instruction 조각, 그다음 원격 마운트 정책 텍스트, 그다음 렌더링된 파일시스템 트리입니다.
+2. 실행의 유효 작업 공간 입력을 결정합니다.
+   실행이 샌드박스 세션을 주입하거나 재개하는 경우, 기존 샌드박스 상태가 우선합니다.
+   그렇지 않으면 runner는 일회성 매니페스트 오버라이드 또는 `agent.default_manifest`에서 시작합니다.
+   이 때문에 `Manifest`만으로 모든 실행의 최종 라이브 작업 공간이 정의되지는 않습니다.
+3. 기능이 결과 매니페스트를 처리하도록 합니다.
+   이를 통해 기능은 최종 에이전트가 준비되기 전에 파일, 마운트, 또는 기타 작업 공간 범위 동작을 추가할 수 있습니다.
+4. 고정된 순서로 최종 instructions를 구성합니다:
+   SDK의 기본 샌드박스 프롬프트, 또는 명시적으로 오버라이드한 경우 `base_instructions`, 그다음 `instructions`, 기능 지침 조각, 원격 마운트 정책 텍스트, 렌더링된 파일 시스템 트리 순서입니다.
 5. 기능 도구를 라이브 샌드박스 세션에 바인딩하고 준비된 에이전트를 일반 `Runner` API를 통해 실행합니다.
 
-샌드박싱은 turn의 의미를 바꾸지 않습니다. turn은 여전히 모델 단계이지, 단일 셸 명령이나 샌드박스 작업이 아닙니다. 샌드박스 측 작업과 turn 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머무를 수 있고, 다른 작업은 도구 결과, 승인 또는 다른 상태를 반환하여 또 다른 모델 단계가 필요할 수 있습니다. 실용적인 규칙으로, 샌드박스 작업이 발생한 뒤 에이전트 런타임에 또 다른 모델 응답이 필요할 때만 또 다른 turn이 소비됩니다.
+샌드박싱은 턴의 의미를 바꾸지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 동작이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 매핑이 없습니다. 일부 작업은 샌드박스 실행 계층 내부에 머무를 수 있고, 다른 작업은 또 다른 모델 단계가 필요한 도구 결과, 승인, 또는 기타 상태를 반환할 수 있습니다. 실용적인 규칙으로는, 샌드박스 작업이 발생한 뒤 에이전트 런타임이 또 다른 모델 응답을 필요로 할 때만 추가 턴이 소비됩니다.
 
-이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 생각해야 할 주요 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다.
+이러한 준비 단계 때문에 `SandboxAgent`를 설계할 때 주로 고려해야 하는 샌드박스별 옵션은 `default_manifest`, `instructions`, `base_instructions`, `capabilities`, `run_as`입니다.
 
 ## `SandboxAgent` 옵션
 
-일반적인 `Agent` 필드에 추가되는 샌드박스별 옵션은 다음과 같습니다.
+다음은 일반적인 `Agent` 필드에 더해 제공되는 샌드박스별 옵션입니다:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 옵션 | 최적의 사용 |
+| 옵션 | 권장 사용처 |
 | --- | --- |
-| `default_manifest` | runner가 생성하는 새 샌드박스 세션의 기본 워크스페이스 |
+| `default_manifest` | runner가 생성하는 새 샌드박스 세션의 기본 작업 공간 |
 | `instructions` | SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로, 성공 기준 |
-| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 탈출구 |
-| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구와 동작 |
-| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대면 샌드박스 도구의 사용자 ID |
+| `base_instructions` | SDK 샌드박스 프롬프트를 대체하는 고급 우회 수단 |
+| `capabilities` | 이 에이전트와 함께 이동해야 하는 샌드박스 네이티브 도구 및 동작 |
+| `run_as` | 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구의 사용자 ID |
 
 </div>
 
-샌드박스 클라이언트 선택, 샌드박스 세션 재사용, manifest 재정의, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다.
+샌드박스 클라이언트 선택, 샌드박스 세션 재사용, 매니페스트 오버라이드, 스냅샷 선택은 에이전트가 아니라 [`SandboxRunConfig`][agents.run_config.SandboxRunConfig]에 속합니다.
 
 ### `default_manifest`
 
-`default_manifest`는 runner가 이 에이전트에 대해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 보통 시작해야 하는 파일, 저장소, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
+`default_manifest`는 runner가 이 에이전트를 위해 새 샌드박스 세션을 생성할 때 사용하는 기본 [`Manifest`][agents.sandbox.manifest.Manifest]입니다. 에이전트가 일반적으로 시작해야 하는 파일, 리포지토리, 보조 자료, 출력 디렉터리, 마운트에 사용하세요.
 
-이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 재정의할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 워크스페이스 상태를 유지합니다.
+이는 기본값일 뿐입니다. 실행은 `SandboxRunConfig(manifest=...)`로 이를 오버라이드할 수 있으며, 재사용되거나 재개된 샌드박스 세션은 기존 작업 공간 상태를 유지합니다.
 
 ### `instructions` 및 `base_instructions`
 
-서로 다른 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 내장 샌드박스 가이드를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
+여러 프롬프트에서도 유지되어야 하는 짧은 규칙에는 `instructions`를 사용하세요. `SandboxAgent`에서 이러한 instructions는 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 안내를 유지하면서 자체 역할, 워크플로, 성공 기준을 추가할 수 있습니다.
 
 SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 `base_instructions`를 사용하세요. 대부분의 에이전트는 이를 설정하지 않아야 합니다.
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| 넣을 위치 | 용도 | 예시 |
+| 위치 | 용도 | 예시 |
 | --- | --- | --- |
-| `instructions` | 에이전트의 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검토한 다음 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
-| `base_instructions` | SDK 샌드박스 기본 프롬프트의 완전한 대체 | 사용자 지정 저수준 샌드박스 래퍼 프롬프트 |
-| 사용자 프롬프트 | 이 실행의 일회성 요청 | "이 워크스페이스를 요약하세요." |
-| manifest의 워크스페이스 파일 | 더 긴 작업 명세, 저장소 로컬 instructions, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
+| `instructions` | 에이전트를 위한 안정적인 역할, 워크플로 규칙, 성공 기준 | "온보딩 문서를 검사한 다음 핸드오프하세요.", "최종 파일을 `output/`에 작성하세요." |
+| `base_instructions` | SDK 샌드박스 기본 프롬프트의 전체 대체 | 사용자 지정 저수준 샌드박스 래퍼 프롬프트 |
+| 사용자 프롬프트 | 이 실행을 위한 일회성 요청 | "이 작업 공간을 요약하세요." |
+| 매니페스트의 작업 공간 파일 | 더 긴 작업 사양, 리포지토리 로컬 지침, 또는 범위가 제한된 참고 자료 | `repo/task.md`, 문서 번들, 샘플 패킷 |
 
 </div>
 
-`instructions`의 좋은 사용 예는 다음과 같습니다.
+`instructions`의 좋은 사용 예는 다음과 같습니다:
 
-- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요할 때 에이전트를 하나의 대화형 프로세스에 유지합니다.
-- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 샌드박스 리뷰어가 검사 후 사용자에게 직접 답변하는 것을 금지합니다.
-- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종으로 채워진 파일이 실제로 `output/`에 저장되도록 요구합니다.
-- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 워크스페이스 루트 기준 패치 경로를 명확히 합니다.
+- [examples/sandbox/unix_local_pty.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/unix_local_pty.py)는 PTY 상태가 중요한 경우 에이전트를 하나의 인터랙티브 프로세스 안에 유지합니다.
+- [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)는 검사 후 샌드박스 검토자가 사용자에게 직접 답변하는 것을 금지합니다.
+- [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)는 최종 작성 파일이 실제로 `output/`에 저장되도록 요구합니다.
+- [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)는 정확한 검증 명령을 고정하고 작업 공간 루트 기준 패치 경로를 명확히 합니다.
 
-사용자의 일회성 작업을 `instructions`에 복사하거나, manifest에 속해야 하는 긴 참고 자료를 포함하거나, 내장 기능이 이미 주입하는 도구 문서를 다시 서술하거나, 런타임에 모델에 필요하지 않은 로컬 설치 메모를 섞지 마세요.
+사용자의 일회성 작업을 `instructions`에 복사하거나, 매니페스트에 속해야 하는 긴 참고 자료를 삽입하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 실행 시 필요로 하지 않는 로컬 설치 노트를 섞지 마세요.
 
-`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대면 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다.
+`instructions`를 생략해도 SDK는 기본 샌드박스 프롬프트를 포함합니다. 이는 저수준 래퍼에는 충분하지만, 대부분의 사용자 대상 에이전트는 여전히 명시적인 `instructions`를 제공해야 합니다.
 
 ### `capabilities`
 
-기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 실행 시작 전에 워크스페이스를 형성하고, 샌드박스별 instructions를 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작 또는 입력 처리를 조정할 수 있습니다.
+기능은 샌드박스 네이티브 동작을 `SandboxAgent`에 연결합니다. 기능은 실행이 시작되기 전에 작업 공간을 구성하고, 샌드박스별 지침을 추가하고, 라이브 샌드박스 세션에 바인딩되는 도구를 노출하고, 해당 에이전트의 모델 동작이나 입력 처리를 조정할 수 있습니다.
 
-내장 기능은 다음과 같습니다.
+기본 제공 기능에는 다음이 포함됩니다:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
 | 기능 | 추가할 때 | 참고 |
 | --- | --- | --- |
-| `Shell` | 에이전트에 셸 접근이 필요할 때 | `exec_command`를 추가하고, 샌드박스 클라이언트가 PTY 상호작용을 지원할 때 `write_stdin`도 추가합니다. |
-| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 할 때 | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 워크스페이스 루트 기준입니다. |
-| `Skills` | 샌드박스에서 스킬 검색과 구체화가 필요할 때 | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이를 선호하세요. `Skills`가 스킬을 인덱싱하고 샌드박스에 구체화합니다. |
-| `Memory` | 후속 실행이 메모리 아티팩트를 읽거나 생성해야 할 때 | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. |
-| `Compaction` | 장기 실행 흐름이 컴팩션 항목 이후 컨텍스트 트리밍을 필요로 할 때 | 모델 샘플링과 입력 처리를 조정합니다. |
+| `Shell` | 에이전트에 셸 접근이 필요합니다. | `exec_command`를 추가하고, 샌드박스 클라이언트가 PTY 상호작용을 지원하는 경우 `write_stdin`도 추가합니다. |
+| `Filesystem` | 에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 합니다. | `apply_patch`와 `view_image`를 추가합니다. 패치 경로는 작업 공간 루트 기준 상대 경로입니다. |
+| `Skills` | 샌드박스에서 스킬 탐색과 구체화를 사용하고 싶습니다. | `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 대신 이를 선호하세요. `Skills`는 스킬을 인덱싱하고 샌드박스 안에 구체화해 줍니다. |
+| `Memory` | 후속 실행에서 메모리 아티팩트를 읽거나 생성해야 합니다. | `Shell`이 필요합니다. 라이브 업데이트에는 `Filesystem`도 필요합니다. |
+| `Compaction` | 장기 실행 흐름에서 컴팩션 항목 이후 컨텍스트 줄이기가 필요합니다. | 모델 샘플링과 입력 처리를 조정합니다. |
 
 </div>
 
-기본적으로 `SandboxAgent.capabilities`는 `Filesystem()`, `Shell()`, `Compaction()`을 포함하는 `Capabilities.default()`를 사용합니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 여전히 원하는 기본 기능이 있다면 포함하세요.
+기본적으로 `SandboxAgent.capabilities`는 `Capabilities.default()`를 사용하며, 여기에는 `Filesystem()`, `Shell()`, `Compaction()`이 포함됩니다. `capabilities=[...]`를 전달하면 해당 목록이 기본값을 대체하므로, 계속 사용하려는 기본 기능을 포함하세요.
 
-스킬의 경우, 어떻게 구체화할지에 따라 소스를 선택하세요.
+스킬의 경우 원하는 구체화 방식에 따라 소스를 선택하세요:
 
-- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있으므로 더 큰 로컬 스킬 디렉터리에 좋은 기본값입니다.
-- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일시스템에서 읽습니다. 샌드박스 이미지나 워크스페이스 내부에만 존재하는 경로가 아니라 원래의 호스트 측 스킬 디렉터리를 전달하세요.
+- `Skills(lazy_from=LocalDirLazySkillSource(...))`는 큰 로컬 스킬 디렉터리에 적합한 기본값입니다. 모델이 먼저 인덱스를 발견하고 필요한 것만 로드할 수 있기 때문입니다.
+- `LocalDirLazySkillSource(source=LocalDir(src=...))`는 SDK 프로세스가 실행 중인 파일 시스템에서 읽습니다. 샌드박스 이미지나 작업 공간 내부에만 존재하는 경로가 아니라, 원래의 호스트 측 스킬 디렉터리를 전달하세요.
 - `Skills(from_=LocalDir(src=...))`는 미리 스테이징하려는 작은 로컬 번들에 더 적합합니다.
-- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 저장소에서 와야 할 때 적합합니다.
+- `Skills(from_=GitRepo(repo=..., ref=...))`는 스킬 자체가 리포지토리에서 와야 할 때 적합합니다.
 
-`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 워크스페이스 내부의 상대 대상 경로입니다.
+`LocalDir.src`는 SDK 호스트의 소스 경로입니다. `skills_path`는 `load_skill`이 호출될 때 스킬이 스테이징되는 샌드박스 작업 공간 내부의 상대 대상 경로입니다.
 
-스킬이 이미 `.agents/skills/<name>/SKILL.md` 같은 디스크 위치에 있다면, 해당 소스 루트를 `LocalDir(...)`로 지정하되, 여전히 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 워크스페이스 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요.
+스킬이 이미 `.agents/skills/<name>/SKILL.md` 같은 위치 아래 디스크에 있다면, `LocalDir(...)`가 해당 소스 루트를 가리키도록 하고 그래도 `Skills(...)`를 사용해 노출하세요. 다른 샌드박스 내부 레이아웃에 의존하는 기존 작업 공간 계약이 없다면 기본 `skills_path=".agents"`를 유지하세요.
 
-적합할 때는 내장 기능을 선호하세요. 내장 기능이 제공하지 않는 샌드박스별 도구나 instruction 표면이 필요할 때만 사용자 지정 기능을 작성하세요.
+적합한 경우 기본 제공 기능을 선호하세요. 기본 제공 기능이 다루지 않는 샌드박스별 도구나 지침 표면이 필요할 때만 사용자 지정 기능을 작성하세요.
 
 ## 개념
 
-### Manifest
+### 매니페스트
 
-[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 워크스페이스를 설명합니다. 워크스페이스 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 저장소를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자 또는 그룹을 정의하고, 워크스페이스 외부의 특정 절대 경로에 접근 권한을 부여할 수 있습니다.
+[`Manifest`][agents.sandbox.manifest.Manifest]는 새 샌드박스 세션의 작업 공간을 설명합니다. 작업 공간 `root`를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사해 넣고, Git 리포지토리를 클론하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자나 그룹을 정의하고, 작업 공간 외부의 특정 절대 경로에 대한 접근 권한을 부여할 수 있습니다.
 
-Manifest 항목 경로는 워크스페이스 기준 상대 경로입니다. 절대 경로가 될 수 없고 `..`로 워크스페이스를 벗어날 수 없으므로, 워크스페이스 계약은 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
+매니페스트 항목 경로는 작업 공간 기준 상대 경로입니다. 절대 경로일 수 없으며 `..`로 작업 공간을 벗어날 수 없습니다. 이를 통해 작업 공간 계약이 로컬, Docker, 호스티드 클라이언트 전반에서 이식 가능하게 유지됩니다.
 
-작업이 시작되기 전에 에이전트가 필요로 하는 자료에는 manifest 항목을 사용하세요.
+작업이 시작되기 전에 에이전트가 필요로 하는 자료에는 매니페스트 항목을 사용하세요:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
-| Manifest 항목 | 용도 |
+| 매니페스트 항목 | 용도 |
 | --- | --- |
 | `File`, `Dir` | 작은 합성 입력, 보조 파일, 또는 출력 디렉터리 |
-| `LocalFile`, `LocalDir` | 샌드박스에 구체화해야 하는 호스트 파일 또는 디렉터리 |
-| `GitRepo` | 워크스페이스로 가져와야 하는 저장소 |
+| `LocalFile`, `LocalDir` | 샌드박스 안에 구체화해야 하는 호스트 파일 또는 디렉터리 |
+| `GitRepo` | 작업 공간으로 가져와야 하는 리포지토리 |
 | `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, `BoxMount`, `S3FilesMount` 같은 마운트 | 샌드박스 내부에 나타나야 하는 외부 스토리지 |
 
 </div>
 
-마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 제공자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참조하세요.
+`Dir`는 합성 자식 항목에서 또는 출력 위치로 샌드박스 작업 공간 안에 디렉터리를 생성합니다. 호스트 파일 시스템에서 읽지는 않습니다. 기존 호스트 디렉터리를 샌드박스 작업 공간으로 복사해야 할 때는 `LocalDir`를 사용하세요.
 
-좋은 manifest 설계는 일반적으로 워크스페이스 계약을 좁게 유지하고, 긴 작업 레시피는 `repo/task.md` 같은 워크스페이스 파일에 넣으며, instructions에서는 `repo/task.md` 또는 `output/report.md` 같은 상대 워크스페이스 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 워크스페이스 루트 기준이라는 점을 기억하세요.
+`LocalFile.src`와 `LocalDir.src`는 기본적으로 SDK 프로세스 작업 디렉터리를 기준으로 확인됩니다. 소스는 `extra_path_grants`로 포함되지 않는 한 해당 기본 디렉터리 아래에 있어야 합니다. 이를 통해 로컬 소스 구체화가 나머지 샌드박스 매니페스트와 동일한 호스트 경로 신뢰 경계 안에 유지됩니다.
 
-에이전트가 워크스페이스 외부의 구체적인 절대 경로가 필요할 때만 `extra_path_grants`를 사용하세요. 예를 들어 임시 도구 출력을 위한 `/tmp` 또는 읽기 전용 런타임을 위한 `/opt/toolchain`입니다. grant는 SDK 파일 API와, 백엔드가 파일시스템 정책을 강제할 수 있는 경우 셸 실행 모두에 적용됩니다.
+마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션과 제공자 지원은 [샌드박스 클라이언트](clients.md#mounts-and-remote-storage)를 참고하세요.
+
+좋은 매니페스트 설계란 일반적으로 작업 공간 계약을 좁게 유지하고, 긴 작업 지침은 `repo/task.md` 같은 작업 공간 파일에 넣고, 지침에서는 `repo/task.md` 또는 `output/report.md` 같은 작업 공간 상대 경로를 사용하는 것을 의미합니다. 에이전트가 `Filesystem` 기능의 `apply_patch` 도구로 파일을 편집하는 경우, 패치 경로는 셸 `workdir`가 아니라 샌드박스 작업 공간 루트 기준 상대 경로임을 기억하세요.
+
+`extra_path_grants`는 에이전트가 작업 공간 외부의 구체적인 절대 경로를 필요로 하거나, 매니페스트가 SDK 프로세스 작업 디렉터리 외부의 신뢰된 로컬 소스를 복사해야 할 때만 사용하세요. 예로는 임시 도구 출력을 위한 `/tmp`, 읽기 전용 런타임을 위한 `/opt/toolchain`, 또는 샌드박스에 구체화해야 하는 생성된 스킬 디렉터리가 있습니다. grant는 로컬 소스 구체화, SDK 파일 API, 그리고 백엔드가 파일 시스템 정책을 강제할 수 있는 경우 셸 실행에 적용됩니다:
 
 ```python
 from agents.sandbox import Manifest, SandboxPathGrant
@@ -257,13 +261,15 @@ manifest = Manifest(
 )
 ```
 
-스냅샷과 `persist_workspace()`는 여전히 워크스페이스 루트만 포함합니다. 추가로 권한이 부여된 경로는 런타임 접근이며, 지속되는 워크스페이스 상태가 아닙니다.
+`extra_path_grants`가 포함된 매니페스트는 신뢰할 수 있는 구성으로 취급하세요. 애플리케이션이 해당 호스트 경로를 이미 승인하지 않은 한, 모델 출력이나 기타 신뢰할 수 없는 페이로드에서 grant를 로드하지 마세요.
+
+스냅샷과 `persist_workspace()`는 여전히 작업 공간 루트만 포함합니다. 추가로 grant된 경로는 런타임 접근 권한일 뿐, 지속되는 작업 공간 상태가 아닙니다.
 
 ### 권한
 
-`Permissions`는 manifest 항목의 파일시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책 또는 API 자격 증명에 관한 것이 아닙니다.
+`Permissions`는 매니페스트 항목의 파일 시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책, API 자격 증명에 관한 것이 아닙니다.
 
-기본적으로 manifest 항목은 소유자가 읽기/쓰기/실행 가능하고 그룹과 기타 사용자가 읽기/실행 가능합니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능해야 할 때 이를 재정의하세요.
+기본적으로 매니페스트 항목은 소유자가 읽기/쓰기/실행할 수 있고, 그룹 및 기타 사용자가 읽기/실행할 수 있습니다. 스테이징된 파일이 비공개, 읽기 전용, 또는 실행 가능이어야 할 때 이를 오버라이드하세요:
 
 ```python
 from agents.sandbox import FileMode, Permissions
@@ -279,9 +285,9 @@ private_notes = File(
 )
 ```
 
-`Permissions`는 소유자, 그룹, 기타 사용자 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 만들거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다.
+`Permissions`는 소유자, 그룹, 기타 권한 비트와 해당 항목이 디렉터리인지 여부를 별도로 저장합니다. 직접 만들거나, `Permissions.from_str(...)`로 모드 문자열에서 파싱하거나, `Permissions.from_mode(...)`로 OS 모드에서 파생할 수 있습니다.
 
-사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 할 때 manifest에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대면 샌드박스 도구가 해당 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 manifest에 아직 없는 사용자를 가리키면 runner가 이를 실제 manifest에 추가합니다.
+사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 한다면 매니페스트에 `User`를 추가한 다음, 셸 명령, 파일 읽기, 패치 같은 모델 대상 샌드박스 도구가 그 사용자로 실행되어야 할 때 `SandboxAgent.run_as`를 설정하세요. `run_as`가 매니페스트에 아직 없는 사용자를 가리키면 runner가 유효 매니페스트에 이를 추가합니다.
 
 ```python
 from agents import Runner
@@ -333,13 +339,13 @@ result = await Runner.run(
 )
 ```
 
-파일 수준 공유 규칙도 필요하다면 사용자를 manifest 그룹 및 항목 `group` 메타데이터와 결합하세요. `run_as` 사용자는 누가 샌드박스 네이티브 작업을 실행하는지 제어하고, `Permissions`는 샌드박스가 워크스페이스를 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지 제어합니다.
+파일 수준 공유 규칙도 필요하다면 사용자와 매니페스트 그룹 및 항목 `group` 메타데이터를 조합하세요. `run_as` 사용자는 샌드박스 네이티브 작업을 실행하는 주체를 제어하고, `Permissions`는 샌드박스가 작업 공간을 구체화한 뒤 해당 사용자가 어떤 파일을 읽고, 쓰고, 실행할 수 있는지를 제어합니다.
 
-### SnapshotSpec
+### 스냅샷 사양
 
-`SnapshotSpec`은 새 샌드박스 세션이 저장된 워크스페이스 콘텐츠를 어디에서 복원하고 어디에 다시 저장해야 하는지 알려줍니다. 이는 샌드박스 워크스페이스의 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
+`SnapshotSpec`은 새 샌드박스 세션이 저장된 작업 공간 콘텐츠를 어디에서 복원하고 어디로 다시 지속해야 하는지를 알려줍니다. 이는 샌드박스 작업 공간에 대한 스냅샷 정책이며, `session_state`는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.
 
-로컬의 지속 가능한 스냅샷에는 `LocalSnapshotSpec`을 사용하고, 앱이 원격 스냅샷 클라이언트를 제공할 때는 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 no-op 스냅샷이 폴백으로 사용되며, 고급 호출자는 워크스페이스 스냅샷 지속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다.
+로컬 지속 스냅샷에는 `LocalSnapshotSpec`을 사용하고, 앱이 원격 스냅샷 클라이언트를 제공하는 경우 `RemoteSnapshotSpec`을 사용하세요. 로컬 스냅샷 설정을 사용할 수 없을 때는 무작동 스냅샷이 fallback으로 사용되며, 고급 호출자는 작업 공간 스냅샷 지속성을 원하지 않을 때 이를 명시적으로 사용할 수 있습니다.
 
 ```python
 from pathlib import Path
@@ -356,13 +362,13 @@ run_config = RunConfig(
 )
 ```
 
-runner가 새 샌드박스 세션을 생성하면 샌드박스 클라이언트가 해당 세션의 스냅샷 인스턴스를 만듭니다. 시작 시 스냅샷을 복원할 수 있으면, 실행이 계속되기 전에 샌드박스가 저장된 워크스페이스 콘텐츠를 복원합니다. 정리 시 runner 소유 샌드박스 세션은 워크스페이스를 아카이브하고 스냅샷을 통해 다시 저장합니다.
+runner가 새 샌드박스 세션을 만들면 샌드박스 클라이언트가 해당 세션을 위한 스냅샷 인스턴스를 빌드합니다. 시작 시 스냅샷을 복원할 수 있으면 샌드박스는 실행이 계속되기 전에 저장된 작업 공간 콘텐츠를 복원합니다. 정리 시 runner가 소유한 샌드박스 세션은 작업 공간을 아카이브하고 스냅샷을 통해 다시 지속합니다.
 
-`snapshot`을 생략하면 런타임은 가능할 때 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 설정할 수 없으면 no-op 스냅샷으로 폴백합니다. 마운트된 경로와 임시 경로는 지속 가능한 워크스페이스 콘텐츠로 스냅샷에 복사되지 않습니다.
+`snapshot`을 생략하면 런타임은 가능한 경우 기본 로컬 스냅샷 위치를 사용하려고 시도합니다. 이를 설정할 수 없으면 무작동 스냅샷으로 fallback합니다. 마운트된 경로와 임시 경로는 지속되는 작업 공간 콘텐츠로 스냅샷에 복사되지 않습니다.
 
-### 샌드박스 라이프사이클
+### 샌드박스 수명 주기
 
-두 가지 라이프사이클 모드가 있습니다. **SDK 소유**와 **개발자 소유**입니다.
+수명 주기 모드는 **SDK 소유**와 **개발자 소유** 두 가지입니다.
 
 <div class="sandbox-lifecycle-diagram" markdown="1">
 
@@ -390,7 +396,7 @@ sequenceDiagram
 
 </div>
 
-샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 라이프사이클을 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 runner가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 워크스페이스 상태를 저장하고, 샌드박스를 종료하며, 클라이언트가 runner 소유 리소스를 정리하도록 합니다.
+샌드박스가 한 번의 실행 동안만 살아 있으면 되는 경우 SDK 소유 수명 주기를 사용하세요. `client`, 선택적 `manifest`, 선택적 `snapshot`, 클라이언트 `options`를 전달하면 runner가 샌드박스를 생성하거나 재개하고, 시작하고, 에이전트를 실행하고, 스냅샷 기반 작업 공간 상태를 지속하고, 샌드박스를 종료하고, 클라이언트가 runner 소유 리소스를 정리하도록 합니다.
 
 ```python
 result = await Runner.run(
@@ -402,7 +408,7 @@ result = await Runner.run(
 )
 ```
 
-샌드박스를 미리 생성하거나, 여러 실행에서 하나의 라이브 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때 개발자 소유 라이프사이클을 사용하세요. `session=...`을 전달하면 runner는 해당 라이브 샌드박스를 사용하지만 대신 닫아 주지는 않습니다.
+샌드박스를 미리 생성하거나, 여러 실행에서 하나의 라이브 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스를 대상으로 스트리밍하거나, 정리 시점을 정확히 결정하고 싶을 때는 개발자 소유 수명 주기를 사용하세요. `session=...`을 전달하면 runner는 해당 라이브 샌드박스를 사용하지만 대신 닫지는 않습니다.
 
 ```python
 sandbox = await client.create(manifest=agent.default_manifest)
@@ -413,7 +419,7 @@ async with sandbox:
     await Runner.run(agent, "Write the final report.", run_config=run_config)
 ```
 
-컨텍스트 매니저가 일반적인 형태입니다. 진입 시 샌드박스를 시작하고 종료 시 세션 정리 라이프사이클을 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 라이프사이클 메서드를 직접 호출하세요.
+일반적인 형태는 컨텍스트 매니저입니다. 진입 시 샌드박스를 시작하고, 종료 시 세션 정리 수명 주기를 실행합니다. 앱에서 컨텍스트 매니저를 사용할 수 없다면 수명 주기 메서드를 직접 호출하세요:
 
 ```python
 sandbox = await client.create(
@@ -434,62 +440,64 @@ finally:
     await sandbox.aclose()
 ```
 
-`stop()`은 스냅샷 기반 워크스페이스 콘텐츠만 저장합니다. 샌드박스를 해체하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. 중지 전 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
+`stop()`은 스냅샷 기반 작업 공간 콘텐츠만 지속합니다. 샌드박스를 해체하지는 않습니다. `aclose()`는 전체 세션 정리 경로입니다. 중지 전 훅을 실행하고, `stop()`을 호출하고, 샌드박스 리소스를 종료하고, 세션 범위 종속성을 닫습니다.
 
 ## `SandboxRunConfig` 옵션
 
-[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디에서 오는지, 새 세션을 어떻게 초기화할지 결정하는 실행별 옵션을 담습니다.
+[`SandboxRunConfig`][agents.run_config.SandboxRunConfig]는 샌드박스 세션이 어디에서 오는지, 그리고 새 세션을 어떻게 초기화할지를 결정하는 실행별 옵션을 보관합니다.
 
 ### 샌드박스 소스
 
-이 옵션들은 runner가 샌드박스 세션을 재사용, 재개 또는 생성해야 하는지 결정합니다.
+이 옵션들은 runner가 샌드박스 세션을 재사용, 재개, 또는 생성해야 하는지를 결정합니다:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
 | 옵션 | 사용 시점 | 참고 |
 | --- | --- | --- |
-| `client` | runner가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 라이브 샌드박스 `session`을 제공하지 않는 한 필수입니다. |
-| `session` | 라이브 샌드박스 세션을 이미 직접 생성했을 때 | 호출자가 라이프사이클을 소유합니다. runner는 해당 라이브 샌드박스 세션을 재사용합니다. |
+| `client` | runner가 샌드박스 세션을 생성, 재개, 정리해 주기를 원할 때 | 라이브 샌드박스 `session`을 제공하지 않는 한 필요합니다. |
+| `session` | 이미 직접 라이브 샌드박스 세션을 생성했을 때 | 호출자가 수명 주기를 소유하며, runner는 해당 라이브 샌드박스 세션을 재사용합니다. |
 | `session_state` | 직렬화된 샌드박스 세션 상태는 있지만 라이브 샌드박스 세션 객체는 없을 때 | `client`가 필요합니다. runner는 해당 명시적 상태에서 소유 세션으로 재개합니다. |
 
 </div>
 
-실제로 runner는 다음 순서로 샌드박스 세션을 해석합니다.
+실제로 runner는 다음 순서로 샌드박스 세션을 확인합니다:
 
 1. `run_config.sandbox.session`을 주입하면 해당 라이브 샌드박스 세션이 직접 재사용됩니다.
 2. 그렇지 않고 실행이 `RunState`에서 재개되는 경우, 저장된 샌드박스 세션 상태가 재개됩니다.
-3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면, runner는 해당 명시적으로 직렬화된 샌드박스 세션 상태에서 재개합니다.
+3. 그렇지 않고 `run_config.sandbox.session_state`를 전달하면 runner가 해당 명시적으로 직렬화된 샌드박스 세션 상태에서 재개합니다.
 4. 그렇지 않으면 runner가 새 샌드박스 세션을 생성합니다. 이 새 세션에는 제공된 경우 `run_config.sandbox.manifest`를 사용하고, 그렇지 않으면 `agent.default_manifest`를 사용합니다.
 
 ### 새 세션 입력
 
-이 옵션들은 runner가 새 샌드박스 세션을 생성할 때만 중요합니다.
+이 옵션들은 runner가 새 샌드박스 세션을 생성할 때만 의미가 있습니다:
 
 <div class="sandbox-nowrap-first-column-table" markdown="1">
 
 | 옵션 | 사용 시점 | 참고 |
 | --- | --- | --- |
-| `manifest` | 일회성 새 세션 워크스페이스 재정의를 원할 때 | 생략하면 `agent.default_manifest`로 폴백합니다. |
-| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시작해야 할 때 | 재개와 유사한 흐름 또는 원격 스냅샷 클라이언트에 유용합니다. |
-| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃 및 유사한 클라이언트별 설정에 일반적입니다. |
+| `manifest` | 일회성 새 세션 작업 공간 오버라이드를 원할 때 | 생략하면 `agent.default_manifest`로 fallback합니다. |
+| `snapshot` | 새 샌드박스 세션이 스냅샷에서 시드되어야 할 때 | 재개와 유사한 흐름 또는 원격 스냅샷 클라이언트에 유용합니다. |
+| `options` | 샌드박스 클라이언트에 생성 시점 옵션이 필요할 때 | Docker 이미지, Modal 앱 이름, E2B 템플릿, 타임아웃, 유사한 클라이언트별 설정에 일반적입니다. |
 
 </div>
 
 ### 구체화 제어
 
-`concurrency_limits`는 병렬로 실행할 수 있는 샌드박스 구체화 작업의 양을 제어합니다. 큰 manifest나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
+`concurrency_limits`는 병렬로 실행될 수 있는 샌드박스 구체화 작업량을 제어합니다. 큰 매니페스트나 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요할 때 `SandboxConcurrencyLimits(manifest_entries=..., local_dir_files=...)`를 사용하세요. 특정 제한을 비활성화하려면 해당 값을 `None`으로 설정하세요.
 
-유의할 몇 가지 영향은 다음과 같습니다.
+`archive_limits`는 아카이브 추출에 대한 SDK 측 리소스 검사를 제어합니다. SDK 기본 임계값을 활성화하려면 `archive_limits=SandboxArchiveLimits()`를 설정하거나, 아카이브에 더 엄격한 리소스 제어가 필요할 때 `SandboxArchiveLimits(max_input_bytes=..., max_extracted_bytes=..., max_members=...)` 같은 명시적 값을 전달하세요. SDK 아카이브 리소스 제한이 없는 기본 동작을 유지하려면 `archive_limits=None`으로 두거나, 특정 제한만 비활성화하려면 개별 필드를 `None`으로 설정하세요.
+
+몇 가지 영향을 염두에 둘 필요가 있습니다:
 
 - 새 세션: `manifest=`와 `snapshot=`은 runner가 새 샌드박스 세션을 생성할 때만 적용됩니다.
-- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 다시 연결하는 반면, `snapshot=`은 저장된 워크스페이스 콘텐츠에서 새 샌드박스 세션을 시작합니다.
-- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라집니다. Docker와 많은 호스티드 클라이언트에는 이것이 필요합니다.
-- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 manifest 업데이트가 호환되는 비마운트 항목을 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 바꾸거나, 마운트 항목을 추가 또는 변경할 수는 없습니다.
+- 재개와 스냅샷: `session_state=`는 이전에 직렬화된 샌드박스 상태에 다시 연결하는 반면, `snapshot=`은 저장된 작업 공간 콘텐츠에서 새 샌드박스 세션을 시드합니다.
+- 클라이언트별 옵션: `options=`는 샌드박스 클라이언트에 따라 달라집니다. Docker와 많은 호스티드 클라이언트에는 필요합니다.
+- 주입된 라이브 세션: 실행 중인 샌드박스 `session`을 전달하면 기능 기반 매니페스트 업데이트가 호환되는 비마운트 항목을 추가할 수 있습니다. `manifest.root`, `manifest.environment`, `manifest.users`, `manifest.groups`를 변경하거나, 기존 항목을 제거하거나, 항목 유형을 교체하거나, 마운트 항목을 추가 또는 변경할 수는 없습니다.
 - Runner API: `SandboxAgent` 실행은 여전히 일반 `Runner.run()`, `Runner.run_sync()`, `Runner.run_streamed()` API를 사용합니다.
 
-## 전체 예시: 코딩 작업
+## 전체 예제: 코딩 작업
 
-이 코딩 스타일 예시는 좋은 기본 시작점입니다.
+이 코딩 스타일 예제는 좋은 기본 시작점입니다:
 
 ```python
 import asyncio
@@ -568,19 +576,19 @@ if __name__ == "__main__":
     )
 ```
 
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예시는 작은 셸 기반 저장소를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다. 실제 작업 저장소는 물론 Python, JavaScript 또는 무엇이든 될 수 있습니다.
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참고하세요. 이 예제는 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있도록 작은 셸 기반 리포지토리를 사용합니다. 실제 작업 리포지토리는 물론 Python, JavaScript 또는 그 밖의 어떤 것이어도 됩니다.
 
 ## 일반적인 패턴
 
-위의 전체 예시에서 시작하세요. 많은 경우 동일한 `SandboxAgent`는 그대로 두고 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 워크스페이스 소스만 변경할 수 있습니다.
+위의 전체 예제에서 시작하세요. 많은 경우 동일한 `SandboxAgent`를 그대로 유지하면서 샌드박스 클라이언트, 샌드박스 세션 소스, 또는 작업 공간 소스만 변경할 수 있습니다.
 
 ### 샌드박스 클라이언트 전환
 
-에이전트 정의를 그대로 유지하고 실행 구성만 변경하세요. 컨테이너 격리 또는 이미지 동등성이 필요하면 Docker를 사용하고, 제공자 관리 실행을 원하면 호스티드 제공자를 사용하세요. 예시와 제공자 옵션은 [샌드박스 클라이언트](clients.md)를 참조하세요.
+에이전트 정의는 그대로 두고 실행 구성만 변경하세요. 컨테이너 격리나 이미지 일관성이 필요하면 Docker를 사용하고, 제공자 관리 실행을 원하면 호스티드 제공자를 사용하세요. 예제와 제공자 옵션은 [샌드박스 클라이언트](clients.md)를 참고하세요.
 
-### 워크스페이스 재정의
+### 작업 공간 오버라이드
 
-에이전트 정의를 그대로 유지하고 새 세션 manifest만 교체하세요.
+에이전트 정의는 그대로 두고 새 세션 매니페스트만 교체하세요:
 
 ```python
 from agents.run import RunConfig
@@ -600,11 +608,11 @@ run_config = RunConfig(
 )
 ```
 
-동일한 에이전트 역할을 에이전트를 다시 빌드하지 않고 서로 다른 저장소, 패킷, 작업 번들에 대해 실행해야 할 때 사용하세요. 위의 검증된 코딩 예시는 일회성 재정의 대신 `default_manifest`로 같은 패턴을 보여줍니다.
+동일한 에이전트 역할을 여러 리포지토리, 패킷, 또는 작업 번들에 대해 실행해야 하지만 에이전트를 다시 빌드하고 싶지 않을 때 사용하세요. 위의 검증된 코딩 예제는 일회성 오버라이드 대신 `default_manifest`로 동일한 패턴을 보여줍니다.
 
 ### 샌드박스 세션 주입
 
-명시적 라이프사이클 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 라이브 샌드박스 세션을 주입하세요.
+명시적 수명 주기 제어, 실행 후 검사, 또는 출력 복사가 필요할 때 라이브 샌드박스 세션을 주입하세요:
 
 ```python
 from agents import Runner
@@ -625,11 +633,11 @@ async with sandbox:
     )
 ```
 
-실행 후 워크스페이스를 검사하거나 이미 시작된 샌드박스 세션에서 스트리밍하려는 경우 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참조하세요.
+실행 후 작업 공간을 검사하거나 이미 시작된 샌드박스 세션을 대상으로 스트리밍하고 싶을 때 사용하세요. [examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)와 [examples/sandbox/docker/docker_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docker/docker_runner.py)를 참고하세요.
 
 ### 세션 상태에서 재개
 
-이미 `RunState` 외부에서 샌드박스 상태를 직렬화했다면, runner가 해당 상태에서 다시 연결하도록 하세요.
+`RunState` 외부에서 샌드박스 상태를 이미 직렬화했다면 runner가 그 상태에서 다시 연결하도록 하세요:
 
 ```python
 from agents.run import RunConfig
@@ -646,11 +654,11 @@ run_config = RunConfig(
 )
 ```
 
-샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 여기서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참조하세요.
+샌드박스 상태가 자체 스토리지나 작업 시스템에 있고 `Runner`가 여기서 직접 재개하기를 원할 때 사용하세요. 직렬화/역직렬화 흐름은 [examples/sandbox/extensions/blaxel_runner.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/blaxel_runner.py)를 참고하세요.
 
 ### 스냅샷에서 시작
 
-저장된 파일과 아티팩트에서 새 샌드박스를 시작하세요.
+저장된 파일과 아티팩트에서 새 샌드박스를 시드하세요:
 
 ```python
 from pathlib import Path
@@ -667,11 +675,11 @@ run_config = RunConfig(
 )
 ```
 
-새 실행이 `agent.default_manifest`만이 아니라 저장된 워크스페이스 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를, 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참조하세요.
+새 실행이 `agent.default_manifest`만이 아니라 저장된 작업 공간 콘텐츠에서 시작해야 할 때 사용하세요. 로컬 스냅샷 흐름은 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를, 원격 스냅샷 클라이언트는 [examples/sandbox/sandbox_agent_with_remote_snapshot.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_remote_snapshot.py)를 참고하세요.
 
 ### Git에서 스킬 로드
 
-로컬 스킬 소스를 저장소 기반 소스로 교체하세요.
+로컬 스킬 소스를 리포지토리 기반 소스로 교체하세요:
 
 ```python
 from agents.sandbox.capabilities import Capabilities, Skills
@@ -682,11 +690,11 @@ capabilities = Capabilities.default() + [
 ]
 ```
 
-스킬 번들에 자체 릴리스 주기가 있거나 샌드박스 전반에서 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참조하세요.
+스킬 번들에 자체 릴리스 주기가 있거나 여러 샌드박스에서 공유되어야 할 때 사용하세요. [examples/sandbox/tax_prep.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/tax_prep.py)를 참고하세요.
 
 ### 도구로 노출
 
-도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 부모 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 부모가 사용하는 정확한 워크스페이스를 검사할 수 있습니다.
+도구 에이전트는 자체 샌드박스 경계를 가질 수도 있고 상위 실행의 라이브 샌드박스를 재사용할 수도 있습니다. 재사용은 빠른 읽기 전용 탐색기 에이전트에 유용합니다. 다른 샌드박스를 생성, 하이드레이션, 스냅샷하는 비용 없이 상위 에이전트가 사용 중인 정확한 작업 공간을 검사할 수 있기 때문입니다.
 
 ```python
 from agents import Runner
@@ -768,9 +776,9 @@ async with sandbox:
     )
 ```
 
-여기서 부모 에이전트는 `coordinator`로 실행되고, 탐색 도구 에이전트는 같은 라이브 샌드박스 세션 내부에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색자는 빠르게 검사할 수 있지만 쓰기 비트는 없습니다. `work/` 디렉터리는 코디네이터의 사용자/그룹에만 제공되므로, 부모는 최종 아티팩트를 쓸 수 있고 탐색자는 읽기 전용으로 유지됩니다.
+여기서 상위 에이전트는 `coordinator`로 실행되고, 탐색기 도구 에이전트는 같은 라이브 샌드박스 세션 안에서 `explorer`로 실행됩니다. `pricing_packet/` 항목은 `other` 사용자에게 읽기 가능하므로 탐색기가 빠르게 검사할 수 있지만, 쓰기 비트는 없습니다. `work/` 디렉터리는 coordinator의 사용자/그룹에만 제공되므로, 상위 에이전트는 탐색기가 읽기 전용으로 남아 있는 동안 최종 아티팩트를 작성할 수 있습니다.
 
-도구 에이전트에 실제 격리가 필요하다면 대신 자체 샌드박스 `RunConfig`를 제공하세요.
+도구 에이전트에 실제 격리가 필요하다면 자체 샌드박스 `RunConfig`를 제공하세요:
 
 ```python
 from docker import from_env as docker_from_env
@@ -791,11 +799,11 @@ rollout_agent.as_tool(
 )
 ```
 
-도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요.
+도구 에이전트가 자유롭게 변경하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드/이미지를 사용해야 할 때 별도의 샌드박스를 사용하세요. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
 
 ### 로컬 도구 및 MCP와 결합
 
-동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 워크스페이스를 유지하세요.
+동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 작업 공간을 유지하세요:
 
 ```python
 from agents.sandbox import SandboxAgent
@@ -810,42 +818,42 @@ agent = SandboxAgent(
 )
 ```
 
-워크스페이스 검사가 에이전트 작업의 일부일 뿐일 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참조하세요.
+작업 공간 검사가 에이전트 작업의 일부에 불과할 때 사용하세요. [examples/sandbox/sandbox_agent_with_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agent_with_tools.py)를 참고하세요.
 
 ## 메모리
 
-향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 할 때 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 학습 내용을 샌드박스 워크스페이스 내부 파일로 추출하고, 이후 실행이 해당 파일을 읽을 수 있습니다.
+향후 샌드박스 에이전트 실행이 이전 실행에서 학습해야 한다면 `Memory` 기능을 사용하세요. 메모리는 SDK의 대화형 `Session` 메모리와 별개입니다. 메모리는 학습 내용을 샌드박스 작업 공간 내부의 파일로 증류하고, 이후 실행은 해당 파일을 읽을 수 있습니다.
 
-설정, 읽기/생성 동작, 다중 턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참조하세요.
+설정, 읽기/생성 동작, 멀티턴 대화, 레이아웃 격리는 [에이전트 메모리](memory.md)를 참고하세요.
 
 ## 구성 패턴
 
-단일 에이전트 패턴이 명확해지면, 더 큰 시스템에서 샌드박스 경계를 어디에 둘지가 다음 설계 질문입니다.
+단일 에이전트 패턴이 명확해지면, 다음 설계 질문은 더 큰 시스템에서 샌드박스 경계를 어디에 둘 것인지입니다.
 
-샌드박스 에이전트는 여전히 SDK의 나머지 부분과 조합됩니다.
+샌드박스 에이전트는 여전히 SDK의 나머지 부분과 함께 구성됩니다:
 
-- [핸드오프](../handoffs.md): 문서가 많은 작업을 비샌드박스 접수 에이전트에서 샌드박스 리뷰어로 핸드오프합니다.
+- [핸드오프](../handoffs.md): 문서 중심 작업을 비샌드박스 접수 에이전트에서 샌드박스 검토자로 넘깁니다.
 - [Agents as tools](../tools.md#agents-as-tools): 여러 샌드박스 에이전트를 도구로 노출합니다. 일반적으로 각 `Agent.as_tool(...)` 호출에 `run_config=RunConfig(sandbox=SandboxRunConfig(...))`를 전달하여 각 도구가 자체 샌드박스 경계를 갖도록 합니다.
 - [MCP](../mcp.md) 및 일반 함수 도구: 샌드박스 기능은 `mcp_servers` 및 일반 Python 도구와 공존할 수 있습니다.
 - [에이전트 실행](../running_agents.md): 샌드박스 실행은 여전히 일반 `Runner` API를 사용합니다.
 
-특히 흔한 두 가지 패턴은 다음과 같습니다.
+특히 다음 두 가지 패턴이 일반적입니다:
 
-- 워크스페이스 격리가 필요한 워크플로 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프
-- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출. 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용하여 각 도구가 자체 격리 워크스페이스를 갖도록 함
+- 워크플로 중 작업 공간 격리가 필요한 부분에만 비샌드박스 에이전트가 샌드박스 에이전트로 핸드오프
+- 오케스트레이터가 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 `Agent.as_tool(...)` 호출마다 별도의 샌드박스 `RunConfig`를 사용하여 각 도구가 자체 격리 작업 공간을 갖도록 함
 
-### 턴과 샌드박스 실행
+### 턴 및 샌드박스 실행
 
-핸드오프와 agent-as-tool 호출은 별도로 설명하는 것이 도움이 됩니다.
+핸드오프와 에이전트-도구 호출은 별도로 설명하는 것이 도움이 됩니다.
 
-핸드오프의 경우, 여전히 하나의 최상위 실행과 하나의 최상위 turn 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 리뷰어에게 핸드오프하면, 같은 실행의 다음 모델 호출은 샌드박스 에이전트용으로 준비되며 해당 샌드박스 에이전트가 다음 turn을 수행하는 에이전트가 됩니다. 즉, 핸드오프는 같은 실행의 다음 turn을 어느 에이전트가 소유하는지 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참조하세요.
+핸드오프에서는 여전히 하나의 최상위 실행과 하나의 최상위 턴 루프가 있습니다. 활성 에이전트는 바뀌지만 실행이 중첩되지는 않습니다. 비샌드박스 접수 에이전트가 샌드박스 검토자로 핸드오프하면, 같은 실행의 다음 모델 호출이 샌드박스 에이전트를 위해 준비되고, 해당 샌드박스 에이전트가 다음 턴을 수행하는 주체가 됩니다. 즉, 핸드오프는 같은 실행의 다음 턴을 어느 에이전트가 소유하는지를 바꿉니다. [examples/sandbox/handoffs.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/handoffs.py)를 참고하세요.
 
-`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구 호출을 결정하는 데 하나의 외부 turn을 사용하고, 해당 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행에는 자체 turn 루프, `max_turns`, 승인, 그리고 일반적으로 자체 샌드박스 `RunConfig`가 있습니다. 한 번의 중첩 turn으로 끝날 수도 있고 여러 번 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 turn은 외부 실행의 turn 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참조하세요.
+`Agent.as_tool(...)`에서는 관계가 다릅니다. 외부 오케스트레이터는 도구 호출을 결정하기 위해 하나의 외부 턴을 사용하고, 해당 도구 호출은 샌드박스 에이전트에 대한 중첩 실행을 시작합니다. 중첩 실행에는 자체 턴 루프, `max_turns`, 승인, 그리고 보통 자체 샌드박스 `RunConfig`가 있습니다. 하나의 중첩 턴으로 끝날 수도 있고 여러 턴이 걸릴 수도 있습니다. 외부 오케스트레이터 관점에서는 이 모든 작업이 여전히 하나의 도구 호출 뒤에 있으므로, 중첩 턴은 외부 실행의 턴 카운터를 증가시키지 않습니다. [examples/sandbox/sandbox_agents_as_tools.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/sandbox_agents_as_tools.py)를 참고하세요.
 
-승인 동작도 같은 구분을 따릅니다.
+승인 동작도 같은 분리를 따릅니다:
 
-- 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인은 같은 최상위 실행에 유지됩니다.
-- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 표면화되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다.
+- 핸드오프에서는 샌드박스 에이전트가 이제 해당 실행의 활성 에이전트이므로 승인이 같은 최상위 실행에 유지됩니다.
+- `Agent.as_tool(...)`에서는 샌드박스 도구 에이전트 내부에서 발생한 승인도 외부 실행에 표시되지만, 저장된 중첩 실행 상태에서 오며 외부 실행이 재개될 때 중첩 샌드박스 실행을 재개합니다.
 
 ## 추가 자료
 

docs/ko/sandbox/memory.md

@@ -4,23 +4,23 @@ search:
 ---
 # 에이전트 메모리
 
-메모리를 사용하면 이후의 sandbox-agent 실행이 이전 실행에서 학습할 수 있습니다. 이는 메시지 기록을 저장하는 SDK의 대화형 [`Session`](../sessions/index.md) 메모리와는 별개입니다. 메모리는 이전 실행에서 얻은 교훈을 sandbox 워크스페이스의 파일로 정리합니다.
+메모리는 향후 sandbox-agent 실행이 이전 실행에서 학습할 수 있게 합니다. 이는 메시지 기록을 저장하는 SDK의 대화형 [`Session`](../sessions/index.md) 메모리와는 별개입니다. 메모리는 이전 실행에서 얻은 교훈을 샌드박스 워크스페이스의 파일로 정제합니다.
 
 !!! warning "베타 기능"
 
-    Sandbox 에이전트는 베타입니다. 일반 제공 이전에 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
+    샌드박스 에이전트는 베타 버전입니다. API, 기본값, 지원 기능의 세부 사항은 정식 출시 전에 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다.
 
-메모리는 이후 실행에서 세 가지 종류의 비용을 줄일 수 있습니다.
+메모리는 향후 실행에서 세 가지 비용을 줄일 수 있습니다.
 
-1. 에이전트 비용: 에이전트가 워크플로를 완료하는 데 오랜 시간이 걸렸다면, 다음 실행에서는 탐색이 덜 필요해야 합니다. 이렇게 하면 토큰 사용량과 완료 시간을 줄일 수 있습니다.
-2. 사용자 비용: 사용자가 에이전트를 수정했거나 선호 사항을 표현했다면, 이후 실행은 그 피드백을 기억할 수 있습니다. 이렇게 하면 사람의 개입을 줄일 수 있습니다.
-3. 컨텍스트 비용: 에이전트가 이전에 작업을 완료했고 사용자가 그 작업을 이어서 진행하려는 경우, 사용자는 이전 스레드를 찾거나 모든 컨텍스트를 다시 입력할 필요가 없어야 합니다. 이렇게 하면 작업 설명이 더 짧아집니다.
+1. 에이전트 비용: 에이전트가 워크플로를 완료하는 데 오랜 시간이 걸렸다면, 다음 실행에서는 탐색이 덜 필요해야 합니다. 이를 통해 토큰 사용량과 완료까지 걸리는 시간을 줄일 수 있습니다.
+2. 사용자 비용: 사용자가 에이전트를 수정했거나 선호 사항을 표현했다면, 향후 실행에서 해당 피드백을 기억할 수 있습니다. 이를 통해 사람의 개입을 줄일 수 있습니다.
+3. 컨텍스트 비용: 에이전트가 이전에 작업을 완료했고 사용자가 그 작업을 이어서 진행하려는 경우, 사용자가 이전 스레드를 찾거나 모든 컨텍스트를 다시 입력할 필요가 없어야 합니다. 이를 통해 작업 설명을 더 짧게 만들 수 있습니다.
 
-버그를 수정하고, 메모리를 생성하고, 스냅샷을 재개하고, 후속 검증 실행에서 해당 메모리를 사용하는 완전한 2회 실행 예제는 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를 참조하세요. 별도의 메모리 레이아웃을 사용하는 멀티턴, 멀티 에이전트 예제는 [examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)를 참조하세요.
+버그를 수정하고, 메모리를 생성하고, 스냅샷을 재개한 뒤, 후속 검증 실행에서 해당 메모리를 사용하는 완전한 2회 실행 예제는 [examples/sandbox/memory.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory.py)를 참고하세요. 별도의 메모리 레이아웃을 사용하는 멀티턴, 멀티 에이전트 예제는 [examples/sandbox/memory_multi_agent_multiturn.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/memory_multi_agent_multiturn.py)를 참고하세요.
 
 ## 메모리 활성화
 
-sandbox 에이전트의 capability로 `Memory()`를 추가합니다.
+샌드박스 에이전트에 기능으로 `Memory()`를 추가합니다.
 
 ```python
 from pathlib import Path
@@ -42,28 +42,28 @@ with tempfile.TemporaryDirectory(prefix="sandbox-memory-example-") as snapshot_d
     )
 ```
 
-읽기가 활성화되면 `Memory()`에는 `Shell()`이 필요하며, 이를 통해 주입된 요약만으로 충분하지 않을 때 에이전트가 메모리 파일을 읽고 검색할 수 있습니다. 라이브 메모리 업데이트가 활성화된 경우(기본값)에는 `Filesystem()`도 필요하며, 이를 통해 에이전트가 오래된 메모리를 발견했거나 사용자가 메모리 업데이트를 요청했을 때 `memories/MEMORY.md`를 업데이트할 수 있습니다.
+읽기가 활성화된 경우 `Memory()`에는 `Shell()`이 필요합니다. 이는 주입된 요약만으로 충분하지 않을 때 에이전트가 메모리 파일을 읽고 검색할 수 있게 합니다. 라이브 메모리 업데이트가 활성화된 경우(기본값), `Filesystem()`도 필요합니다. 이는 에이전트가 오래된 메모리를 발견하거나 사용자가 메모리 업데이트를 요청할 때 `memories/MEMORY.md`를 업데이트할 수 있게 합니다.
 
-기본적으로 메모리 아티팩트는 sandbox 워크스페이스의 `memories/` 아래에 저장됩니다. 이후 실행에서 이를 재사용하려면 동일한 라이브 sandbox 세션을 유지하거나, 영속화된 세션 상태 또는 스냅샷에서 재개하여 구성된 전체 memories 디렉터리를 보존하고 재사용해야 합니다. 새 빈 sandbox는 빈 메모리로 시작합니다.
+기본적으로 메모리 아티팩트는 샌드박스 워크스페이스의 `memories/` 아래에 저장됩니다. 나중 실행에서 이를 재사용하려면 동일한 라이브 샌드박스 세션을 유지하거나, 영구 저장된 세션 상태 또는 스냅샷에서 재개하여 구성된 memories 디렉터리 전체를 보존하고 재사용하세요. 새 빈 샌드박스는 빈 메모리로 시작합니다.
 
-`Memory()`는 메모리 읽기와 메모리 생성을 모두 활성화합니다. 메모리를 읽되 새 메모리는 생성하지 않아야 하는 에이전트에는 `Memory(generate=None)`를 사용하세요. 예를 들어, 내부 에이전트, 서브에이전트, 검사기, 또는 실행이 큰 신호를 추가하지 않는 일회성 도구 에이전트가 이에 해당합니다. 실행이 나중을 위해 메모리를 생성해야 하지만, 사용자가 기존 메모리의 영향을 받기를 원하지 않는 경우에는 `Memory(read=None)`를 사용하세요.
+`Memory()`는 메모리 읽기와 생성을 모두 활성화합니다. 메모리를 읽어야 하지만 새 메모리를 생성해서는 안 되는 에이전트에는 `Memory(generate=None)`을 사용하세요. 예를 들어 내부 에이전트, 서브에이전트, 검사기, 또는 실행이 많은 신호를 추가하지 않는 일회성 도구 에이전트가 이에 해당합니다. 실행이 나중을 위한 메모리는 생성해야 하지만, 기존 메모리의 영향을 받는 것을 사용자가 원하지 않는 경우에는 `Memory(read=None)`을 사용하세요.
 
 ## 메모리 읽기
 
-메모리 읽기는 점진적 공개(progressive disclosure)를 사용합니다. 실행 시작 시 SDK는 일반적으로 유용한 팁, 사용자 선호 사항, 사용 가능한 메모리를 담은 작은 요약인 (`memory_summary.md`)을 에이전트의 개발자 프롬프트에 주입합니다. 이를 통해 에이전트는 이전 작업이 관련 있을 수 있는지 판단할 만큼 충분한 컨텍스트를 얻습니다.
+메모리 읽기는 점진적 공개 방식을 사용합니다. 실행 시작 시 SDK는 일반적으로 유용한 팁, 사용자 선호 사항, 사용 가능한 메모리에 대한 작은 요약(`memory_summary.md`)을 에이전트의 개발자 프롬프트에 주입합니다. 이를 통해 에이전트는 이전 작업이 관련될 수 있는지 판단하기에 충분한 컨텍스트를 얻습니다.
 
-이전 작업이 관련 있어 보이면, 에이전트는 현재 작업의 키워드로 구성된 메모리 인덱스(`memories_dir` 아래의 `MEMORY.md`)를 검색합니다. 더 자세한 정보가 필요한 경우에만 구성된 `rollout_summaries/` 디렉터리 아래의 해당 이전 rollout 요약을 엽니다.
+이전 작업이 관련 있어 보이면, 에이전트는 현재 작업의 키워드로 구성된 메모리 인덱스(`memories_dir` 아래의 `MEMORY.md`)를 검색합니다. 작업에 더 자세한 정보가 필요할 때만 구성된 `rollout_summaries/` 디렉터리 아래의 해당 이전 롤아웃 요약을 엽니다.
 
-메모리는 오래될 수 있습니다. 에이전트는 메모리를 오직 참고용으로만 취급하고 현재 환경을 신뢰하도록 지시받습니다. 기본적으로 메모리 읽기에는 `live_update`가 활성화되어 있으므로, 에이전트가 오래된 메모리를 발견하면 같은 실행에서 구성된 `MEMORY.md`를 업데이트할 수 있습니다. 예를 들어 실행이 지연 시간에 민감한 경우처럼, 에이전트가 메모리를 읽되 실행 중 수정해서는 안 되는 경우에는 라이브 업데이트를 비활성화하세요.
+메모리는 오래될 수 있습니다. 에이전트는 메모리를 지침으로만 취급하고 현재 환경을 신뢰하도록 지시받습니다. 기본적으로 메모리 읽기에는 `live_update`가 활성화되어 있으므로, 에이전트가 오래된 메모리를 발견하면 동일한 실행에서 구성된 `MEMORY.md`를 업데이트할 수 있습니다. 에이전트가 메모리를 읽어야 하지만 실행 중에 수정해서는 안 되는 경우, 예를 들어 실행이 지연 시간에 민감한 경우에는 라이브 업데이트를 비활성화하세요.
 
 ## 메모리 생성
 
-실행이 끝나면 sandbox 런타임은 해당 실행 세그먼트를 대화 파일에 추가합니다. 누적된 대화 파일은 sandbox 세션이 닫힐 때 처리됩니다.
+실행이 끝나면 샌드박스 런타임은 해당 실행 세그먼트를 대화 파일에 추가합니다. 누적된 대화 파일은 샌드박스 세션이 닫힐 때 처리됩니다.
 
 메모리 생성에는 두 단계가 있습니다.
 
-1. 1단계: 대화 추출. 메모리 생성 모델이 하나의 누적된 대화 파일을 처리하고 대화 요약을 생성합니다. 시스템, 개발자, 추론 콘텐츠는 제외됩니다. 대화가 너무 길면 컨텍스트 윈도에 맞도록 잘리며, 시작과 끝은 보존됩니다. 또한 2단계에서 통합할 수 있도록 대화의 간결한 메모인 원문 메모리 추출도 생성합니다.
-2. 2단계: 레이아웃 통합. 통합 에이전트가 하나의 메모리 레이아웃에 대한 원문 메모리를 읽고, 더 많은 근거가 필요할 때 대화 요약을 열어 패턴을 `MEMORY.md`와 `memory_summary.md`로 추출합니다.
+1. 1단계: 대화 추출. 메모리 생성 모델이 누적된 대화 파일 하나를 처리하고 대화 요약을 생성합니다. 시스템, 개발자, 추론 내용은 생략됩니다. 대화가 너무 길면 컨텍스트 창에 맞도록 잘리며, 시작과 끝은 보존됩니다. 또한 원문 메모리 추출도 생성합니다. 이는 2단계에서 통합할 수 있는 대화의 간결한 노트입니다.
+2. 2단계: 레이아웃 통합. 통합 에이전트가 하나의 메모리 레이아웃에 대한 원문 메모리를 읽고, 더 많은 근거가 필요할 때 대화 요약을 연 다음, 패턴을 `MEMORY.md`와 `memory_summary.md`로 추출합니다.
 
 기본 워크스페이스 레이아웃은 다음과 같습니다.
 
@@ -97,13 +97,13 @@ memory = Memory(
 )
 ```
 
-`extra_prompt`를 사용해 GTM 에이전트의 고객 및 회사 세부 정보처럼, 사용 사례에서 어떤 신호가 가장 중요한지 메모리 생성기에 알려주세요.
+`extra_prompt`를 사용하여 메모리 생성기에 사용 사례에서 가장 중요한 신호를 알려줄 수 있습니다. 예를 들어 GTM 에이전트의 경우 고객 및 회사 세부 정보가 해당됩니다.
 
-최근 원문 메모리가 `max_raw_memories_for_consolidation`(기본값 256)을 초과하면, 2단계는 가장 최신 대화의 메모리만 유지하고 오래된 것은 제거합니다. 최신성은 대화가 마지막으로 업데이트된 시간을 기준으로 합니다. 이 망각 메커니즘은 메모리가 가장 새로운 환경을 반영하도록 돕습니다.
+최근 원문 메모리가 `max_raw_memories_for_consolidation`(기본값 256)을 초과하면, 2단계는 가장 최신 대화의 메모리만 유지하고 더 오래된 메모리는 제거합니다. 최신성은 대화가 마지막으로 업데이트된 시간을 기준으로 합니다. 이 망각 메커니즘은 메모리가 최신 환경을 반영하는 데 도움이 됩니다.
 
 ## 멀티턴 대화
 
-멀티턴 sandbox 채팅의 경우, 동일한 라이브 sandbox 세션과 함께 일반 SDK `Session`을 사용하세요.
+멀티턴 샌드박스 채팅에는 일반 SDK `Session`을 동일한 라이브 샌드박스 세션과 함께 사용하세요.
 
 ```python
 from agents import Runner, SQLiteSession
@@ -132,20 +132,20 @@ async with sandbox:
     )
 ```
 
-두 실행은 동일한 SDK 대화 세션(`session=conversation_session`)을 전달하므로 하나의 메모리 대화 파일에 추가되며, 따라서 같은 `session.session_id`를 공유합니다. 이는 라이브 워크스페이스를 식별하지만 메모리 대화 ID로는 사용되지 않는 sandbox(`sandbox`)와는 다릅니다. 1단계는 sandbox 세션이 닫힐 때 누적된 대화를 확인하므로, 분리된 두 턴이 아니라 전체 교환에서 메모리를 추출할 수 있습니다.
+두 실행은 동일한 SDK 대화 세션(`session=conversation_session`)을 전달하므로 같은 `session.session_id`를 공유하고, 따라서 하나의 메모리 대화 파일에 추가됩니다. 이는 라이브 워크스페이스를 식별하며 메모리 대화 ID로 사용되지 않는 샌드박스(`sandbox`)와 다릅니다. 1단계는 샌드박스 세션이 닫힐 때 누적된 대화를 보므로, 서로 분리된 두 턴이 아니라 전체 교환에서 메모리를 추출할 수 있습니다.
 
-여러 `Runner.run(...)` 호출이 하나의 메모리 대화가 되도록 하려면, 해당 호출들에 걸쳐 안정적인 식별자를 전달하세요. 메모리가 실행을 대화와 연결할 때는 다음 순서로 이를 확인합니다.
+여러 `Runner.run(...)` 호출이 하나의 메모리 대화가 되도록 하려면 해당 호출들에 안정적인 식별자를 전달하세요. 메모리가 실행을 대화와 연결할 때는 다음 순서로 확인합니다.
 
-1. `Runner.run(...)`에 전달한 경우의 `conversation_id`
-2. `SQLiteSession`과 같은 SDK `Session`을 전달한 경우의 `session.session_id`
-3. 위 둘 다 없는 경우의 `RunConfig.group_id`
-4. 안정적인 식별자가 없는 경우의 실행별 생성 ID
+1. `Runner.run(...)`에 전달한 경우 `conversation_id`
+2. `SQLiteSession` 같은 SDK `Session`을 전달한 경우 `session.session_id`
+3. 위 둘 중 어느 것도 없을 경우 `RunConfig.group_id`
+4. 안정적인 식별자가 없을 경우 생성된 실행별 ID
 
-## 여러 에이전트의 메모리 분리를 위한 다른 레이아웃 사용
+## 서로 다른 에이전트의 메모리를 격리하기 위한 서로 다른 레이아웃 사용
 
-메모리 분리는 에이전트 이름이 아니라 `MemoryLayoutConfig`를 기준으로 합니다. 동일한 레이아웃과 동일한 메모리 대화 ID를 가진 에이전트는 하나의 메모리 대화와 하나의 통합 메모리를 공유합니다. 레이아웃이 다른 에이전트는 같은 sandbox 워크스페이스를 공유하더라도 별도의 rollout 파일, 원문 메모리, `MEMORY.md`, `memory_summary.md`를 유지합니다.
+메모리 격리는 에이전트 이름이 아니라 `MemoryLayoutConfig`를 기준으로 합니다. 동일한 레이아웃과 동일한 메모리 대화 ID를 가진 에이전트는 하나의 메모리 대화와 하나의 통합된 메모리를 공유합니다. 서로 다른 레이아웃을 가진 에이전트는 동일한 샌드박스 워크스페이스를 공유하더라도 별도의 롤아웃 파일, 원문 메모리, `MEMORY.md`, `memory_summary.md`를 유지합니다.
 
-여러 에이전트가 하나의 sandbox를 공유하지만 메모리를 공유해서는 안 되는 경우에는 별도의 레이아웃을 사용하세요.
+여러 에이전트가 하나의 샌드박스를 공유하지만 메모리는 공유해서는 안 되는 경우 별도의 레이아웃을 사용하세요.
 
 ```python
 from agents import SQLiteSession
@@ -186,4 +186,4 @@ gtm_session = SQLiteSession("gtm-q2-pipeline-review")
 engineering_session = SQLiteSession("eng-invoice-test-fix")
 ```
 
-이렇게 하면 GTM 분석이 엔지니어링 버그 수정 메모리에 통합되는 것을 방지하고, 그 반대도 방지할 수 있습니다.
+이렇게 하면 GTM 분석이 엔지니어링 버그 수정 메모리로 통합되거나 그 반대가 되는 일을 방지할 수 있습니다.

docs/ko/sandbox_agents.md

@@ -6,16 +6,16 @@ search:
 
 !!! warning "베타 기능"
 
-    샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 제공 전에 변경될 수 있으며, 시간이 지남에 따라 더 고급 기능이 추가될 수 있습니다.
+    샌드박스 에이전트는 베타입니다. API, 기본값, 지원 기능의 세부 사항은 일반 공개 전까지 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 예정입니다.
 
-최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. Agents SDK의 **샌드박스 에이전트**는 모델에 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 저장된 샌드박스 상태에서 작업 재개를 수행할 수 있는 지속적인 워크스페이스를 제공합니다.
+최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 잘 작동합니다. Agents SDK의 **샌드박스 에이전트**는 모델에 영구 작업 공간을 제공하여 대규모 문서 집합을 검색하고, 파일을 편집하고, 명령을 실행하고, 아티팩트를 생성하고, 저장된 샌드박스 상태에서 작업을 다시 이어갈 수 있게 합니다.
 
-SDK는 파일 스테이징, 파일 시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 제공자별 글루 코드를 직접 연결하지 않아도 이러한 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지한 다음, 워크스페이스용 `Manifest`, 샌드박스 네이티브 도구용 기능, 작업이 실행될 위치를 위한 `SandboxRunConfig`를 추가하면 됩니다.
+SDK는 파일 스테이징, 파일 시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 공급자별 연결 코드를 직접 엮지 않아도 이러한 실행 하네스를 제공합니다. 일반적인 `Agent` 및 `Runner` 흐름을 유지한 다음, 작업 공간을 위한 `Manifest`, 샌드박스 네이티브 도구를 위한 기능, 작업이 실행될 위치를 위한 `SandboxRunConfig`를 추가하면 됩니다.
 
 ## 사전 요구 사항
 
 - Python 3.10 이상
-- OpenAI Agents SDK에 대한 기본 이해
+- OpenAI Agents SDK에 대한 기본적인 이해
 - 샌드박스 클라이언트. 로컬 개발의 경우 `UnixLocalSandboxClient`로 시작하세요.
 
 ## 설치
@@ -34,7 +34,7 @@ pip install "openai-agents[docker]"
 
 ## 로컬 샌드박스 에이전트 생성
 
-이 예제는 `repo/` 아래에 로컬 저장소를 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위한 Unix 로컬 샌드박스 세션을 만들도록 합니다.
+이 예제는 `repo/` 아래에 로컬 리포지토리를 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 실행을 위한 Unix-local 샌드박스 세션을 만들 수 있게 합니다.
 
 ```python
 import asyncio
@@ -94,24 +94,24 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 저장소를 사용하므로 Unix 로컬 실행 전반에서 결정적으로 검증할 수 있습니다.
+[examples/sandbox/docs/coding_task.py](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/docs/coding_task.py)를 참조하세요. 이 예제는 작은 셸 기반 리포지토리를 사용하므로 Unix-local 실행 전반에서 결정적으로 검증할 수 있습니다.
 
 ## 주요 선택 사항
 
-기본 실행이 작동한 뒤 대부분의 사람이 다음으로 고려하는 선택 사항은 다음과 같습니다.
+기본 실행이 작동한 후 대부분의 사용자가 다음으로 고려하는 선택지는 다음과 같습니다.
 
-- `default_manifest`: 새 샌드박스 세션을 위한 파일, 저장소, 디렉터리, 마운트
+- `default_manifest`: 새 샌드박스 세션을 위한 파일, 리포지토리, 디렉터리, 마운트
 - `instructions`: 프롬프트 전반에 적용되어야 하는 짧은 워크플로 규칙
-- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 이스케이프 해치
+- `base_instructions`: SDK 샌드박스 프롬프트를 대체하기 위한 고급 탈출구
 - `capabilities`: 파일 시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축과 같은 샌드박스 네이티브 도구
-- `run_as`: 모델이 사용하는 도구의 샌드박스 사용자 ID
+- `run_as`: 모델 대상 도구를 위한 샌드박스 사용자 ID
 - `SandboxRunConfig.client`: 샌드박스 백엔드
-- `SandboxRunConfig.session`, `session_state` 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결하는 방식
+- `SandboxRunConfig.session`, `session_state` 또는 `snapshot`: 이후 실행이 이전 작업에 다시 연결되는 방식
 
 ## 다음 단계
 
-- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 구성 패턴을 이해합니다.
-- [샌드박스 클라이언트](sandbox/clients.md): Unix 로컬, Docker, 호스티드 제공자, 마운트 전략을 선택합니다.
-- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행에서 얻은 교훈을 보존하고 재사용합니다.
+- [개념](sandbox/guide.md): 매니페스트, 기능, 권한, 스냅샷, 실행 구성, 구성 패턴 이해
+- [샌드박스 클라이언트](sandbox/clients.md): Unix-local, Docker, 호스티드 공급자, 마운트 전략 선택
+- [에이전트 메모리](sandbox/memory.md): 이전 샌드박스 실행에서 얻은 교훈 보존 및 재사용
 
-셸 접근이 가끔 사용하는 도구 중 하나에 불과하다면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 워크스페이스 격리, 샌드박스 클라이언트 선택, 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.
+셸 접근이 가끔 사용하는 도구 중 하나일 뿐이라면 [도구 가이드](tools.md)의 호스티드 셸부터 시작하세요. 작업 공간 격리, 샌드박스 클라이언트 선택 또는 샌드박스 세션 재개 동작이 설계의 일부일 때 샌드박스 에이전트를 선택하세요.

docs/ko/sessions/advanced_sqlite_session.md

@@ -4,14 +4,14 @@ search:
 ---
 # 고급 SQLite 세션
 
-`AdvancedSQLiteSession`은 기본 `SQLiteSession`의 향상된 버전으로, 대화 브랜칭, 상세 사용량 분석, 구조화된 대화 쿼리를 포함한 고급 대화 관리 기능을 제공합니다
+`AdvancedSQLiteSession`은 기본 `SQLiteSession`의 향상된 버전으로, 대화 분기, 상세 사용량 분석, 구조화된 대화 쿼리 등 고급 대화 관리 기능을 제공합니다.
 
 ## 기능
 
-- **대화 브랜칭**: 모든 사용자 메시지에서 대체 대화 경로 생성
+- **대화 분기**: 모든 사용자 메시지에서 대체 대화 경로를 생성
 - **사용량 추적**: 전체 JSON 세부 내역과 함께 턴별 상세 토큰 사용량 분석
-- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등 조회
-- **브랜치 관리**: 독립적인 브랜치 전환 및 관리
+- **구조화된 쿼리**: 턴별 대화, 도구 사용 통계 등을 조회
+- **분기 관리**: 독립적인 분기 전환 및 관리
 - **메시지 구조 메타데이터**: 메시지 유형, 도구 사용, 대화 흐름 추적
 
 ## 빠른 시작
@@ -85,13 +85,13 @@ session = AdvancedSQLiteSession(
 ### 매개변수
 
 - `session_id` (str): 대화 세션의 고유 식별자
-- `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 기본값은 인메모리 저장을 위한 `:memory:`
+- `db_path` (str | Path): SQLite 데이터베이스 파일 경로. 인메모리 저장소의 경우 기본값은 `:memory:`
 - `create_tables` (bool): 고급 테이블을 자동으로 생성할지 여부. 기본값은 `False`
 - `logger` (logging.Logger | None): 세션용 사용자 지정 로거. 기본값은 모듈 로거
 
 ## 사용량 추적
 
-AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드가 호출되는지에 전적으로 의존합니다.**
+AdvancedSQLiteSession은 대화 턴별 토큰 사용량 데이터를 저장하여 상세한 사용량 분석을 제공합니다. **이는 각 에이전트 실행 후 `store_run_usage` 메서드가 호출되는지에 전적으로 의존합니다.**
 
 ### 사용량 데이터 저장
 
@@ -135,11 +135,11 @@ for turn_data in turn_usage:
 turn_2_usage = await session.get_turn_usage(user_turn_number=2)
 ```
 
-## 대화 브랜칭
+## 대화 분기
 
-AdvancedSQLiteSession의 핵심 기능 중 하나는 모든 사용자 메시지에서 대화 브랜치를 생성할 수 있다는 점이며, 이를 통해 대체 대화 경로를 탐색할 수 있습니다.
+AdvancedSQLiteSession의 핵심 기능 중 하나는 모든 사용자 메시지에서 대화 분기를 생성하여 대체 대화 경로를 탐색할 수 있는 기능입니다.
 
-### 브랜치 생성
+### 분기 생성
 
 ```python
 # Get available turns for branching
@@ -165,7 +165,7 @@ branch_id = await session.create_branch_from_content(
 )
 ```
 
-### 브랜치 관리
+### 분기 관리
 
 ```python
 # List all branches
@@ -182,7 +182,7 @@ await session.switch_to_branch(branch_id)
 await session.delete_branch(branch_id, force=True)  # force=True allows deleting current branch
 ```
 
-### 브랜치 워크플로 예제
+### 분기 워크플로 예제
 
 ```python
 # Original conversation
@@ -245,17 +245,17 @@ for turn in matching_turns:
 
 ### 메시지 구조
 
-세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다:
+세션은 다음을 포함한 메시지 구조를 자동으로 추적합니다.
 
-- 메시지 유형(user, assistant, tool_call 등)
+- 메시지 유형(사용자, 어시스턴트, tool_call 등)
 - 도구 호출의 도구 이름
 - 턴 번호 및 시퀀스 번호
-- 브랜치 연결
+- 분기 연결
 - 타임스탬프
 
 ## 데이터베이스 스키마
 
-AdvancedSQLiteSession은 기본 SQLite 스키마를 두 개의 추가 테이블로 확장합니다:
+AdvancedSQLiteSession은 두 개의 추가 테이블로 기본 SQLite 스키마를 확장합니다.
 
 ### message_structure 테이블
 
@@ -298,7 +298,7 @@ CREATE TABLE turn_usage (
 
 ## 전체 예제
 
-모든 기능을 종합적으로 시연하는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요
+모든 기능을 종합적으로 보여 주는 [전체 예제](https://github.com/openai/openai-agents-python/tree/main/examples/memory/advanced_sqlite_session_example.py)를 확인하세요.
 
 
 ## API 참조

docs/ko/sessions/encrypted_session.md

@@ -4,18 +4,18 @@ search:
 ---
 # 암호화된 세션
 
-`EncryptedSession`은 모든 세션 구현에 대해 투명한 암호화를 제공하며, 오래된 항목의 자동 만료로 대화 데이터를 안전하게 보호합니다.
+`EncryptedSession`은 모든 세션 구현에 투명한 암호화를 제공하여, 오래된 항목의 자동 만료와 함께 대화 데이터를 보호합니다.
 
 ## 기능
 
-- **투명한 암호화**: Fernet 암호화로 모든 세션을 래핑합니다
-- **세션별 키**: 세션마다 고유한 암호화를 위해 HKDF 키 파생을 사용합니다
-- **자동 만료**: TTL이 만료되면 오래된 항목을 자동으로 건너뜁니다
-- **즉시 교체 가능**: 기존의 모든 세션 구현과 함께 작동합니다
+- **투명한 암호화**: 모든 세션을 Fernet 암호화로 래핑합니다
+- **세션별 키**: HKDF 키 파생을 사용하여 세션마다 고유한 암호화를 적용합니다
+- **자동 만료**: TTL이 만료되면 오래된 항목을 조용히 건너뜁니다
+- **드롭인 대체**: 기존의 모든 세션 구현과 함께 작동합니다
 
 ## 설치
 
-암호화된 세션을 사용하려면 `encrypt` extra가 필요합니다:
+암호화된 세션에는 `encrypt` extra가 필요합니다:
 
 ```bash
 pip install openai-agents[encrypt]
@@ -57,7 +57,7 @@ if __name__ == "__main__":
 
 ### 암호화 키
 
-암호화 키는 Fernet 키 또는 임의의 문자열이 될 수 있습니다:
+암호화 키는 Fernet 키이거나 임의의 문자열일 수 있습니다:
 
 ```python
 from agents.extensions.memory import EncryptedSession
@@ -79,9 +79,9 @@ session = EncryptedSession(
 )
 ```
 
-### TTL (유효 기간)
+### TTL(time to live)
 
-암호화된 항목이 유효하게 유지되는 시간을 설정합니다:
+암호화된 항목이 유효한 기간을 설정합니다:
 
 ```python
 # Items expire after 1 hour
@@ -101,7 +101,7 @@ session = EncryptedSession(
 )
 ```
 
-## 다양한 세션 유형과의 사용
+## 다양한 세션 유형과 함께 사용
 
 ### SQLite 세션과 함께 사용
 
@@ -140,16 +140,16 @@ session = EncryptedSession(
 
 !!! warning "고급 세션 기능"
 
-    `AdvancedSQLiteSession` 같은 고급 세션 구현과 `EncryptedSession`을 함께 사용할 때는 다음을 유의하세요:
+    `EncryptedSession`을 `AdvancedSQLiteSession` 같은 고급 세션 구현과 함께 사용할 때는 다음 사항에 유의하세요:
 
-    - 메시지 콘텐츠가 암호화되므로 `find_turns_by_content()` 같은 메서드는 효과적으로 작동하지 않습니다
-    - 콘텐츠 기반 검색은 암호화된 데이터에서 수행되므로 효과가 제한됩니다
+    - `find_turns_by_content()` 같은 메서드는 메시지 콘텐츠가 암호화되어 있으므로 효과적으로 작동하지 않습니다
+    - 콘텐츠 기반 검색은 암호화된 데이터에 대해 동작하므로 효과가 제한됩니다
 
 
 
 ## 키 파생
 
-EncryptedSession은 세션별 고유 암호화 키를 파생하기 위해 HKDF(HMAC 기반 키 파생 함수)를 사용합니다:
+EncryptedSession은 HKDF(HMAC-based Key Derivation Function)를 사용하여 세션별로 고유한 암호화 키를 파생합니다:
 
 - **마스터 키**: 제공한 암호화 키
 - **세션 솔트**: 세션 ID
@@ -157,9 +157,9 @@ EncryptedSession은 세션별 고유 암호화 키를 파생하기 위해 HKDF(H
 - **출력**: 32바이트 Fernet 키
 
 이를 통해 다음이 보장됩니다:
-- 각 세션은 고유한 암호화 키를 가집니다
+- 각 세션에는 고유한 암호화 키가 있습니다
 - 마스터 키 없이는 키를 파생할 수 없습니다
-- 세션 데이터는 서로 다른 세션 간에 복호화할 수 없습니다
+- 서로 다른 세션 간에는 세션 데이터를 복호화할 수 없습니다
 
 ## 자동 만료
 
@@ -175,5 +175,5 @@ result = await Runner.run(agent, "Continue conversation", session=session)
 
 ## API 참조
 
-- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 주요 클래스
+- [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 기본 클래스
 - [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜

docs/ko/sessions/index.md

@@ -4,11 +4,11 @@ search:
 ---
 # 세션
 
-Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하는 내장 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요를 없애줍니다.
+Agents SDK는 여러 에이전트 실행 간 대화 기록을 자동으로 유지하는 기본 제공 세션 메모리를 제공하여, 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요를 없애줍니다.
 
-세션은 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 특히 에이전트가 이전 상호작용을 기억하길 원하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 유용합니다.
+세션은 특정 세션의 대화 기록을 저장하므로, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있습니다. 이는 에이전트가 이전 상호작용을 기억해야 하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
 
-SDK가 클라이언트 측 메모리를 관리하도록 하려면 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id`, `auto_previous_response_id`와 함께 사용할 수 없습니다. 대신 OpenAI 서버 관리형 이어가기를 원한다면, 세션을 그 위에 겹쳐 쓰지 말고 이러한 메커니즘 중 하나를 선택하세요.
+SDK가 클라이언트 측 메모리를 관리해 주기를 원할 때 세션을 사용하세요. 세션은 동일한 실행에서 `conversation_id`, `previous_response_id` 또는 `auto_previous_response_id` 와 함께 사용할 수 없습니다. OpenAI 서버 관리형 이어가기를 원한다면 세션을 그 위에 겹쳐 사용하지 말고 해당 메커니즘 중 하나를 선택하세요.
 
 ## 빠른 시작
 
@@ -51,7 +51,7 @@ print(result.final_output)  # "Approximately 39 million"
 
 ## 동일한 세션으로 인터럽트된 실행 재개
 
-승인을 위해 실행이 일시 중지되면, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 동일한 백킹 스토어를 가리키는 다른 세션 인스턴스)로 재개하세요.
+승인을 위해 실행이 일시 중지되는 경우, 재개된 턴이 동일한 저장된 대화 기록을 이어가도록 같은 세션 인스턴스(또는 같은 기반 저장소를 가리키는 다른 세션 인스턴스)로 재개하세요.
 
 ```python
 result = await Runner.run(agent, "Delete temporary files that are no longer needed.", session=session)
@@ -65,29 +65,29 @@ if result.interruptions:
 
 ## 핵심 세션 동작
 
-세션 메모리가 활성화되면:
+세션 메모리가 활성화되면 다음과 같이 동작합니다.
 
-1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 항목 앞에 추가합니다.
+1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 조회하여 입력 항목 앞에 추가합니다.
 2. **각 실행 후**: 실행 중 생성된 모든 새 항목(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 세션에 자동으로 저장됩니다.
 3. **컨텍스트 보존**: 동일한 세션으로 이어지는 각 실행에는 전체 대화 기록이 포함되어 에이전트가 컨텍스트를 유지할 수 있습니다.
 
-이를 통해 `.to_input_list()`를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다.
+이를 통해 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다.
 
 ## 기록과 새 입력 병합 제어
 
-세션을 전달하면, 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다.
+세션을 전달하면 러너는 일반적으로 모델 입력을 다음과 같이 준비합니다.
 
-1. 세션 기록(`session.get_items(...)`에서 가져옴)
+1. 세션 기록(`session.get_items(...)` 에서 조회)
 2. 새 턴 입력
 
-모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 콜백은 두 개의 목록을 받습니다.
+모델 호출 전에 이 병합 단계를 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 을 사용하세요. 콜백은 두 개의 목록을 받습니다.
 
--   `history`: 가져온 세션 기록(이미 입력 항목 형식으로 정규화됨)
+-   `history`: 조회된 세션 기록(이미 입력 항목 형식으로 정규화됨)
 -   `new_input`: 현재 턴의 새 입력 항목
 
 모델에 전송할 최종 입력 항목 목록을 반환하세요.
 
-콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 저장합니다. 따라서 오래된 기록을 재정렬하거나 필터링해도 오래된 세션 항목이 새 입력으로 다시 저장되지는 않습니다.
+콜백은 두 목록의 복사본을 받으므로 안전하게 변경할 수 있습니다. 반환된 목록은 해당 턴의 모델 입력을 제어하지만, SDK는 여전히 새 턴에 속한 항목만 지속 저장합니다. 따라서 이전 기록을 재정렬하거나 필터링해도 이전 세션 항목이 새 입력으로 다시 저장되지는 않습니다.
 
 ```python
 from agents import Agent, RunConfig, Runner, SQLiteSession
@@ -109,16 +109,16 @@ result = await Runner.run(
 )
 ```
 
-세션이 항목을 저장하는 방식을 바꾸지 않으면서 기록을 사용자 지정 가지치기, 재정렬 또는 선택적으로 포함해야 할 때 사용하세요. 모델 호출 직전에 한 번 더 최종 처리가 필요하다면 [running agents guide](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]를 사용하세요.
+세션이 항목을 저장하는 방식은 바꾸지 않으면서 기록에 대한 사용자 지정 가지치기, 재정렬 또는 선택적 포함이 필요할 때 사용하세요. 모델 호출 직전에 더 늦은 최종 처리 단계가 필요하다면 [에이전트 실행 가이드](../running_agents.md)의 [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter] 를 사용하세요.
 
-## 가져오는 기록 제한
+## 조회 기록 제한
 
-각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings]를 사용하세요.
+각 실행 전에 가져올 기록의 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요.
 
--   `SessionSettings(limit=None)`(기본값): 사용 가능한 모든 세션 항목 가져오기
--   `SessionSettings(limit=N)`: 가장 최근 `N`개 항목만 가져오기
+-   `SessionSettings(limit=None)` (기본값): 사용 가능한 모든 세션 항목 조회
+-   `SessionSettings(limit=N)`: 가장 최근 `N` 개 항목만 조회
 
-[`RunConfig.session_settings`][agents.run.RunConfig.session_settings]를 통해 실행별로 이를 적용할 수 있습니다.
+[`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 를 통해 실행별로 이를 적용할 수 있습니다.
 
 ```python
 from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
@@ -134,13 +134,13 @@ result = await Runner.run(
 )
 ```
 
-세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings`는 해당 실행에서 `None`이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작을 바꾸지 않고 가져오기 크기를 제한하고 싶을 때 유용합니다.
+세션 구현이 기본 세션 설정을 제공하는 경우, `RunConfig.session_settings` 는 해당 실행에 대해 `None` 이 아닌 값을 재정의합니다. 이는 긴 대화에서 세션의 기본 동작은 변경하지 않으면서 조회 크기를 제한하고 싶을 때 유용합니다.
 
 ## 메모리 작업
 
 ### 기본 작업
 
-세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다.
+세션은 대화 기록 관리를 위한 여러 작업을 지원합니다.
 
 ```python
 from agents import SQLiteSession
@@ -167,7 +167,7 @@ await session.clear_session()
 
 ### 수정을 위한 pop_item 사용
 
-`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하려는 경우 특히 유용합니다.
+`pop_item` 메서드는 대화의 마지막 항목을 되돌리거나 수정하고 싶을 때 특히 유용합니다.
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -196,34 +196,34 @@ result = await Runner.run(
 print(f"Agent: {result.final_output}")
 ```
 
-## 내장 세션 구현
+## 기본 제공 세션 구현
 
-SDK는 다양한 사용 사례에 맞는 여러 세션 구현을 제공합니다.
+SDK는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다.
 
-### 내장 세션 구현 선택
+### 기본 제공 세션 구현 선택
 
-아래의 상세 예제를 읽기 전에 이 표를 사용해 출발점을 선택하세요.
+아래의 상세 예제를 읽기 전에 시작점을 고르는 데 이 표를 사용하세요.
 
-| 세션 유형 | 적합한 경우 | 참고 |
+| 세션 유형 | 적합한 용도 | 참고 |
 | --- | --- | --- |
-| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 내장형, 경량, 파일 기반 또는 인메모리 |
-| `AsyncSQLiteSession` | `aiosqlite`를 사용하는 비동기 SQLite | 비동기 드라이버 지원이 있는 확장 백엔드 |
-| `RedisSession` | 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 |
-| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy 지원 데이터베이스와 작동 |
-| `MongoDBSession` | 이미 MongoDB를 사용하거나 멀티프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 |
+| `SQLiteSession` | 로컬 개발 및 간단한 앱 | 기본 제공, 경량, 파일 기반 또는 인메모리 |
+| `AsyncSQLiteSession` | `aiosqlite` 기반 비동기 SQLite | 비동기 드라이버를 지원하는 확장 백엔드 |
+| `RedisSession` | 여러 워커/서비스 간 공유 메모리 | 저지연 분산 배포에 적합 |
+| `SQLAlchemySession` | 기존 데이터베이스를 사용하는 프로덕션 앱 | SQLAlchemy가 지원하는 데이터베이스와 함께 동작 |
+| `MongoDBSession` | 이미 MongoDB를 사용하거나 다중 프로세스 스토리지가 필요한 앱 | 비동기 pymongo; 순서 보장을 위한 원자적 시퀀스 카운터 |
 | `DaprSession` | Dapr 사이드카를 사용하는 클라우드 네이티브 배포 | 여러 상태 저장소와 TTL 및 일관성 제어 지원 |
 | `OpenAIConversationsSession` | OpenAI의 서버 관리형 스토리지 | OpenAI Conversations API 기반 기록 |
 | `OpenAIResponsesCompactionSession` | 자동 압축이 필요한 긴 대화 | 다른 세션 백엔드를 감싸는 래퍼 |
-| `AdvancedSQLiteSession` | SQLite와 브랜칭/분석 | 더 무거운 기능 세트; 전용 페이지 참조 |
-| `EncryptedSession` | 다른 세션 위의 암호화 + TTL | 래퍼; 먼저 기반 백엔드 선택 |
+| `AdvancedSQLiteSession` | SQLite와 분기/분석 | 더 많은 기능 세트; 전용 페이지 참조 |
+| `EncryptedSession` | 다른 세션 위에 암호화 + TTL 적용 | 래퍼; 먼저 하위 백엔드 선택 |
 
-일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 각 하위 섹션에 인라인으로 링크되어 있습니다.
+일부 구현에는 추가 세부 정보를 담은 전용 페이지가 있으며, 해당 하위 섹션에 링크되어 있습니다.
 
-ChatKit용 파이썬 서버를 구현하는 경우 ChatKit의 스레드 및 항목 영속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 대체하는 드롭인 대체품은 아닙니다. [`ChatKit 데이터 스토어 구현에 대한 chatkit-python 가이드`](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요.
+ChatKit용 Python 서버를 구현하는 경우, ChatKit의 스레드 및 항목 지속성을 위해 `chatkit.store.Store` 구현을 사용하세요. `SQLAlchemySession` 같은 Agents SDK 세션은 SDK 측 대화 기록을 관리하지만, ChatKit의 스토어를 그대로 대체할 수 있는 것은 아닙니다. [`chatkit-python` 의 ChatKit 데이터 스토어 구현 가이드](https://github.com/openai/chatkit-python/blob/main/docs/guides/respond-to-user-message.md#implement-your-chatkit-data-store)를 참조하세요.
 
 ### OpenAI Conversations API 세션
 
-`OpenAIConversationsSession`을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요.
+`OpenAIConversationsSession` 을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용하세요.
 
 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -259,7 +259,7 @@ print(result.final_output)  # "California"
 
 ### OpenAI Responses 압축 세션
 
-Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession`을 사용하세요. 이는 기반 세션을 감싸며 `should_trigger_compaction`에 따라 각 턴 후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession`을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다.
+Responses API(`responses.compact`)로 저장된 대화 기록을 압축하려면 `OpenAIResponsesCompactionSession` 을 사용하세요. 이 세션은 하위 세션을 감싸며, `should_trigger_compaction` 에 따라 각 턴 이후 자동으로 압축할 수 있습니다. `OpenAIConversationsSession` 을 이것으로 감싸지 마세요. 두 기능은 서로 다른 방식으로 기록을 관리합니다.
 
 #### 일반적인 사용법(자동 압축)
 
@@ -278,17 +278,17 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```
 
-기본적으로, 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다.
+기본적으로 압축은 후보 임계값에 도달하면 각 턴 이후 실행됩니다.
 
-`compaction_mode="previous_response_id"`는 Responses API 응답 ID로 이미 턴을 체이닝하고 있을 때 가장 잘 작동합니다. `compaction_mode="input"`은 대신 현재 세션 항목에서 압축 요청을 다시 구성하므로, 응답 체인을 사용할 수 없거나 세션 내용이 진실의 원천이 되길 원할 때 유용합니다. 기본값 `"auto"`는 사용 가능한 가장 안전한 옵션을 선택합니다.
+`compaction_mode="previous_response_id"` 는 이미 Responses API 응답 ID로 턴을 체이닝하고 있을 때 가장 잘 동작합니다. `compaction_mode="input"` 은 대신 현재 세션 항목으로부터 압축 요청을 다시 구성합니다. 이는 응답 체인을 사용할 수 없거나 세션 내용을 신뢰할 수 있는 기준으로 삼고 싶을 때 유용합니다. 기본값인 `"auto"` 는 사용 가능한 가장 안전한 옵션을 선택합니다.
 
-에이전트가 `ModelSettings(store=False)`로 실행되면 Responses API는 나중 조회를 위해 마지막 응답을 보관하지 않습니다. 이러한 무상태 설정에서는 기본 `"auto"` 모드가 `previous_response_id`에 의존하는 대신 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요.
+에이전트가 `ModelSettings(store=False)` 로 실행되는 경우, Responses API는 나중에 조회할 수 있도록 마지막 응답을 보관하지 않습니다. 이 무상태 구성에서는 기본 `"auto"` 모드가 `previous_response_id` 에 의존하지 않고 입력 기반 압축으로 폴백합니다. 전체 예제는 [`examples/memory/compaction_session_stateless_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/compaction_session_stateless_example.py)를 참조하세요.
 
-#### 자동 압축과 스트리밍 차단 가능성
+#### 스트리밍을 차단할 수 있는 자동 압축
 
-압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행을 완료로 간주하기 전에 압축이 끝날 때까지 기다립니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초 동안 열려 있을 수 있음을 의미합니다.
+압축은 세션 기록을 지우고 다시 쓰므로, SDK는 실행이 완료된 것으로 간주하기 전에 압축이 끝나기를 기다립니다. 스트리밍 모드에서는 압축 작업이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열린 상태로 남아 있을 수 있습니다.
 
-저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()`을 호출하세요. 자체 기준에 따라 언제 압축을 강제할지 결정할 수 있습니다.
+저지연 스트리밍이나 빠른 턴 전환을 원한다면 자동 압축을 비활성화하고 턴 사이(또는 유휴 시간)에 직접 `run_compaction()` 을 호출하세요. 자체 기준에 따라 언제 압축을 강제로 실행할지 결정할 수 있습니다.
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -311,7 +311,7 @@ await session.run_compaction({"force": True})
 
 ### SQLite 세션
 
-SQLite를 사용하는 기본 경량 세션 구현:
+SQLite를 사용하는 기본 경량 세션 구현입니다.
 
 ```python
 from agents import SQLiteSession
@@ -332,7 +332,7 @@ result = await Runner.run(
 
 ### 비동기 SQLite 세션
 
-`aiosqlite` 기반 SQLite 영속성이 필요할 때 `AsyncSQLiteSession`을 사용하세요.
+`aiosqlite` 기반 SQLite 지속성이 필요할 때 `AsyncSQLiteSession` 을 사용하세요.
 
 ```bash
 pip install aiosqlite
@@ -349,7 +349,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### Redis 세션
 
-여러 워커나 서비스 간 공유 세션 메모리에는 `RedisSession`을 사용하세요.
+여러 워커 또는 서비스 간 공유 세션 메모리에는 `RedisSession` 을 사용하세요.
 
 ```bash
 pip install openai-agents[redis]
@@ -369,7 +369,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### SQLAlchemy 세션
 
-SQLAlchemy가 지원하는 모든 데이터베이스를 사용한 프로덕션 준비 Agents SDK 세션 영속성:
+SQLAlchemy가 지원하는 모든 데이터베이스를 사용하는 프로덕션 환경에 적합한 Agents SDK 세션 지속성입니다.
 
 ```python
 from agents.extensions.memory import SQLAlchemySession
@@ -391,7 +391,7 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 
 ### Dapr 세션
 
-이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 다양한 상태 저장소 백엔드 간 이동할 수 있는 세션 스토리지가 필요할 때 `DaprSession`을 사용하세요.
+이미 Dapr 사이드카를 실행 중이거나 에이전트 코드를 변경하지 않고 여러 상태 저장소 백엔드 간에 이동할 수 있는 세션 스토리지를 원할 때 `DaprSession` 을 사용하세요.
 
 ```bash
 pip install openai-agents[dapr]
@@ -414,16 +414,16 @@ async with DaprSession.from_address(
 
 참고:
 
--   `from_address(...)`는 Dapr 클라이언트를 생성하고 소유합니다. 앱에서 이미 클라이언트를 관리한다면 `dapr_client=...`로 `DaprSession(...)`을 직접 생성하세요.
--   백킹 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...`을 전달하세요.
--   더 강한 쓰기 후 읽기 보장이 필요할 때는 `consistency=DAPR_CONSISTENCY_STRONG`을 전달하세요.
--   Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address`에서 사용하는 gRPC 포트와 함께 `--dapr-http-port 3500`으로 Dapr를 시작하세요.
--   로컬 컴포넌트와 문제 해결을 포함한 전체 설정 절차는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요.
+-   `from_address(...)` 는 Dapr 클라이언트를 생성하고 수명 주기를 관리합니다. 앱에서 이미 Dapr 클라이언트를 관리하고 있다면 `dapr_client=...` 로 `DaprSession(...)` 을 직접 생성하세요.
+-   기반 상태 저장소가 TTL을 지원하는 경우 오래된 세션 데이터가 자동으로 만료되도록 `ttl=...` 을 전달하세요.
+-   더 강한 쓰기 후 읽기 보장이 필요하면 `consistency=DAPR_CONSISTENCY_STRONG` 을 전달하세요.
+-   Dapr Python SDK는 HTTP 사이드카 엔드포인트도 확인합니다. 로컬 개발에서는 `dapr_address` 에서 사용하는 gRPC 포트뿐 아니라 `--dapr-http-port 3500` 도 함께 지정해 Dapr를 시작하세요.
+-   로컬 컴포넌트와 문제 해결을 포함한 전체 설정 안내는 [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py)를 참조하세요.
 
 
 ### MongoDB 세션
 
-이미 MongoDB를 사용하거나 수평 확장 가능한 멀티프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession`을 사용하세요.
+이미 MongoDB를 사용하거나 수평 확장이 가능한 다중 프로세스 세션 스토리지가 필요한 애플리케이션에는 `MongoDBSession` 을 사용하세요.
 
 ```bash
 pip install openai-agents[mongodb]
@@ -448,14 +448,14 @@ await session.close()
 
 참고:
 
--   `from_uri(...)`는 `AsyncMongoClient`를 생성하고 소유하며 `session.close()`에서 이를 닫습니다. 애플리케이션에서 이미 클라이언트를 관리한다면 `client=...`로 `MongoDBSession(...)`을 직접 생성하세요. 이 경우 `session.close()`는 아무 작업도 하지 않으며 라이프사이클은 호출자에게 있습니다.
--   다른 변경 없이 `from_uri(...)`에 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요.
--   두 컬렉션이 사용되며 두 이름 모두 `sessions_collection=`(기본값 `agent_sessions`)과 `messages_collection=`(기본값 `agent_messages`)를 통해 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서에는 동시 작성자와 프로세스 간 순서를 보존하는 단조 증가 `seq` 카운터가 포함됩니다.
--   첫 실행 전에 연결성을 확인하려면 `await session.ping()`을 사용하세요.
+-   `from_uri(...)` 는 `AsyncMongoClient` 를 생성하고 수명 주기를 관리하며, `session.close()` 시 닫습니다. 애플리케이션에서 이미 클라이언트를 관리하고 있다면 `client=...` 로 `MongoDBSession(...)` 을 직접 생성하세요. 이 경우 `session.close()` 는 아무 작업도 하지 않으며 수명 주기는 호출자에게 남아 있습니다.
+-   다른 변경 없이 `mongodb+srv://user:password@cluster.example.mongodb.net` URI를 `from_uri(...)` 에 전달하여 [MongoDB Atlas](https://www.mongodb.com/products/platform)에 연결하세요.
+-   두 개의 컬렉션이 사용되며, 두 이름 모두 `sessions_collection=` (기본값 `agent_sessions`) 및 `messages_collection=` (기본값 `agent_messages`) 로 구성할 수 있습니다. 인덱스는 처음 사용할 때 자동으로 생성됩니다. 각 메시지 문서는 단조 증가하는 `seq` 카운터를 포함하여 동시 작성자와 프로세스 간 순서를 보존합니다.
+-   첫 실행 전에 연결을 확인하려면 `await session.ping()` 을 사용하세요.
 
 ### 고급 SQLite 세션
 
-대화 브랜칭, 사용량 분석, structured queries를 갖춘 향상된 SQLite 세션:
+대화 분기, 사용량 분석, 구조화된 쿼리를 지원하는 향상된 SQLite 세션입니다.
 
 ```python
 from agents.extensions.memory import AdvancedSQLiteSession
@@ -479,7 +479,7 @@ await session.create_branch_from_turn(2)  # Branch from turn 2
 
 ### 암호화된 세션
 
-모든 세션 구현을 위한 투명한 암호화 래퍼:
+모든 세션 구현을 위한 투명한 암호화 래퍼입니다.
 
 ```python
 from agents.extensions.memory import EncryptedSession, SQLAlchemySession
@@ -506,7 +506,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### 기타 세션 유형
 
-몇 가지 내장 옵션이 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요.
+기본 제공 옵션이 몇 가지 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참조하세요.
 
 ## 운영 패턴
 
@@ -518,18 +518,18 @@ result = await Runner.run(agent, "Hello", session=session)
 -   스레드 기반: `"thread_abc123"`
 -   컨텍스트 기반: `"support_ticket_456"`
 
-### 메모리 영속성
+### 메모리 지속성
 
 -   임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`) 사용
--   영속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용
+-   지속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`) 사용
 -   `aiosqlite` 기반 구현이 필요할 때는 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`) 사용
 -   공유 저지연 세션 메모리에는 Redis 기반 세션(`RedisSession.from_url("session_id", url="redis://...")`) 사용
 -   SQLAlchemy가 지원하는 기존 데이터베이스가 있는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 사용
--   이미 MongoDB를 사용하거나 멀티프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용
--   내장 텔레메트리, 트레이싱 및 데이터 격리를 갖춘 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용
--   OpenAI Conversations API에 기록을 저장하는 것을 선호한다면 OpenAI 호스팅 스토리지(`OpenAIConversationsSession()`) 사용
--   모든 세션을 투명한 암호화 및 TTL 기반 만료로 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용
--   더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django)에 대한 사용자 지정 세션 백엔드 구현 고려
+-   이미 MongoDB를 사용하거나 다중 프로세스, 수평 확장 가능한 세션 스토리지가 필요한 애플리케이션에는 MongoDB 세션(`MongoDBSession.from_uri("session_id", uri="mongodb://localhost:27017")`) 사용
+-   기본 제공 텔레메트리, 트레이싱, 데이터 격리와 함께 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 사용
+-   OpenAI Conversations API에 기록을 저장하고 싶다면 OpenAI가 호스팅하는 스토리지(`OpenAIConversationsSession()`) 사용
+-   투명한 암호화와 TTL 기반 만료로 모든 세션을 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`) 사용
+-   더 고급 사용 사례에는 다른 프로덕션 시스템(예: Django)을 위한 사용자 지정 세션 백엔드 구현 고려
 
 ### 여러 세션
 
@@ -577,7 +577,7 @@ result2 = await Runner.run(
 
 ## 전체 예제
 
-다음은 세션 메모리가 동작하는 모습을 보여주는 전체 예제입니다.
+세션 메모리가 동작하는 방식을 보여주는 전체 예제입니다.
 
 ```python
 import asyncio
@@ -692,7 +692,7 @@ result = await Runner.run(
 |---------|-------------|
 | [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 위한 Django ORM 기반 세션 |
 
-세션 구현을 구축했다면 여기에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요!
+세션 구현을 만들었다면 이곳에 추가할 수 있도록 문서 PR을 자유롭게 제출해 주세요!
 
 ## API 참조
 
@@ -707,5 +707,5 @@ result = await Runner.run(
 -   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현
 -   [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] - MongoDB 기반 세션 구현
 -   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현
--   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭과 분석을 갖춘 향상된 SQLite
+-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기와 분석을 지원하는 향상된 SQLite
 -   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 모든 세션을 위한 암호화 래퍼

docs/ko/sessions/sqlalchemy_session.md

@@ -4,11 +4,11 @@ search:
 ---
 # SQLAlchemy 세션
 
-`SQLAlchemySession`은 SQLAlchemy를 사용하여 프로덕션 준비가 된 세션 구현을 제공하며, 세션 저장소에 SQLAlchemy가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 사용할 수 있게 해줍니다
+`SQLAlchemySession`은 SQLAlchemy를 사용해 프로덕션 환경에서 사용할 수 있는 세션 구현을 제공하며, 세션 저장소로 SQLAlchemy가 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 사용할 수 있습니다.
 
 ## 설치
 
-SQLAlchemy 세션에는 `sqlalchemy` extra가 필요합니다:
+SQLAlchemy 세션에는 `sqlalchemy` extra가 필요합니다.
 
 ```bash
 pip install openai-agents[sqlalchemy]
@@ -18,7 +18,7 @@ pip install openai-agents[sqlalchemy]
 
 ### 데이터베이스 URL 사용
 
-시작하는 가장 간단한 방법입니다:
+가장 간단하게 시작하는 방법입니다.
 
 ```python
 import asyncio
@@ -76,5 +76,5 @@ if __name__ == "__main__":
 
 ## API 참조
 
-- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 메인 클래스
+- [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 주요 클래스
 - [`Session`][agents.memory.session.Session] - 기본 세션 프로토콜

docs/ko/streaming.md

@@ -4,17 +4,17 @@ search:
 ---
 # 스트리밍
 
-스트리밍을 사용하면 에이전트 실행이 진행되는 동안 업데이트를 구독할 수 있습니다. 이는 최종 사용자에게 진행 상황 업데이트와 부분 응답을 보여줄 때 유용할 수 있습니다.
+스트리밍을 사용하면 에이전트 실행이 진행되는 동안 업데이트를 구독할 수 있습니다. 이는 최종 사용자에게 진행 상황 업데이트와 부분 응답을 보여주는 데 유용할 수 있습니다.
 
-스트리밍하려면 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 호출하면 되며, 그러면 [`RunResultStreaming`][agents.result.RunResultStreaming]을 받습니다. `result.stream_events()`를 호출하면 아래에 설명된 [`StreamEvent`][agents.stream_events.StreamEvent] 객체의 비동기 스트림을 얻을 수 있습니다.
+스트리밍하려면 [`Runner.run_streamed()`][agents.run.Runner.run_streamed]를 호출하면 되며, 이는 [`RunResultStreaming`][agents.result.RunResultStreaming]을 반환합니다. `result.stream_events()`를 호출하면 아래에 설명된 [`StreamEvent`][agents.stream_events.StreamEvent] 객체의 비동기 스트림을 얻을 수 있습니다.
 
-비동기 이터레이터가 끝날 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 종료될 때까지 완료된 것이 아니며, 세션 영속화, 승인 장부 처리, 히스토리 압축 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 끝날 수 있습니다. 루프가 종료되면 `result.is_complete`가 최종 실행 상태를 반영합니다.
+비동기 이터레이터가 종료될 때까지 `result.stream_events()`를 계속 소비하세요. 스트리밍 실행은 이터레이터가 끝나기 전까지 완료되지 않으며, 세션 영속화, 승인 기록 관리, 히스토리 압축과 같은 후처리는 마지막으로 보이는 토큰이 도착한 뒤에 완료될 수 있습니다. 루프가 종료되면 `result.is_complete`는 최종 실행 상태를 반영합니다.
 
-## 원시 응답 이벤트
+## 원문 응답 이벤트
 
-[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원시 이벤트입니다. OpenAI Responses API 형식이므로 각 이벤트에는 타입(예: `response.created`, `response.output_text.delta` 등)과 데이터가 있습니다. 이러한 이벤트는 생성되는 즉시 사용자에게 응답 메시지를 스트리밍하려는 경우에 유용합니다.
+[`RawResponsesStreamEvent`][agents.stream_events.RawResponsesStreamEvent]는 LLM에서 직접 전달되는 원문 이벤트입니다. OpenAI Responses API 형식이므로 각 이벤트에는 `response.created`, `response.output_text.delta` 등과 같은 타입과 데이터가 있습니다. 이러한 이벤트는 응답 메시지가 생성되는 즉시 사용자에게 스트리밍하려는 경우 유용합니다.
 
-컴퓨터 도구 원시 이벤트는 저장된 결과와 동일한 프리뷰-vs-GA 구분을 유지합니다. 프리뷰 플로는 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하는 반면, `gpt-5.5`는 일괄 처리된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 더 높은 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면은 이를 위해 컴퓨터 전용 특별 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 노출되며, 스크린샷 결과는 `computer_call_output` 항목을 감싼 `tool_output`으로 반환됩니다.
+컴퓨터 도구 원문 이벤트는 저장된 결과와 동일하게 preview-vs-GA 구분을 유지합니다. Preview 흐름은 하나의 `action`이 있는 `computer_call` 항목을 스트리밍하는 반면, `gpt-5.5`는 배치된 `actions[]`가 있는 `computer_call` 항목을 스트리밍할 수 있습니다. 상위 수준의 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent] 표면은 이를 위해 컴퓨터 전용의 특별한 이벤트 이름을 추가하지 않습니다. 두 형태 모두 여전히 `tool_called`로 표면화되며, 스크린샷 결과는 `computer_call_output` 항목을 래핑한 `tool_output`으로 반환됩니다.
 
 예를 들어, 다음은 LLM이 생성한 텍스트를 토큰 단위로 출력합니다.
 
@@ -39,9 +39,9 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## 스트리밍과 승인
+## 스트리밍 및 승인
 
-스트리밍은 도구 승인을 위해 일시 중지되는 실행과 호환됩니다. 도구에 승인이 필요한 경우 `result.stream_events()`가 종료되고 보류 중인 승인은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`로 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인하거나 거부한 다음 `Runner.run_streamed(...)`로 재개하세요.
+스트리밍은 도구 승인을 위해 일시 중지되는 실행과 호환됩니다. 도구에 승인이 필요한 경우 `result.stream_events()`가 종료되고 대기 중인 승인은 [`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.interruptions]에 노출됩니다. `result.to_state()`를 사용해 결과를 [`RunState`][agents.run_state.RunState]로 변환하고, 인터럽션(중단 처리)을 승인하거나 거부한 다음 `Runner.run_streamed(...)`로 재개하세요.
 
 ```python
 result = Runner.run_streamed(agent, "Delete temporary files if they are no longer needed.")
@@ -57,21 +57,21 @@ if result.interruptions:
         pass
 ```
 
-전체 일시 중지/재개 절차는 [휴먼인더루프 가이드](human_in_the_loop.md)를 참조하세요.
+전체 일시 중지/재개 과정을 보려면 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요.
 
 ## 현재 턴 이후 스트리밍 취소
 
-스트리밍 실행을 중간에 중지해야 하는 경우 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로 이는 실행을 즉시 중지합니다. 중지하기 전에 현재 턴이 깔끔하게 완료되도록 하려면 대신 `result.cancel(mode="after_turn")`을 호출하세요.
+스트리밍 실행을 중간에 중지해야 하는 경우 [`result.cancel()`][agents.result.RunResultStreaming.cancel]을 호출하세요. 기본적으로 이는 실행을 즉시 중지합니다. 중지하기 전에 현재 턴이 깔끔하게 끝나도록 하려면 대신 `result.cancel(mode="after_turn")`을 호출하세요.
 
-스트리밍된 실행은 `result.stream_events()`가 끝날 때까지 완료되지 않습니다. 마지막으로 보이는 토큰 이후에도 SDK가 세션 항목을 영속화하거나, 승인 상태를 마무리하거나, 히스토리를 압축하고 있을 수 있습니다.
+스트리밍된 실행은 `result.stream_events()`가 종료되기 전까지 완료되지 않습니다. 마지막으로 보이는 토큰 이후에도 SDK가 여전히 세션 항목을 영속화하거나, 승인 상태를 최종화하거나, 히스토리를 압축하고 있을 수 있습니다.
 
-[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 계속 진행하고 있으며 `cancel(mode="after_turn")`이 도구 턴 이후 중지되는 경우, 즉시 새 사용자 턴을 추가하는 대신 해당 정규화된 입력으로 `result.last_agent`를 다시 실행하여 완료되지 않은 턴을 계속하세요.
--   스트리밍 실행이 도구 승인 때문에 중지된 경우, 이를 새 턴으로 취급하지 마세요. 스트림을 끝까지 소진하고 `result.interruptions`를 검사한 다음 `result.to_state()`에서 재개하세요.
--   다음 모델 호출 전에 가져온 세션 히스토리와 새 사용자 입력을 병합하는 방식을 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 그곳에서 새 턴 항목을 다시 작성하면, 다시 작성된 버전이 해당 턴에 대해 영속화됩니다.
+[`result.to_input_list(mode="normalized")`][agents.result.RunResultBase.to_input_list]에서 수동으로 계속 진행하고 있고, `cancel(mode="after_turn")`가 도구 턴 이후에 중지되는 경우, 즉시 새 사용자 턴을 추가하는 대신 해당 정규화된 입력으로 `result.last_agent`를 다시 실행하여 완료되지 않은 턴을 계속 진행하세요.
+-   스트리밍된 실행이 도구 승인 때문에 중지된 경우 이를 새 턴으로 취급하지 마세요. 스트림 소비를 완료하고, `result.interruptions`를 검사한 뒤, `result.to_state()`에서 재개하세요.
+-   다음 모델 호출 전에 가져온 세션 히스토리와 새 사용자 입력이 병합되는 방식을 사용자 지정하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback]을 사용하세요. 여기에서 새 턴 항목을 다시 작성하면, 다시 작성된 버전이 해당 턴에 대해 영속화됩니다.
 
 ## 실행 항목 이벤트 및 에이전트 이벤트
 
-[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰이 아니라 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황 업데이트를 푸시할 수 있습니다. 마찬가지로 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과) 업데이트를 제공합니다.
+[`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]는 더 높은 수준의 이벤트입니다. 항목이 완전히 생성되었을 때 알려줍니다. 이를 통해 각 토큰 대신 "메시지 생성됨", "도구 실행됨" 등의 수준에서 진행 상황 업데이트를 푸시할 수 있습니다. 마찬가지로 [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent]는 현재 에이전트가 변경될 때(예: 핸드오프의 결과) 업데이트를 제공합니다.
 
 ### 실행 항목 이벤트 이름
 
@@ -89,11 +89,11 @@ if result.interruptions:
 -   `mcp_approval_response`
 -   `mcp_list_tools`
 
-`handoff_occured`는 하위 호환성을 위해 의도적으로 철자가 잘못되어 있습니다.
+`handoff_occured`는 이전 버전과의 호환성을 위해 의도적으로 철자가 틀리게 작성되었습니다.
 
-호스티드 툴 검색을 사용할 때는 모델이 도구 검색 요청을 발행하면 `tool_search_called`가 내보내지고, Responses API가 로드된 하위 집합을 반환하면 `tool_search_output_created`가 내보내집니다.
+호스티드 툴 검색을 사용하면 모델이 도구 검색 요청을 발행할 때 `tool_search_called`가 발생하고, Responses API가 로드된 하위 집합을 반환할 때 `tool_search_output_created`가 발생합니다.
 
-예를 들어, 다음은 원시 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다.
+예를 들어, 다음은 원문 이벤트를 무시하고 사용자에게 업데이트를 스트리밍합니다.
 
 ```python
 import asyncio

docs/ko/tools.md

@@ -4,37 +4,37 @@ search:
 ---
 # 도구
 
-도구를 사용하면 에이전트가 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용과 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다.
+도구를 통해 에이전트는 데이터 가져오기, 코드 실행, 외부 API 호출, 심지어 컴퓨터 사용 같은 작업을 수행할 수 있습니다. SDK는 다섯 가지 카테고리를 지원합니다.
 
 -   호스티드 OpenAI 도구: OpenAI 서버에서 모델과 함께 실행됩니다.
--   로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자의 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다.
--   Function Calling: 모든 Python 함수를 도구로 래핑합니다.
+-   로컬/런타임 실행 도구: `ComputerTool` 및 `ApplyPatchTool`은 항상 사용자 환경에서 실행되며, `ShellTool`은 로컬 또는 호스티드 컨테이너에서 실행될 수 있습니다.
+-   함수 호출: 모든 Python 함수를 도구로 래핑합니다.
 -   Agents as tools: 전체 핸드오프 없이 에이전트를 호출 가능한 도구로 노출합니다.
--   실험적: Codex 도구: 도구 호출에서 워크스페이스 범위의 Codex 작업을 실행합니다.
+-   실험적 기능: Codex 도구: 도구 호출에서 워크스페이스 범위 Codex 작업을 실행합니다.
 
 ## 도구 유형 선택
 
-이 페이지를 카탈로그로 사용한 다음, 제어하는 런타임에 맞는 섹션으로 이동하세요.
+이 페이지를 카탈로그로 활용한 다음, 제어하는 런타임에 맞는 섹션으로 이동하세요.
 
-| 원하는 작업 | 시작 위치 |
+| 원하는 작업... | 여기에서 시작 |
 | --- | --- |
-| OpenAI가 관리하는 도구 사용(웹 검색, 파일 검색, code interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 도구](#hosted-tools) |
-| 도구 검색으로 큰 도구 표면을 런타임까지 지연 | [호스티드 도구 검색](#hosted-tool-search) |
+| OpenAI 관리형 도구 사용(웹 검색, 파일 검색, code interpreter, 호스티드 MCP, 이미지 생성) | [호스티드 툴](#hosted-tools) |
+| 도구 검색으로 대규모 도구 노출을 런타임까지 지연 | [호스티드 툴 검색](#hosted-tool-search) |
 | 자체 프로세스 또는 환경에서 도구 실행 | [로컬 런타임 도구](#local-runtime-tools) |
 | Python 함수를 도구로 래핑 | [함수 도구](#function-tools) |
-| 한 에이전트가 핸드오프 없이 다른 에이전트를 호출하도록 허용 | [Agents as tools](#agents-as-tools) |
-| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적: Codex 도구](#experimental-codex-tool) |
+| 핸드오프 없이 한 에이전트가 다른 에이전트를 호출하게 하기 | [Agents as tools](#agents-as-tools) |
+| 에이전트에서 워크스페이스 범위 Codex 작업 실행 | [실험적 기능: Codex 도구](#experimental-codex-tool) |
 
-## 호스티드 도구
+## 호스티드 툴
 
-OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]을 사용할 때 몇 가지 기본 제공 도구를 제공합니다.
+OpenAI는 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel]을 사용할 때 몇 가지 내장 도구를 제공합니다.
 
--   [`WebSearchTool`][agents.tool.WebSearchTool]을 사용하면 에이전트가 웹을 검색할 수 있습니다.
+-   [`WebSearchTool`][agents.tool.WebSearchTool]은 에이전트가 웹을 검색할 수 있게 합니다.
 -   [`FileSearchTool`][agents.tool.FileSearchTool]은 OpenAI 벡터 스토어에서 정보를 검색할 수 있게 합니다.
 -   [`CodeInterpreterTool`][agents.tool.CodeInterpreterTool]은 LLM이 샌드박스 환경에서 코드를 실행할 수 있게 합니다.
 -   [`HostedMCPTool`][agents.tool.HostedMCPTool]은 원격 MCP 서버의 도구를 모델에 노출합니다.
 -   [`ImageGenerationTool`][agents.tool.ImageGenerationTool]은 프롬프트에서 이미지를 생성합니다.
--   [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 필요할 때 지연된 도구, 네임스페이스 또는 호스티드 MCP 서버를 로드할 수 있게 합니다.
+-   [`ToolSearchTool`][agents.tool.ToolSearchTool]은 모델이 지연 로딩 도구, 네임스페이스 또는 호스티드 MCP 서버를 필요할 때 로드할 수 있게 합니다.
 
 고급 호스티드 검색 옵션:
 
@@ -60,11 +60,11 @@ async def main():
     print(result.final_output)
 ```
 
-### 호스티드 도구 검색
+### 호스티드 툴 검색
 
-도구 검색을 사용하면 OpenAI Responses 모델이 큰 도구 표면을 런타임까지 지연시켜, 모델이 현재 턴에 필요한 하위 집합만 로드할 수 있습니다. 이는 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 많고 모든 도구를 미리 노출하지 않으면서 도구 스키마 토큰을 줄이고 싶을 때 유용합니다.
+도구 검색을 사용하면 OpenAI Responses 모델이 대규모 도구 노출을 런타임까지 지연할 수 있어, 모델은 현재 턴에 필요한 하위 집합만 로드합니다. 많은 함수 도구, 네임스페이스 그룹 또는 호스티드 MCP 서버가 있으며 모든 도구를 미리 노출하지 않고 도구 스키마 토큰을 줄이고 싶을 때 유용합니다.
 
-후보 도구를 에이전트를 빌드할 때 이미 알고 있다면 호스티드 도구 검색부터 시작하세요. 애플리케이션이 무엇을 로드할지 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동 실행하지 않습니다.
+후보 도구가 에이전트를 빌드할 때 이미 알려져 있다면 호스티드 툴 검색부터 시작하세요. 애플리케이션이 무엇을 로드할지 동적으로 결정해야 하는 경우 Responses API는 클라이언트 실행 도구 검색도 지원하지만, 표준 `Runner`는 해당 모드를 자동으로 실행하지 않습니다.
 
 ```python
 from typing import Annotated
@@ -108,24 +108,24 @@ print(result.final_output)
 
 알아둘 사항:
 
--   호스티드 도구 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다.
--   에이전트에서 지연 로딩 표면을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요.
--   검색 가능한 표면에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다.
--   지연 로딩 함수 도구는 반드시 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스만 사용하는 구성에서도 모델이 필요할 때 적절한 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다.
--   `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름과 설명 아래에 그룹화합니다. 이는 보통 `crm`, `billing`, `shipping`처럼 관련 도구가 많을 때 가장 적합합니다.
--   OpenAI의 공식 모범 사례 가이드는 [가능한 경우 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다.
--   가능하면 개별적으로 지연된 많은 함수보다 네임스페이스나 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 상위 수준 검색 표면과 더 나은 토큰 절감을 제공합니다.
--   네임스페이스는 즉시 사용 가능한 도구와 지연된 도구를 함께 포함할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능한 상태로 유지되며, 같은 네임스페이스의 지연된 도구는 도구 검색을 통해 로드됩니다.
--   경험상 각 네임스페이스는 비교적 작게 유지하되, 이상적으로는 함수 10개 미만으로 유지하세요.
--   이름이 지정된 `tool_choice`는 단독 네임스페이스 이름이나 지연 전용 도구를 대상으로 지정할 수 없습니다. `auto`, `required` 또는 실제 최상위 호출 가능 도구 이름을 선호하세요.
--   `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 이를 실행하는 대신 예외를 발생시킵니다.
--   도구 검색 활동은 전용 항목 및 이벤트 유형과 함께 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에 나타납니다.
--   네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 완전한 실행 가능 예제는 `examples/tools/tool_search.py`를 참조하세요.
+-   호스티드 툴 검색은 OpenAI Responses 모델에서만 사용할 수 있습니다. 현재 Python SDK 지원은 `openai>=2.25.0`에 따라 달라집니다.
+-   에이전트에 지연 로딩 대상을 구성할 때 `ToolSearchTool()`을 정확히 하나 추가하세요.
+-   검색 가능한 대상에는 `@function_tool(defer_loading=True)`, `tool_namespace(name=..., description=..., tools=[...])`, `HostedMCPTool(tool_config={..., "defer_loading": True})`가 포함됩니다.
+-   지연 로딩 함수 도구는 `ToolSearchTool()`과 함께 사용해야 합니다. 네임스페이스만 사용하는 설정도 모델이 필요할 때 적절한 그룹을 로드하도록 `ToolSearchTool()`을 사용할 수 있습니다.
+-   `tool_namespace()`는 `FunctionTool` 인스턴스를 공유 네임스페이스 이름 및 설명 아래에 그룹화합니다. `crm`, `billing`, `shipping`처럼 관련 도구가 많은 경우 일반적으로 가장 적합합니다.
+-   OpenAI의 공식 모범 사례 가이드는 [가능하면 네임스페이스 사용](https://developers.openai.com/api/docs/guides/tools-tool-search#use-namespaces-where-possible)입니다.
+-   가능하면 개별적으로 지연된 함수 다수보다 네임스페이스 또는 호스티드 MCP 서버를 선호하세요. 일반적으로 모델에 더 나은 상위 수준 검색 대상과 더 나은 토큰 절감을 제공합니다.
+-   네임스페이스는 즉시 사용 가능한 도구와 지연 도구를 혼합할 수 있습니다. `defer_loading=True`가 없는 도구는 즉시 호출 가능한 상태로 유지되고, 같은 네임스페이스의 지연 도구는 도구 검색을 통해 로드됩니다.
+-   경험칙으로 각 네임스페이스는 비교적 작게 유지하세요. 이상적으로는 함수 10개 미만이 좋습니다.
+-   이름이 지정된 `tool_choice`는 네임스페이스 이름만 있는 대상이나 지연 전용 도구를 대상으로 지정할 수 없습니다. `auto`, `required` 또는 실제 최상위 호출 가능 도구 이름을 선호하세요.
+-   `ToolSearchTool(execution="client")`는 수동 Responses 오케스트레이션용입니다. 모델이 클라이언트 실행 `tool_search_call`을 내보내면 표준 `Runner`는 이를 실행하지 않고 예외를 발생시킵니다.
+-   도구 검색 활동은 [`RunResult.new_items`](results.md#new-items) 및 [`RunItemStreamEvent`](streaming.md#run-item-event-names)에 전용 항목 및 이벤트 유형으로 나타납니다.
+-   네임스페이스 로딩과 최상위 지연 도구를 모두 다루는 전체 실행 가능한 예제는 `examples/tools/tool_search.py`를 참조하세요.
 -   공식 플랫폼 가이드: [도구 검색](https://developers.openai.com/api/docs/guides/tools-tool-search)
 
 ### 호스티드 컨테이너 셸 + 스킬
 
-`ShellTool`은 OpenAI 호스티드 컨테이너 실행도 지원합니다. 모델이 로컬 런타임 대신 관리형 컨테이너에서 셸 명령을 실행하도록 하려면 이 모드를 사용하세요.
+`ShellTool`은 OpenAI 호스팅 컨테이너 실행도 지원합니다. 모델이 로컬 런타임 대신 관리형 컨테이너에서 셸 명령을 실행하게 하려면 이 모드를 사용하세요.
 
 ```python
 from agents import Agent, Runner, ShellTool, ShellToolSkillReference
@@ -163,47 +163,47 @@ print(result.final_output)
 알아둘 사항:
 
 -   호스티드 셸은 Responses API 셸 도구를 통해 사용할 수 있습니다.
--   `container_auto`는 요청에 대한 컨테이너를 프로비저닝하며, `container_reference`는 기존 컨테이너를 재사용합니다.
--   `container_auto`는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다.
--   `environment.skills`는 스킬 참조와 인라인 스킬 번들을 허용합니다.
--   호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval` 또는 `on_approval`을 설정하지 마세요.
+-   `container_auto`는 요청을 위한 컨테이너를 프로비저닝하고, `container_reference`는 기존 컨테이너를 재사용합니다.
+-   `container_auto`에는 `file_ids` 및 `memory_limit`도 포함할 수 있습니다.
+-   `environment.skills`는 스킬 참조와 인라인 스킬 번들을 받습니다.
+-   호스티드 환경에서는 `ShellTool`에 `executor`, `needs_approval`, `on_approval`을 설정하지 마세요.
 -   `network_policy`는 `disabled` 및 `allowlist` 모드를 지원합니다.
--   허용 목록 모드에서 `network_policy.domain_secrets`는 이름으로 도메인 범위의 시크릿을 주입할 수 있습니다.
--   완전한 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요.
+-   allowlist 모드에서는 `network_policy.domain_secrets`가 이름으로 도메인 범위 시크릿을 주입할 수 있습니다.
+-   전체 예제는 `examples/tools/container_shell_skill_reference.py` 및 `examples/tools/container_shell_inline_skill.py`를 참조하세요.
 -   OpenAI 플랫폼 가이드: [Shell](https://platform.openai.com/docs/guides/tools-shell) 및 [Skills](https://platform.openai.com/docs/guides/tools-skills)
 
 ## 로컬 런타임 도구
 
-로컬 런타임 도구는 모델 응답 자체 외부에서 실행됩니다. 모델은 여전히 언제 호출할지 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다.
+로컬 런타임 도구는 모델 응답 자체의 외부에서 실행됩니다. 모델은 여전히 언제 호출할지 결정하지만, 실제 작업은 애플리케이션 또는 구성된 실행 환경이 수행합니다.
 
-`ComputerTool` 및 `ApplyPatchTool`에는 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드를 모두 포괄합니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을 사용하고, 명령이 자체 프로세스에서 실행되기를 원하면 아래 로컬 런타임 구성을 사용하세요.
+`ComputerTool` 및 `ApplyPatchTool`은 항상 사용자가 제공하는 로컬 구현이 필요합니다. `ShellTool`은 두 모드 모두에 걸쳐 있습니다. 관리형 실행을 원하면 위의 호스티드 컨테이너 구성을 사용하고, 명령이 자체 프로세스에서 실행되도록 하려면 아래의 로컬 런타임 구성을 사용하세요.
 
 로컬 런타임 도구에는 구현을 제공해야 합니다.
 
 -   [`ComputerTool`][agents.tool.ComputerTool]: GUI/브라우저 자동화를 활성화하려면 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 인터페이스를 구현하세요.
--   [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행 모두를 위한 최신 셸 도구입니다.
+-   [`ShellTool`][agents.tool.ShellTool]: 로컬 실행과 호스티드 컨테이너 실행을 모두 지원하는 최신 셸 도구입니다.
 -   [`LocalShellTool`][agents.tool.LocalShellTool]: 레거시 로컬 셸 통합입니다.
--   [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: 로컬에서 diff를 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요.
+-   [`ApplyPatchTool`][agents.tool.ApplyPatchTool]: diff를 로컬에 적용하려면 [`ApplyPatchEditor`][agents.editor.ApplyPatchEditor]를 구현하세요.
 -   로컬 셸 스킬은 `ShellTool(environment={"type": "local", "skills": [...]})`와 함께 사용할 수 있습니다.
 
 ### ComputerTool 및 Responses 컴퓨터 도구
 
 `ComputerTool`은 여전히 로컬 하네스입니다. 사용자가 [`Computer`][agents.computer.Computer] 또는 [`AsyncComputer`][agents.computer.AsyncComputer] 구현을 제공하면, SDK가 해당 하네스를 OpenAI Responses API 컴퓨터 표면에 매핑합니다.
 
-명시적 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA 기본 제공 도구 페이로드 `{"type": "computer"}`를 보냅니다. 더 오래된 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다.
+명시적 [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) 요청의 경우 SDK는 GA(정식 출시) 내장 도구 페이로드 `{"type": "computer"}`를 전송합니다. 이전 `computer-use-preview` 모델은 프리뷰 페이로드 `{"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...}`를 유지합니다. 이는 OpenAI의 [컴퓨터 사용 가이드](https://developers.openai.com/api/docs/guides/tools-computer-use/)에 설명된 플랫폼 마이그레이션을 반영합니다.
 
 -   모델: `computer-use-preview` -> `gpt-5.5`
--   도구 선택기: `computer_use_preview` -> `computer`
--   컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 일괄 처리된 `actions[]`
+-   도구 선택자: `computer_use_preview` -> `computer`
+-   컴퓨터 호출 형태: `computer_call`당 하나의 `action` -> `computer_call`의 배치된 `actions[]`
 -   잘림: 프리뷰 경로에서는 `ModelSettings(truncation="auto")` 필요 -> GA 경로에서는 필요하지 않음
 
-SDK는 실제 Responses 요청의 유효 모델에서 해당 wire 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하고 있어 요청에서 `model`을 생략하는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택기를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다.
+SDK는 실제 Responses 요청의 유효 모델을 기반으로 해당 전송 형태를 선택합니다. 프롬프트 템플릿을 사용하고 프롬프트가 모델을 소유하기 때문에 요청에서 `model`이 생략되는 경우, `model="gpt-5.5"`를 명시적으로 유지하거나 `ModelSettings(tool_choice="computer")` 또는 `ModelSettings(tool_choice="computer_use")`로 GA 선택자를 강제하지 않는 한 SDK는 프리뷰 호환 컴퓨터 페이로드를 유지합니다.
 
-[`ComputerTool`][agents.tool.ComputerTool]이 있을 때는 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 기본 제공 선택기로 정규화됩니다. `ComputerTool`이 없으면 이 문자열들은 여전히 일반 함수 이름처럼 동작합니다.
+[`ComputerTool`][agents.tool.ComputerTool]이 있으면 `tool_choice="computer"`, `"computer_use"`, `"computer_use_preview"`가 모두 허용되며 유효 요청 모델과 일치하는 내장 선택자로 정규화됩니다. `ComputerTool`이 없으면 이러한 문자열은 여전히 일반 함수 이름처럼 동작합니다.
 
-이 차이는 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리로 뒷받침될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기가 필요하지 않으므로, 해결되지 않은 팩토리도 괜찮습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 보낼 수 있도록 여전히 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 필요합니다.
+이 차이는 `ComputerTool`이 [`ComputerProvider`][agents.tool.ComputerProvider] 팩토리로 지원될 때 중요합니다. GA `computer` 페이로드는 직렬화 시점에 `environment` 또는 크기 정보가 필요하지 않으므로 해결되지 않은 팩토리도 괜찮습니다. 프리뷰 호환 직렬화에는 SDK가 `environment`, `display_width`, `display_height`를 전송할 수 있도록 해결된 `Computer` 또는 `AsyncComputer` 인스턴스가 여전히 필요합니다.
 
-런타임에는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 있는 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 일괄 처리된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요.
+런타임에는 두 경로 모두 동일한 로컬 하네스를 계속 사용합니다. 프리뷰 응답은 단일 `action`이 포함된 `computer_call` 항목을 내보냅니다. `gpt-5.5`는 배치된 `actions[]`를 내보낼 수 있으며, SDK는 `computer_call_output` 스크린샷 항목을 생성하기 전에 이를 순서대로 실행합니다. 실행 가능한 Playwright 기반 하네스는 `examples/tools/computer_use.py`를 참조하세요.
 
 ```python
 from agents import Agent, ApplyPatchTool, ShellTool
@@ -249,14 +249,14 @@ agent = Agent(
 
 모든 Python 함수를 도구로 사용할 수 있습니다. Agents SDK가 도구를 자동으로 설정합니다.
 
--   도구 이름은 Python 함수의 이름이 됩니다(또는 이름을 제공할 수 있습니다)
+-   도구 이름은 Python 함수 이름이 됩니다(또는 이름을 제공할 수 있습니다)
 -   도구 설명은 함수의 docstring에서 가져옵니다(또는 설명을 제공할 수 있습니다)
 -   함수 입력의 스키마는 함수의 인수에서 자동으로 생성됩니다
--   비활성화하지 않는 한 각 입력에 대한 설명은 함수의 docstring에서 가져옵니다
+-   각 입력의 설명은 비활성화하지 않는 한 함수의 docstring에서 가져옵니다
 
-함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring을 파싱하기 위해 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성을 위해 `pydantic`을 사용합니다.
+함수 시그니처를 추출하기 위해 Python의 `inspect` 모듈을 사용하고, docstring 파싱에는 [`griffe`](https://mkdocstrings.github.io/griffe/)를, 스키마 생성에는 `pydantic`을 사용합니다.
 
-OpenAI Responses 모델을 사용할 때 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. 관련 함수 도구를 [`tool_namespace()`][agents.tool.tool_namespace]로 그룹화할 수도 있습니다. 전체 설정과 제약 사항은 [호스티드 도구 검색](#hosted-tool-search)을 참조하세요.
+OpenAI Responses 모델을 사용하는 경우 `@function_tool(defer_loading=True)`는 `ToolSearchTool()`이 로드할 때까지 함수 도구를 숨깁니다. [`tool_namespace()`][agents.tool.tool_namespace]로 관련 함수 도구를 그룹화할 수도 있습니다. 전체 설정과 제약은 [호스티드 툴 검색](#hosted-tool-search)을 참조하세요.
 
 ```python
 import json
@@ -308,9 +308,9 @@ for tool in agent.tools:
 
 ```
 
-1.  함수 인수로 모든 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다.
-2.  Docstring이 있으면 설명과 인수 설명을 캡처하는 데 사용됩니다
-3.  함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 함). 도구 이름, 설명, 사용할 docstring 스타일 등과 같은 재정의도 설정할 수 있습니다.
+1.  함수 인수에는 모든 Python 타입을 사용할 수 있으며, 함수는 동기 또는 비동기일 수 있습니다.
+2.  docstring이 있으면 설명과 인수 설명을 캡처하는 데 사용됩니다.
+3.  함수는 선택적으로 `context`를 받을 수 있습니다(첫 번째 인수여야 합니다). 도구 이름, 설명, 사용할 docstring 스타일 등과 같은 재정의도 설정할 수 있습니다.
 4.  데코레이트된 함수를 도구 목록에 전달할 수 있습니다.
 
 ??? note "출력을 보려면 펼치기"
@@ -383,22 +383,22 @@ for tool in agent.tools:
     }
     ```
 
-### 함수 도구에서 이미지 또는 파일 반환
+### 함수 도구의 이미지 또는 파일 반환
 
 텍스트 출력 반환 외에도 함수 도구의 출력으로 하나 이상의 이미지 또는 파일을 반환할 수 있습니다. 이를 위해 다음 중 하나를 반환할 수 있습니다.
 
--   이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage] (또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict])
--   파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent] (또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict])
--   텍스트: 문자열 또는 문자열화 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText] (또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict])
+-   이미지: [`ToolOutputImage`][agents.tool.ToolOutputImage](또는 TypedDict 버전인 [`ToolOutputImageDict`][agents.tool.ToolOutputImageDict])
+-   파일: [`ToolOutputFileContent`][agents.tool.ToolOutputFileContent](또는 TypedDict 버전인 [`ToolOutputFileContentDict`][agents.tool.ToolOutputFileContentDict])
+-   텍스트: 문자열 또는 문자열로 변환 가능한 객체, 또는 [`ToolOutputText`][agents.tool.ToolOutputText](또는 TypedDict 버전인 [`ToolOutputTextDict`][agents.tool.ToolOutputTextDict])
 
 ### 사용자 지정 함수 도구
 
-때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원한다면 [`FunctionTool`][agents.tool.FunctionTool]을 직접 만들 수 있습니다. 다음을 제공해야 합니다.
+때로는 Python 함수를 도구로 사용하고 싶지 않을 수 있습니다. 원하는 경우 [`FunctionTool`][agents.tool.FunctionTool]을 직접 생성할 수 있습니다. 다음을 제공해야 합니다.
 
 -   `name`
 -   `description`
 -   `params_json_schema`: 인수에 대한 JSON 스키마
--   `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 인수를 JSON 문자열로 받고 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 async 함수
+-   `on_invoke_tool`: [`ToolContext`][agents.tool_context.ToolContext]와 JSON 문자열 형태의 인수를 받아 도구 출력(예: 텍스트, 구조화된 도구 출력 객체 또는 출력 목록)을 반환하는 비동기 함수
 
 ```python
 from typing import Any
@@ -433,16 +433,16 @@ tool = FunctionTool(
 
 ### 자동 인수 및 docstring 파싱
 
-앞서 언급했듯이, 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 이에 대한 몇 가지 참고 사항은 다음과 같습니다.
+앞서 언급했듯이 도구의 스키마를 추출하기 위해 함수 시그니처를 자동으로 파싱하고, 도구와 개별 인수의 설명을 추출하기 위해 docstring을 파싱합니다. 관련 참고 사항은 다음과 같습니다.
 
-1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 어노테이션을 사용하여 인수의 타입을 이해하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다.
-2. `griffe`를 사용하여 docstring을 파싱합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동으로 감지하려고 시도하지만 이는 최선의 노력이며, `function_tool`을 호출할 때 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 docstring 파싱을 비활성화할 수도 있습니다.
+1. 시그니처 파싱은 `inspect` 모듈을 통해 수행됩니다. 타입 주석을 사용해 인수 타입을 파악하고, 전체 스키마를 나타내는 Pydantic 모델을 동적으로 빌드합니다. Python 기본 타입, Pydantic 모델, TypedDict 등 대부분의 타입을 지원합니다.
+2. docstring 파싱에는 `griffe`를 사용합니다. 지원되는 docstring 형식은 `google`, `sphinx`, `numpy`입니다. docstring 형식을 자동으로 감지하려고 시도하지만 이는 최선의 시도 방식이며, `function_tool`을 호출할 때 명시적으로 설정할 수 있습니다. `use_docstring_info`를 `False`로 설정하여 docstring 파싱을 비활성화할 수도 있습니다.
 
 스키마 추출 코드는 [`agents.function_schema`][]에 있습니다.
 
-### Pydantic Field로 인수 제한 및 설명
+### Pydantic Field를 사용한 인수 제약 및 설명
 
-Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용하여 도구 인수에 제약(예: 숫자의 최소/최대, 문자열의 길이 또는 패턴)과 설명을 추가할 수 있습니다. Pydantic에서처럼 두 형식이 모두 지원됩니다. 기본값 기반(`arg: int = Field(..., ge=1)`) 및 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`). 생성된 JSON 스키마와 유효성 검사에는 이러한 제약이 포함됩니다.
+Pydantic의 [`Field`](https://docs.pydantic.dev/latest/concepts/fields/)를 사용하여 도구 인수에 제약(예: 숫자의 최솟값/최댓값, 문자열 길이 또는 패턴)과 설명을 추가할 수 있습니다. Pydantic과 마찬가지로 두 형식 모두 지원됩니다. 기본값 기반(`arg: int = Field(..., ge=1)`)과 `Annotated`(`arg: Annotated[int, Field(..., ge=1)]`)입니다. 생성된 JSON 스키마와 검증에는 이러한 제약이 포함됩니다.
 
 ```python
 from typing import Annotated
@@ -462,7 +462,7 @@ def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score fr
 
 ### 함수 도구 타임아웃
 
-`@function_tool(timeout=...)`으로 async 함수 도구에 호출별 타임아웃을 설정할 수 있습니다.
+`@function_tool(timeout=...)`으로 비동기 함수 도구의 호출별 타임아웃을 설정할 수 있습니다.
 
 ```python
 import asyncio
@@ -482,11 +482,11 @@ agent = Agent(
 )
 ```
 
-타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델이 볼 수 있는 타임아웃 메시지(예: `Tool 'slow_lookup' timed out after 2 seconds.`)를 보냅니다.
+타임아웃에 도달하면 기본 동작은 `timeout_behavior="error_as_result"`이며, 모델에서 볼 수 있는 타임아웃 메시지(예: `Tool 'slow_lookup' timed out after 2 seconds.`)를 보냅니다.
 
 타임아웃 처리를 제어할 수 있습니다.
 
--   `timeout_behavior="error_as_result"` (기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 반환합니다.
+-   `timeout_behavior="error_as_result"`(기본값): 모델이 복구할 수 있도록 타임아웃 메시지를 모델에 반환합니다.
 -   `timeout_behavior="raise_exception"`: [`ToolTimeoutError`][agents.exceptions.ToolTimeoutError]를 발생시키고 실행을 실패시킵니다.
 -   `timeout_error_function=...`: `error_as_result`를 사용할 때 타임아웃 메시지를 사용자 지정합니다.
 
@@ -511,15 +511,15 @@ except ToolTimeoutError as e:
 
 !!! note
 
-    타임아웃 구성은 async `@function_tool` 핸들러에만 지원됩니다.
+    타임아웃 구성은 비동기 `@function_tool` 핸들러에만 지원됩니다.
 
-### 함수 도구의 오류 처리
+### 함수 도구 오류 처리
 
-`@function_tool`을 통해 함수 도구를 만들 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 충돌하는 경우 LLM에 오류 응답을 제공하는 함수입니다.
+`@function_tool`을 통해 함수 도구를 생성할 때 `failure_error_function`을 전달할 수 있습니다. 이는 도구 호출이 충돌하는 경우 LLM에 오류 응답을 제공하는 함수입니다.
 
--   기본적으로(즉, 아무것도 전달하지 않으면) LLM에 오류가 발생했음을 알리는 `default_tool_error_function`이 실행됩니다.
--   자체 오류 함수를 전달하면 대신 그것이 실행되고 응답이 LLM에 전송됩니다.
--   명시적으로 `None`을 전달하면 모든 도구 호출 오류가 다시 발생하여 직접 처리할 수 있습니다. 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`일 수 있고, 코드가 충돌한 경우 `UserError`일 수 있습니다.
+-   기본적으로(즉, 아무것도 전달하지 않으면) LLM에 오류가 발생했음을 알리는 `default_tool_error_function`을 실행합니다.
+-   자체 오류 함수를 전달하면 그 함수를 대신 실행하고 응답을 LLM에 보냅니다.
+-   명시적으로 `None`을 전달하면 모든 도구 호출 오류가 다시 발생하므로 직접 처리할 수 있습니다. 이는 모델이 잘못된 JSON을 생성한 경우 `ModelBehaviorError`일 수도 있고, 코드가 충돌한 경우 `UserError`일 수도 있습니다.
 
 ```python
 from agents import function_tool, RunContextWrapper
@@ -542,7 +542,7 @@ def get_user_profile(user_id: str) -> str:
 
 ```
 
-`FunctionTool` 객체를 수동으로 만드는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다.
+`FunctionTool` 객체를 수동으로 생성하는 경우 `on_invoke_tool` 함수 내부에서 오류를 처리해야 합니다.
 
 ## Agents as tools
 
@@ -585,9 +585,9 @@ async def main():
     print(result.final_output)
 ```
 
-### 도구 에이전트 사용자 지정
+### 도구-에이전트 사용자 지정
 
-`agent.as_tool` 함수는 에이전트를 도구로 쉽게 전환할 수 있게 해주는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 통한 structured input도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, fallback 동작 또는 여러 에이전트 호출 체이닝)의 경우 도구 구현에서 `Runner.run`을 직접 사용하세요.
+`agent.as_tool` 함수는 에이전트를 쉽게 도구로 전환할 수 있게 해주는 편의 메서드입니다. `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, `needs_approval` 같은 일반적인 런타임 옵션을 지원합니다. 또한 `parameters`, `input_builder`, `include_input_schema`를 사용한 구조화된 입력도 지원합니다. 고급 오케스트레이션(예: 조건부 재시도, fallback 동작 또는 여러 에이전트 호출 체이닝)이 필요한 경우 도구 구현에서 `Runner.run`을 직접 사용하세요.
 
 ```python
 @function_tool
@@ -606,7 +606,7 @@ async def run_my_agent() -> str:
     return str(result.final_output)
 ```
 
-### 도구 에이전트의 구조화된 입력
+### 도구-에이전트의 구조화된 입력
 
 기본적으로 `Agent.as_tool()`은 단일 문자열 입력(`{"input": "..."}`)을 기대하지만, `parameters`(Pydantic 모델 또는 dataclass 타입)를 전달하여 구조화된 스키마를 노출할 수 있습니다.
 
@@ -614,7 +614,7 @@ async def run_my_agent() -> str:
 
 - `include_input_schema=True`는 생성된 중첩 입력에 전체 JSON Schema를 포함합니다.
 - `input_builder=...`를 사용하면 구조화된 도구 인수가 중첩 에이전트 입력이 되는 방식을 완전히 사용자 지정할 수 있습니다.
-- `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 안에 파싱된 구조화 페이로드를 포함합니다.
+- `RunContextWrapper.tool_input`은 중첩 실행 컨텍스트 내부의 파싱된 구조화 페이로드를 포함합니다.
 
 ```python
 from pydantic import BaseModel, Field
@@ -634,19 +634,19 @@ translator_tool = translator_agent.as_tool(
 )
 ```
 
-완전한 실행 가능 예제는 `examples/agent_patterns/agents_as_tools_structured.py`를 참조하세요.
+전체 실행 가능한 예제는 `examples/agent_patterns/agents_as_tools_structured.py`를 참조하세요.
 
-### 도구 에이전트의 승인 게이트
+### 도구-에이전트의 승인 게이트
 
-`Agent.as_tool(..., needs_approval=...)`은 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요한 경우 실행이 일시 중지되고 보류 중인 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요.
+`Agent.as_tool(..., needs_approval=...)`은 `function_tool`과 동일한 승인 흐름을 사용합니다. 승인이 필요한 경우 실행이 일시 중지되고 대기 중인 항목이 `result.interruptions`에 나타납니다. 그런 다음 `result.to_state()`를 사용하고 `state.approve(...)` 또는 `state.reject(...)`를 호출한 뒤 재개하세요. 전체 일시 중지/재개 패턴은 [휴먼인더루프 (HITL) 가이드](human_in_the_loop.md)를 참조하세요.
 
 ### 사용자 지정 출력 추출
 
-특정 경우에는 중앙 에이전트에 반환하기 전에 도구 에이전트의 출력을 수정하고 싶을 수 있습니다. 이는 다음을 원할 때 유용할 수 있습니다.
+특정 경우에는 중앙 에이전트에 반환하기 전에 도구-에이전트의 출력을 수정하고 싶을 수 있습니다. 다음과 같은 경우 유용할 수 있습니다.
 
--   하위 에이전트의 채팅 기록에서 특정 정보 조각(예: JSON 페이로드)을 추출
--   에이전트의 최종 답변을 변환하거나 다시 포맷(예: Markdown을 일반 텍스트 또는 CSV로 변환)
--   출력을 검증하거나 에이전트의 응답이 누락되었거나 잘못된 형식일 때 fallback 값 제공
+-   하위 에이전트의 채팅 기록에서 특정 정보(예: JSON 페이로드) 추출
+-   에이전트의 최종 답변 변환 또는 형식 재구성(예: Markdown을 일반 텍스트 또는 CSV로 변환)
+-   에이전트 응답이 누락되었거나 형식이 잘못된 경우 출력 검증 또는 fallback 값 제공
 
 `as_tool` 메서드에 `custom_output_extractor` 인수를 제공하여 이를 수행할 수 있습니다.
 
@@ -667,14 +667,14 @@ json_tool = data_agent.as_tool(
 )
 ```
 
-사용자 지정 추출기 안에서 중첩 [`RunResult`][agents.result.RunResult]는
-[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는 중첩 결과를 후처리하는 동안
-외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다.
+사용자 지정 추출기 내부에서 중첩된 [`RunResult`][agents.result.RunResult]는
+[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation]도 노출하며, 이는
+중첩 결과를 후처리하는 동안 외부 도구 이름, 호출 ID 또는 원문 인수가 필요할 때 유용합니다.
 [결과 가이드](results.md#agent-as-tool-metadata)를 참조하세요.
 
 ### 중첩 에이전트 실행 스트리밍
 
-`as_tool`에 `on_stream` 콜백을 전달하면, 스트림이 완료된 뒤 최종 출력을 반환하면서도 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신할 수 있습니다.
+`as_tool`에 `on_stream` 콜백을 전달하면 중첩 에이전트가 내보내는 스트리밍 이벤트를 수신하면서, 스트림이 완료된 뒤 최종 출력도 반환할 수 있습니다.
 
 ```python
 from agents import AgentToolStreamEvent
@@ -694,15 +694,15 @@ billing_agent_tool = billing_agent.as_tool(
 
 예상 동작:
 
-- 이벤트 유형은 `StreamEvent["type"]`를 반영합니다. `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`
-- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드로 실행되고 최종 출력을 반환하기 전에 스트림을 모두 소비합니다.
-- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착하는 순서대로 전달됩니다.
-- `tool_call`은 도구가 모델 도구 호출을 통해 호출될 때 존재합니다. 직접 호출에서는 `None`으로 남을 수 있습니다.
-- 완전한 실행 가능 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요.
+- 이벤트 유형은 `StreamEvent["type"]`을 반영합니다. `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`
+- `on_stream`을 제공하면 중첩 에이전트가 자동으로 스트리밍 모드에서 실행되며, 최종 출력을 반환하기 전에 스트림을 모두 소비합니다.
+- 핸들러는 동기 또는 비동기일 수 있으며, 각 이벤트는 도착한 순서대로 전달됩니다.
+- 도구가 모델 도구 호출을 통해 호출되면 `tool_call`이 존재합니다. 직접 호출에서는 `None`일 수 있습니다.
+- 전체 실행 가능한 샘플은 `examples/agent_patterns/agents_as_tools_streaming.py`를 참조하세요.
 
 ### 조건부 도구 활성화
 
-`is_enabled` 매개변수를 사용하여 런타임에 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에 사용 가능한 도구를 동적으로 필터링할 수 있습니다.
+`is_enabled` 매개변수를 사용하여 런타임에 에이전트 도구를 조건부로 활성화하거나 비활성화할 수 있습니다. 이를 통해 컨텍스트, 사용자 선호도 또는 런타임 조건에 따라 LLM에 제공되는 도구를 동적으로 필터링할 수 있습니다.
 
 ```python
 import asyncio
@@ -757,24 +757,24 @@ async def main():
 asyncio.run(main())
 ```
 
-`is_enabled` 매개변수는 다음을 허용합니다.
+`is_enabled` 매개변수는 다음을 받습니다.
 
--   **Boolean 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화)
--   **호출 가능한 함수**: `(context, agent)`를 받아 boolean을 반환하는 함수
--   **Async 함수**: 복잡한 조건부 로직을 위한 async 함수
+-   **불리언 값**: `True`(항상 활성화) 또는 `False`(항상 비활성화)
+-   **호출 가능 함수**: `(context, agent)`를 받아 불리언을 반환하는 함수
+-   **비동기 함수**: 복잡한 조건부 로직을 위한 비동기 함수
 
-비활성화된 도구는 런타임에 LLM으로부터 완전히 숨겨지므로, 다음에 유용합니다.
+비활성화된 도구는 런타임에 LLM에게 완전히 숨겨지므로 다음에 유용합니다.
 
 -   사용자 권한에 기반한 기능 게이팅
--   환경별 도구 사용 가능성(dev vs prod)
--   서로 다른 도구 구성의 A/B 테스트
+-   환경별 도구 가용성(개발 vs 프로덕션)
+-   다양한 도구 구성의 A/B 테스트
 -   런타임 상태에 기반한 동적 도구 필터링
 
-## 실험적: Codex 도구
+## 실험적 기능: Codex 도구
 
-`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중에 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다.
+`codex_tool`은 Codex CLI를 래핑하여 에이전트가 도구 호출 중 워크스페이스 범위 작업(셸, 파일 편집, MCP 도구)을 실행할 수 있게 합니다. 이 표면은 실험적이며 변경될 수 있습니다.
 
-메인 에이전트가 현재 실행을 벗어나지 않고 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 사용하세요. 기본적으로 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다.
+메인 에이전트가 현재 실행을 벗어나지 않고 범위가 제한된 워크스페이스 작업을 Codex에 위임하도록 하려면 사용하세요. 기본적으로 도구 이름은 `codex`입니다. 사용자 지정 이름을 설정하는 경우 `codex`이거나 `codex_`로 시작해야 합니다. 에이전트에 여러 Codex 도구가 포함된 경우 각 도구는 고유한 이름을 사용해야 합니다.
 
 ```python
 from agents import Agent
@@ -803,33 +803,33 @@ agent = Agent(
 )
 ```
 
-다음 옵션 그룹부터 시작하세요.
+다음 옵션 그룹부터 살펴보세요.
 
--   실행 표면: `sandbox_mode` 및 `working_directory`는 Codex가 작동할 수 있는 위치를 정의합니다. 둘을 함께 사용하고, 작업 디렉터리가 Git 저장소 안에 있지 않으면 `skip_git_repo_check=True`를 설정하세요.
--   스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, reasoning effort, approval policy, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요.
+-   실행 범위: `sandbox_mode` 및 `working_directory`는 Codex가 작업할 수 있는 위치를 정의합니다. 둘을 함께 설정하고, 작업 디렉터리가 Git 저장소 안에 있지 않으면 `skip_git_repo_check=True`를 설정하세요.
+-   스레드 기본값: `default_thread_options=ThreadOptions(...)`는 모델, 추론 강도, 승인 정책, 추가 디렉터리, 네트워크 액세스, 웹 검색 모드를 구성합니다. 레거시 `web_search_enabled`보다 `web_search_mode`를 선호하세요.
 -   턴 기본값: `default_turn_options=TurnOptions(...)`는 `idle_timeout_seconds` 및 선택적 취소 `signal` 같은 턴별 동작을 구성합니다.
--   도구 I/O: 도구 호출은 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 있는 `inputs` 항목을 최소 하나 포함해야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다.
+-   도구 I/O: 도구 호출에는 `{ "type": "text", "text": ... }` 또는 `{ "type": "local_image", "path": ... }`가 포함된 `inputs` 항목이 적어도 하나 있어야 합니다. `output_schema`를 사용하면 구조화된 Codex 응답을 요구할 수 있습니다.
 
-스레드 재사용과 지속성은 별도의 제어입니다.
+스레드 재사용과 지속성은 별도의 제어 항목입니다.
 
--   `persist_session=True`는 같은 도구 인스턴스에 반복적으로 호출할 때 하나의 Codex 스레드를 재사용합니다.
+-   `persist_session=True`는 같은 도구 인스턴스에 대한 반복 호출에 하나의 Codex 스레드를 재사용합니다.
 -   `use_run_context_thread_id=True`는 동일한 변경 가능한 컨텍스트 객체를 공유하는 실행 전반에서 실행 컨텍스트에 스레드 ID를 저장하고 재사용합니다.
--   스레드 ID 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 구성된 `thread_id` 옵션 순입니다.
+-   스레드 ID 우선순위는 호출별 `thread_id`, 실행 컨텍스트 스레드 ID(활성화된 경우), 설정된 `thread_id` 옵션 순입니다.
 -   기본 실행 컨텍스트 키는 `name="codex"`의 경우 `codex_thread_id`이고, `name="codex_<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`를 해석한 뒤, 번들된 벤더 바이너리로 fallback합니다.
--   환경: `codex_options.env`는 서브프로세스 환경을 완전히 제어합니다. 이 값이 제공되면 서브프로세스는 `os.environ`을 상속하지 않습니다.
--   스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr reader 제한을 제어합니다. 유효 범위는 `65536`부터 `67108864`까지이며, 기본값은 `8388608`입니다.
+-   바이너리 확인: CLI 경로를 고정하려면 `codex_options.codex_path_override`(또는 `CODEX_PATH`)를 설정하세요. 그렇지 않으면 SDK는 `PATH`에서 `codex`를 확인한 뒤, 번들된 벤더 바이너리로 fallback합니다.
+-   환경: `codex_options.env`는 하위 프로세스 환경을 완전히 제어합니다. 제공된 경우 하위 프로세스는 `os.environ`을 상속하지 않습니다.
+-   스트림 제한: `codex_options.codex_subprocess_stream_limit_bytes`(또는 `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`)는 stdout/stderr 리더 제한을 제어합니다. 유효 범위는 `65536`부터 `67108864`까지이며, 기본값은 `8388608`입니다.
 -   스트리밍: `on_stream`은 스레드/턴 수명 주기 이벤트와 항목 이벤트(`reasoning`, `command_execution`, `mcp_tool_call`, `file_change`, `web_search`, `todo_list`, `error` 항목 업데이트)를 수신합니다.
--   출력: 결과에는 `response`, `usage`, `thread_id`가 포함되며, usage는 `RunContextWrapper.usage`에 추가됩니다.
+-   출력: 결과에는 `response`, `usage`, `thread_id`가 포함됩니다. usage는 `RunContextWrapper.usage`에 추가됩니다.
 
-참조:
+참고 자료:
 
--   [Codex 도구 API 참조](ref/extensions/experimental/codex/codex_tool.md)
--   [ThreadOptions 참조](ref/extensions/experimental/codex/thread_options.md)
--   [TurnOptions 참조](ref/extensions/experimental/codex/turn_options.md)
--   완전한 실행 가능 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참조하세요.
+-   [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`를 참조하세요.

docs/ko/tracing.md

@@ -4,55 +4,59 @@ search:
 ---
 # 트레이싱
 
-Agents SDK에는 기본 제공 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트의 포괄적인 기록을 수집합니다. 여기에는 LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 발생한 사용자 정의 이벤트까지 포함됩니다. [Traces dashboard](https://platform.openai.com/traces)를 사용하면 개발 중과 프로덕션 환경에서 워크플로를 디버그하고, 시각화하고, 모니터링할 수 있습니다.
+Agents SDK에는 기본 제공 트레이싱이 포함되어 있어, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 발생한 사용자 지정 이벤트까지)에 대한 포괄적인 기록을 수집합니다. [트레이스 대시보드](https://platform.openai.com/traces)를 사용하면 개발 중 및 프로덕션 환경에서 워크플로를 디버그하고, 시각화하고, 모니터링할 수 있습니다.
 
 !!!note
 
-    트레이싱은 기본적으로 활성화되어 있습니다. 다음의 일반적인 세 가지 방법으로 비활성화할 수 있습니다:
+    트레이싱은 기본적으로 활성화되어 있습니다. 다음 세 가지 일반적인 방법으로 비활성화할 수 있습니다.
 
-    1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1` 을 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다
-    2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]를 사용해 전역적으로 트레이싱을 비활성화할 수 있습니다
-    3. 단일 실행에 대해서는 [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 트레이싱을 비활성화할 수 있습니다
+    1. env var `OPENAI_AGENTS_DISABLE_TRACING=1`을 설정하여 트레이싱을 전역적으로 비활성화할 수 있습니다
+    2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]를 사용하여 트레이싱을 전역적으로 비활성화할 수 있습니다
+    3. [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 단일 실행에 대해 트레이싱을 비활성화할 수 있습니다
 
-***OpenAI API를 사용하면서 Zero Data Retention (ZDR) 정책 하에서 운영하는 조직에서는 트레이싱을 사용할 수 없습니다.***
+***OpenAI의 API를 사용하며 Zero Data Retention (ZDR) 정책에 따라 운영되는 조직에서는 트레이싱을 사용할 수 없습니다.***
 
 ## 트레이스와 스팬
 
--   **트레이스**는 하나의 "워크플로"에 대한 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다:
-    -   `workflow_name`: 논리적인 워크플로 또는 앱입니다. 예를 들어 "Code generation" 또는 "Customer service"입니다.
+-   **트레이스**는 "워크플로"의 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다.
+    -   `workflow_name`: 논리적 워크플로 또는 앱입니다. 예를 들어 "Code generation" 또는 "Customer service"입니다.
     -   `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동으로 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다.
-    -   `group_id`: 선택적 그룹 ID로, 동일한 대화에서 나온 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다.
+    -   `group_id`: 동일한 대화의 여러 트레이스를 연결하기 위한 선택적 그룹 ID입니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다.
     -   `disabled`: True이면 트레이스가 기록되지 않습니다.
-    -   `metadata`: 트레이스에 대한 선택적 메타데이터입니다.
--   **스팬**은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다:
+    -   `metadata`: 트레이스의 선택적 메타데이터입니다.
+-   **스팬**은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다.
     -   `started_at` 및 `ended_at` 타임스탬프
-    -   `trace_id`: 이 스팬이 속한 트레이스를 나타냅니다
-    -   `parent_id`: 이 스팬의 상위 스팬을 가리킵니다(있는 경우)
-    -   `span_data`: 스팬에 대한 정보입니다. 예를 들어 `AgentSpanData`에는 Agent에 대한 정보가, `GenerationSpanData`에는 LLM 생성에 대한 정보가 포함됩니다.
+    -   자신이 속한 트레이스를 나타내는 `trace_id`
+    -   이 스팬의 부모 스팬(있는 경우)을 가리키는 `parent_id`
+    -   스팬에 대한 정보인 `span_data`. 예를 들어 `AgentSpanData`는 에이전트에 대한 정보를 포함하고, `GenerationSpanData`는 LLM 생성에 대한 정보를 포함하는 식입니다.
 
 ## 기본 트레이싱
 
-기본적으로 SDK는 다음을 트레이싱합니다:
+기본적으로 SDK는 다음을 트레이싱합니다.
 
--   전체 `Runner.{run, run_sync, run_streamed}()`는 `trace()`로 감싸집니다
--   에이전트가 실행될 때마다 `agent_span()`으로 감싸집니다
--   LLM 생성은 `generation_span()`으로 감싸집니다
--   함수 도구 호출은 각각 `function_span()`으로 감싸집니다
--   가드레일은 `guardrail_span()`으로 감싸집니다
--   핸드오프는 `handoff_span()`으로 감싸집니다
--   오디오 입력(음성-텍스트 변환)은 `transcription_span()`으로 감싸집니다
--   오디오 출력(텍스트-음성 변환)은 `speech_span()`으로 감싸집니다
--   관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식 관계로 중첩될 수 있습니다
+-   전체 `Runner.{run, run_sync, run_streamed}()`가 `trace()`로 래핑됩니다.
+-   에이전트가 실행될 때마다 `agent_span()`으로 래핑됩니다
+-   LLM 생성은 `generation_span()`으로 래핑됩니다
+-   함수 도구 호출은 각각 `function_span()`으로 래핑됩니다
+-   가드레일은 `guardrail_span()`으로 래핑됩니다
+-   핸드오프는 `handoff_span()`으로 래핑됩니다
+-   오디오 입력(음성-텍스트 변환)은 `transcription_span()`으로 래핑됩니다
+-   오디오 출력(텍스트-음성 변환)은 `speech_span()`으로 래핑됩니다
+-   관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식 관계로 배치될 수 있습니다
 
-기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하는 경우 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]를 사용해 이름 및 기타 속성을 구성할 수도 있습니다.
+기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하는 경우 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]로 이름과 기타 속성을 구성할 수도 있습니다.
 
-또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정하여 다른 대상에 트레이스를 전송할 수 있습니다(대체 대상 또는 보조 대상으로).
+또한 트레이스를 다른 대상으로 보내도록 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정할 수 있습니다(대체 대상 또는 보조 대상으로).
 
 ## 장기 실행 워커와 즉시 내보내기
 
-기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내며, 메모리 내 큐가 크기 임계값에 도달하면 더 빨리 내보냅니다. 또한 프로세스가 종료될 때 최종 플러시를 수행합니다. Celery, RQ, Dramatiq 또는 FastAPI 백그라운드 작업과 같은 장기 실행 워커에서는 일반적으로 추가 코드 없이도 트레이스가 자동으로 내보내지지만, 각 작업이 끝난 직후 Traces dashboard에 바로 표시되지는 않을 수 있습니다.
+기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내거나, 메모리 내 큐가 크기 트리거에 도달하면 더 빨리 내보내며,
+프로세스가 종료될 때 최종 flush도 수행합니다. Celery,
+RQ, Dramatiq 또는 FastAPI 백그라운드 작업과 같은 장기 실행 워커에서는 일반적으로 추가 코드 없이 트레이스가 자동으로 내보내지지만,
+각 작업이 완료된 직후 Traces 대시보드에 표시되지 않을 수 있습니다.
 
-작업 단위가 끝날 때 즉시 전달을 보장해야 한다면, 트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출하세요.
+작업 단위가 끝날 때 즉시 전달을 보장해야 하는 경우,
+트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출합니다.
 
 ```python
 from agents import Runner, flush_traces, trace
@@ -89,11 +93,13 @@ async def run(prompt: str, background_tasks: BackgroundTasks):
     return {"status": "queued"}
 ```
 
-[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이 내보내질 때까지 블로킹되므로, 부분적으로만 구성된 트레이스를 플러시하지 않도록 `trace()`가 닫힌 후 호출해야 합니다. 기본 내보내기 지연이 허용 가능하다면 이 호출은 생략할 수 있습니다.
+[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이
+내보내질 때까지 차단하므로, 부분적으로 구성된 트레이스를 flush하지 않도록 `trace()`가 닫힌 후 호출합니다. 기본 내보내기 지연 시간이 허용 가능한 경우
+이 호출을 생략할 수 있습니다.
 
 ## 상위 수준 트레이스
 
-경우에 따라 여러 `run()` 호출을 하나의 단일 트레이스에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다.
+때로는 여러 `run()` 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 전체 코드를 `trace()`로 래핑하면 이를 수행할 수 있습니다.
 
 ```python
 from agents import Agent, Runner, trace
@@ -108,20 +114,20 @@ async def main():
         print(f"Rating: {second_result.final_output}")
 ```
 
-1. 두 번의 `Runner.run` 호출이 `with trace()`로 감싸져 있으므로, 개별 실행이 각각 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다.
+1. `Runner.run`에 대한 두 호출이 `with trace()`로 래핑되어 있으므로, 개별 실행은 두 개의 트레이스를 만드는 대신 전체 트레이스의 일부가 됩니다.
 
 ## 트레이스 생성
 
-[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작되고 종료되어야 하며, 이를 위한 두 가지 방법이 있습니다:
+[`trace()`][agents.tracing.trace] 함수를 사용하여 트레이스를 만들 수 있습니다. 트레이스는 시작되고 종료되어야 합니다. 이를 수행하는 방법은 두 가지입니다.
 
-1. **권장 방식**: `with trace(...) as my_trace`처럼 트레이스를 컨텍스트 매니저로 사용합니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작되고 종료됩니다.
+1. **권장**: 트레이스를 컨텍스트 매니저로 사용합니다. 즉, `with trace(...) as my_trace`를 사용합니다. 그러면 적절한 시점에 트레이스가 자동으로 시작되고 종료됩니다.
 2. [`trace.start()`][agents.tracing.Trace.start] 및 [`trace.finish()`][agents.tracing.Trace.finish]를 수동으로 호출할 수도 있습니다.
 
-현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 이는 동시성 환경에서도 자동으로 동작함을 의미합니다. 트레이스를 수동으로 시작/종료하는 경우, 현재 트레이스를 갱신하기 위해 `start()`/`finish()`에 `mark_as_current` 및 `reset_current`를 전달해야 합니다.
+현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 즉, 동시성 환경에서도 자동으로 작동합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 업데이트하려면 `start()`/`finish()`에 `mark_as_current` 및 `reset_current`를 전달해야 합니다.
 
 ## 스팬 생성
 
-다양한 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로는 스팬을 수동으로 생성할 필요가 없습니다. 사용자 정의 스팬 정보를 추적하기 위해 [`custom_span()`][agents.tracing.custom_span] 함수를 사용할 수 있습니다.
+다양한 [`*_span()`][agents.tracing.create] 메서드를 사용하여 스팬을 만들 수 있습니다. 일반적으로 스팬을 수동으로 만들 필요는 없습니다. 사용자 지정 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수가 제공됩니다.
 
 스팬은 자동으로 현재 트레이스의 일부가 되며, Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다.
 
@@ -129,27 +135,28 @@ async def main():
 
 일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다.
 
-`generation_span()`은 LLM 생성의 입력/출력을 저장하고, `function_span()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로, [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 통해 해당 데이터의 캡처를 비활성화할 수 있습니다.
+`generation_span()`은 LLM 생성의 입력/출력을 저장하고, `function_span()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 통해 해당 데이터 캡처를 비활성화할 수 있습니다.
 
-마찬가지로 오디오 스팬은 기본적으로 입력 및 출력 오디오에 대한 base64 인코딩 PCM 데이터를 포함합니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]를 구성하여 이 오디오 데이터의 캡처를 비활성화할 수 있습니다.
+마찬가지로 오디오 스팬은 기본적으로 입력 및 출력 오디오에 대한 base64 인코딩 PCM 데이터를 포함합니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]를 구성하여 이 오디오 데이터 캡처를 비활성화할 수 있습니다.
 
-기본적으로 `trace_include_sensitive_data`는 `True`입니다. 앱을 실행하기 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`으로 내보내 코드 변경 없이 기본값을 설정할 수 있습니다.
+기본적으로 `trace_include_sensitive_data`는 `True`입니다. 앱을 실행하기 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`로 내보내면 코드 없이 기본값을 설정할 수 있습니다.
 
-## 사용자 정의 트레이싱 프로세서
+## 사용자 지정 트레이싱 프로세서
 
-트레이싱의 상위 수준 아키텍처는 다음과 같습니다:
+트레이싱의 상위 수준 아키텍처는 다음과 같습니다.
 
--   초기화 시 트레이스 생성을 담당하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성합니다
--   `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성하며, 이 프로세서는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하고, `BackendSpanExporter`는 스팬과 트레이스를 OpenAI 백엔드로 배치 단위로 내보냅니다
+-   초기화 시, 트레이스 생성을 담당하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성합니다.
+-   `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성합니다. 이 프로세서는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 보내며, 이 익스포터는 스팬과 트레이스를 배치로 OpenAI 백엔드에 내보냅니다.
 
-이 기본 설정을 사용자 정의하여 대체 또는 추가 백엔드로 트레이스를 보내거나 내보내기 동작을 수정하려면 두 가지 옵션이 있습니다:
+트레이스를 대체 또는 추가 백엔드로 보내거나 익스포터 동작을 수정하도록 이 기본 설정을 사용자 지정하려면 두 가지 옵션이 있습니다.
 
-1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 준비된 트레이스와 스팬을 전달받는 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 트레이스를 OpenAI 백엔드로 전송하는 것에 더해 자체 처리를 수행할 수 있습니다.
-2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 사용자의 트레이스 프로세서로 **대체**할 수 있습니다. 이 경우 `TracingProcessor`를 포함하지 않으면 트레이스는 OpenAI 백엔드로 전송되지 않습니다.
+1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 트레이스와 스팬이 준비되는 대로 수신할 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 트레이스를 보내는 것에 더해 자체 처리를 수행할 수 있습니다.
+2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 자체 트레이스 프로세서로 **교체**할 수 있습니다. 즉, 이를 수행하는 `TracingProcessor`를 포함하지 않는 한 트레이스는 OpenAI 백엔드로 전송되지 않습니다.
 
-## 비 OpenAI 모델과의 트레이싱
 
-트레이싱을 비활성화하지 않고도 OpenAI Traces dashboard에서 무료 트레이싱을 활성화하기 위해 비 OpenAI 모델에 OpenAI API 키를 사용할 수 있습니다. 어댑터 선택 및 설정 시 유의사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요.
+## 비 OpenAI 모델을 사용한 트레이싱
+
+비 OpenAI 모델에서 OpenAI API 키를 사용하면 트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. 어댑터 선택 및 설정 시 주의 사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참조하세요.
 
 ```python
 import os
@@ -170,7 +177,7 @@ agent = Agent(
 )
 ```
 
-단일 실행에 대해서만 다른 트레이싱 키가 필요하다면, 전역 exporter를 변경하는 대신 `RunConfig`를 통해 전달하세요.
+단일 실행에 대해서만 다른 트레이싱 키가 필요한 경우, 전역 익스포터를 변경하는 대신 `RunConfig`를 통해 전달합니다.
 
 ```python
 from agents import Runner, RunConfig
@@ -183,7 +190,8 @@ await Runner.run(
 ```
 
 ## 추가 참고 사항
-- Openai Traces dashboard에서 무료 트레이스를 확인하세요
+- Openai Traces 대시보드에서 무료 트레이스를 확인합니다.
+
 
 ## 에코시스템 통합
 
@@ -194,8 +202,8 @@ await Runner.run(
 -   [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
 -   [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
 -   [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents)
--   [MLflow (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
--   [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
+-   [MLflow (자체 호스팅/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
+-   [MLflow (Databricks 호스팅)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
 -   [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)
 -   [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents)
 -   [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)

docs/ko/usage.md

@@ -2,9 +2,9 @@
 search:
   exclude: true
 ---
-# 사용
+# 사용량
 
-Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 확인하여 비용 모니터링, 제한 적용, 분석 기록에 활용할 수 있습니다.
+Agents SDK는 모든 실행에 대한 토큰 사용량을 자동으로 추적합니다. 실행 컨텍스트에서 이를 접근할 수 있으며, 비용 모니터링, 한도 적용, 분석 기록에 사용할 수 있습니다.
 
 ## 추적 항목
 
@@ -19,7 +19,7 @@ Agents SDK는 모든 실행에 대해 토큰 사용량을 자동으로 추적합
 
 ## 실행에서 사용량 접근
 
-`Runner.run(...)` 이후 `result.context_wrapper.usage`를 통해 사용량에 접근할 수 있습니다.
+`Runner.run(...)` 이후에는 `result.context_wrapper.usage`를 통해 사용량에 접근합니다.
 
 ```python
 result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -31,20 +31,20 @@ print("Output tokens:", usage.output_tokens)
 print("Total tokens:", usage.total_tokens)
 ```
 
-사용량은 실행 중 발생한 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다.
+사용량은 실행 중의 모든 모델 호출(도구 호출 및 핸드오프 포함)에 걸쳐 집계됩니다.
 
 ### 서드파티 어댑터에서 사용량 활성화
 
-사용량 보고는 서드파티 어댑터와 제공자 백엔드에 따라 달라집니다. 어댑터 기반 모델을 사용하고 정확한 `result.context_wrapper.usage` 값이 필요하다면 다음을 확인하세요:
+사용량 보고는 서드파티 어댑터와 제공자 백엔드에 따라 다릅니다. 어댑터 기반 모델에 의존하고 정확한 `result.context_wrapper.usage` 값이 필요한 경우:
 
-- `AnyLLMModel`에서는 업스트림 제공자가 사용량을 반환하면 자동으로 전파됩니다. 스트리밍 Chat Completions 백엔드의 경우, 사용량 청크가 전송되기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다
-- `LitellmModel`에서는 일부 제공자 백엔드가 기본적으로 사용량을 보고하지 않으므로, `ModelSettings(include_usage=True)`가 자주 필요합니다
+- `AnyLLMModel`에서는 업스트림 제공자가 사용량을 반환하면 사용량이 자동으로 전달됩니다. 스트리밍 Chat Completions 백엔드의 경우 사용량 청크가 방출되기 전에 `ModelSettings(include_usage=True)`가 필요할 수 있습니다.
+- `LitellmModel`에서는 일부 제공자 백엔드가 기본적으로 사용량을 보고하지 않으므로, `ModelSettings(include_usage=True)`가 필요한 경우가 많습니다.
 
-모델 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션에서 어댑터별 참고 사항을 확인하고, 배포 예정인 정확한 제공자 백엔드를 검증하세요.
+Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션에서 어댑터별 참고 사항을 검토하고, 배포하려는 정확한 제공자 백엔드를 검증하세요.
 
 ## 요청별 사용량 추적
 
-SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하므로, 상세한 비용 계산과 컨텍스트 윈도 소비량 모니터링에 유용합니다.
+SDK는 `request_usage_entries`에서 각 API 요청의 사용량을 자동으로 추적하므로, 자세한 비용 계산과 컨텍스트 창 소비 모니터링에 유용합니다.
 
 ```python
 result = await Runner.run(agent, "What's the weather in Tokyo?")
@@ -55,7 +55,7 @@ for i, request in enumerate(result.context_wrapper.usage.request_usage_entries):
 
 ## 세션에서 사용량 접근
 
-`Session`(예: `SQLiteSession`)을 사용할 때 `Runner.run(...)`의 각 호출은 해당 실행에 대한 사용량을 반환합니다. 세션은 컨텍스트를 위해 대화 이력을 유지하지만, 각 실행의 사용량은 서로 독립적입니다.
+`Session`(예: `SQLiteSession`)을 사용하는 경우 `Runner.run(...)`을 호출할 때마다 해당 특정 실행의 사용량이 반환됩니다. 세션은 컨텍스트를 위해 대화 기록을 유지하지만, 각 실행의 사용량은 독립적입니다.
 
 ```python
 session = SQLiteSession("my_conversation")
@@ -67,11 +67,11 @@ second = await Runner.run(agent, "Can you elaborate?", session=session)
 print(second.context_wrapper.usage.total_tokens)  # Usage for second run
 ```
 
-세션은 실행 간 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출에서 반환되는 사용량 지표는 해당 실행만을 나타냅니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 주입될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다.
+세션은 실행 간 대화 컨텍스트를 보존하지만, 각 `Runner.run()` 호출이 반환하는 사용량 지표는 해당 특정 실행만을 나타냅니다. 세션에서는 이전 메시지가 각 실행의 입력으로 다시 제공될 수 있으며, 이는 이후 턴의 입력 토큰 수에 영향을 줍니다.
 
-## 훅에서 사용량 활용
+## 훅에서 사용량 사용
 
-`RunHooks`를 사용하는 경우, 각 훅에 전달되는 `context` 객체에 `usage`가 포함됩니다. 이를 통해 주요 라이프사이클 시점에 사용량을 기록할 수 있습니다.
+`RunHooks`를 사용하는 경우 각 훅에 전달되는 `context` 객체에는 `usage`가 포함됩니다. 이를 통해 주요 수명 주기 시점에 사용량을 기록할 수 있습니다.
 
 ```python
 class MyHooks(RunHooks):
@@ -80,11 +80,11 @@ class MyHooks(RunHooks):
         print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens")
 ```
 
-## API 레퍼런스
+## API 참조
 
-자세한 API 문서는 다음을 참고하세요:
+자세한 API 문서는 다음을 참조하세요.
 
 -   [`Usage`][agents.usage.Usage] - 사용량 추적 데이터 구조
 -   [`RequestUsage`][agents.usage.RequestUsage] - 요청별 사용량 세부 정보
 -   [`RunContextWrapper`][agents.run.RunContextWrapper] - 실행 컨텍스트에서 사용량 접근
--   [`RunHooks`][agents.run.RunHooks] - 사용량 추적 라이프사이클에 훅 연결
+-   [`RunHooks`][agents.run.RunHooks] - 사용량 추적 수명 주기에 훅 연결

docs/ko/visualization.md

@@ -4,11 +4,11 @@ search:
 ---
 # 에이전트 시각화
 
-에이전트 시각화를 사용하면 **Graphviz**를 통해 에이전트와 그 관계를 구조화된 그래픽 표현으로 생성할 수 있습니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다.
+에이전트 시각화를 사용하면 **Graphviz**를 이용해 에이전트와 그 관계를 구조화된 그래픽 표현으로 생성할 수 있습니다. 이는 애플리케이션 내에서 에이전트, 도구, 핸드오프가 어떻게 상호작용하는지 이해하는 데 유용합니다.
 
 ## 설치
 
-선택 사항인 `viz` 의존성 그룹을 설치하세요:
+선택적 `viz` 의존성 그룹을 설치합니다.
 
 ```bash
 pip install "openai-agents[viz]"
@@ -16,12 +16,12 @@ pip install "openai-agents[viz]"
 
 ## 그래프 생성
 
-`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 방향 그래프를 만듭니다:
+`draw_graph` 함수를 사용해 에이전트 시각화를 생성할 수 있습니다. 이 함수는 다음과 같은 유향 그래프를 만듭니다.
 
-- **에이전트**는 노란색 상자로 표시됩니다
-- **MCP 서버**는 회색 상자로 표시됩니다
-- **도구**는 초록색 타원으로 표시됩니다
-- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향성 간선으로 표시됩니다
+- **에이전트**는 노란색 박스로 표시됩니다.
+- **MCP 서버**는 회색 박스로 표시됩니다.
+- **도구**는 초록색 타원으로 표시됩니다.
+- **핸드오프**는 한 에이전트에서 다른 에이전트로 향하는 방향성 엣지로 표시됩니다.
 
 ### 사용 예시
 
@@ -67,40 +67,43 @@ triage_agent = Agent(
 draw_graph(triage_agent)
 ```
 
-![Agent Graph](../assets/images/graph.png)
+![에이전트 그래프](../assets/images/graph.png)
+
+이렇게 하면 **트리아지 에이전트**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프가 생성됩니다.
 
-이렇게 하면 **triage agent**의 구조와 하위 에이전트 및 도구와의 연결을 시각적으로 나타내는 그래프가 생성됩니다.
 
 ## 시각화 이해
 
-생성된 그래프에는 다음이 포함됩니다:
+생성된 그래프에는 다음이 포함됩니다.
 
-- 진입 지점을 나타내는 **시작 노드** (`__start__`)
-- 노란색 채움의 **직사각형**으로 표시된 에이전트
-- 초록색 채움의 **타원**으로 표시된 도구
-- 회색 채움의 **직사각형**으로 표시된 MCP 서버
-- 상호작용을 나타내는 방향성 간선:
-  - 에이전트 간 핸드오프를 위한 **실선 화살표**
-  - 도구 호출을 위한 **점선 화살표**
-  - MCP 서버 호출을 위한 **파선 화살표**
-- 실행이 종료되는 지점을 나타내는 **종료 노드** (`__end__`)
+- 진입점을 나타내는 **시작 노드**(`__start__`)
+- 노란색으로 채워진 **직사각형**으로 표시되는 에이전트
+- 초록색으로 채워진 **타원**으로 표시되는 도구
+- 회색으로 채워진 **직사각형**으로 표시되는 MCP 서버
+- 상호작용을 나타내는 방향성 엣지:
+  - 에이전트 간 핸드오프를 나타내는 **실선 화살표**
+  - 도구 호출을 나타내는 **점선 화살표**
+  - MCP 서버 호출을 나타내는 **파선 화살표**
+- 실행이 종료되는 위치를 나타내는 **종료 노드**(`__end__`)
 
-**참고:** MCP 서버는 `agents` 패키지의 최신 버전에서 렌더링됩니다(**v0.2.8**에서 확인됨). 시각화에서 MCP 상자가 보이지 않으면 최신 릴리스로 업그레이드하세요.
+**참고:** MCP 서버는 최신 버전의
+`agents` 패키지에서 렌더링됩니다(**v0.2.8**에서 확인됨). 시각화에서 MCP 박스가
+보이지 않으면 최신 릴리스로 업그레이드하세요.
 
 ## 그래프 사용자 지정
 
 ### 그래프 표시
-기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에서 표시하려면 다음과 같이 작성하세요:
+기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 그래프를 별도 창에 표시하려면 다음과 같이 작성합니다.
 
 ```python
 draw_graph(triage_agent).view()
 ```
 
 ### 그래프 저장
-기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일명을 지정하세요:
+기본적으로 `draw_graph`는 그래프를 인라인으로 표시합니다. 파일로 저장하려면 파일 이름을 지정합니다.
 
 ```python
 draw_graph(triage_agent, filename="agent_graph")
 ```
 
-이렇게 하면 작업 디렉터리에 `agent_graph.png`가 생성됩니다.
+그러면 작업 디렉터리에 `agent_graph.png`가 생성됩니다.

docs/ko/voice/pipeline.md

@@ -2,9 +2,9 @@
 search:
   exclude: true
 ---
-# 파이프라인과 워크플로
+# 파이프라인 및 워크플로
 
-[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 워크플로를 음성 앱으로 쉽게 전환할 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 시점 감지, 적절한 시점의 워크플로 호출, 그리고 워크플로 출력의 오디오 변환까지 처리합니다.
+[`VoicePipeline`][agents.voice.pipeline.VoicePipeline]은 에이전트 기반 워크플로를 음성 앱으로 쉽게 전환할 수 있게 해주는 클래스입니다. 실행할 워크플로를 전달하면, 파이프라인이 입력 오디오 전사, 오디오 종료 시점 감지, 적절한 시점의 워크플로 호출, 워크플로 출력의 오디오 변환을 처리합니다.
 
 ```mermaid
 graph LR
@@ -34,29 +34,29 @@ graph LR
 
 ## 파이프라인 구성
 
-파이프라인을 생성할 때 몇 가지를 설정할 수 있습니다:
+파이프라인을 만들 때 몇 가지를 설정할 수 있습니다.
 
-1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]: 새 오디오가 전사될 때마다 실행되는 코드입니다
+1. [`workflow`][agents.voice.workflow.VoiceWorkflowBase]: 새 오디오가 전사될 때마다 실행되는 코드
 2. 사용되는 [`speech-to-text`][agents.voice.model.STTModel] 및 [`text-to-speech`][agents.voice.model.TTSModel] 모델
-3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 다음과 같은 항목을 구성할 수 있습니다:
+3. [`config`][agents.voice.pipeline_config.VoicePipelineConfig]: 다음과 같은 항목을 구성할 수 있습니다.
     - 모델 이름을 모델에 매핑할 수 있는 모델 제공자
-    - 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, trace ID 등 트레이싱 관련 설정
-    - 프롬프트, 언어, 사용되는 데이터 유형 등 TTS 및 STT 모델의 설정
+    - 트레이싱 비활성화 여부, 오디오 파일 업로드 여부, 워크플로 이름, 트레이스 ID 등을 포함한 트레이싱
+    - 프롬프트, 언어, 사용되는 데이터 타입 등 TTS 및 STT 모델 설정
 
 ## 파이프라인 실행
 
-[`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드를 통해 파이프라인을 실행할 수 있으며, 두 가지 형태의 오디오 입력을 전달할 수 있습니다:
+[`run()`][agents.voice.pipeline.VoicePipeline.run] 메서드로 파이프라인을 실행할 수 있으며, 오디오 입력은 두 가지 형태로 전달할 수 있습니다.
 
-1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사본이 있을 때 사용하며, 그에 대한 결과만 생성하려는 경우에 적합합니다. 이는 화자가 말하기를 마쳤는지 감지할 필요가 없는 경우에 유용합니다. 예를 들어, 미리 녹음된 오디오가 있거나 사용자가 말을 마쳤는지 명확한 push-to-talk 앱에서 사용할 수 있습니다.
-2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 말하기를 마쳤는지 감지해야 할 수 있을 때 사용합니다. 감지되는 대로 오디오 청크를 전달할 수 있으며, 음성 파이프라인이 "activity detection"이라는 과정을 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다.
+1. [`AudioInput`][agents.voice.input.AudioInput]은 전체 오디오 전사가 있고 그에 대한 결과만 생성하려는 경우에 사용됩니다. 화자가 말하기를 마쳤는지 감지할 필요가 없는 경우에 유용합니다. 예를 들어, 사전 녹음된 오디오가 있거나 사용자가 말하기를 마친 시점이 명확한 push-to-talk 앱에서 사용할 수 있습니다.
+2. [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]은 사용자가 말하기를 마쳤는지 감지해야 할 수 있는 경우에 사용됩니다. 감지되는 즉시 오디오 청크를 푸시할 수 있으며, 음성 파이프라인은 "활동 감지(activity detection)"라는 프로세스를 통해 적절한 시점에 에이전트 워크플로를 자동으로 실행합니다.
 
 ## 결과
 
-음성 파이프라인 실행 결과는 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]입니다. 이는 이벤트가 발생하는 대로 스트리밍할 수 있게 해주는 객체입니다. [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent]에는 몇 가지 종류가 있습니다:
+음성 파이프라인 실행 결과는 [`StreamedAudioResult`][agents.voice.result.StreamedAudioResult]입니다. 이는 이벤트가 발생할 때마다 스트리밍할 수 있게 해주는 객체입니다. [`VoiceStreamEvent`][agents.voice.events.VoiceStreamEvent]에는 다음을 포함한 몇 가지 종류가 있습니다.
 
-1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]: 오디오 청크를 포함합니다
-2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]: 턴 시작 또는 종료와 같은 라이프사이클 이벤트를 알려줍니다
-3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]: 오류 이벤트입니다
+1. [`VoiceStreamEventAudio`][agents.voice.events.VoiceStreamEventAudio]: 오디오 청크를 포함합니다.
+2. [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle]: 턴 시작 또는 종료와 같은 수명 주기 이벤트를 알려줍니다.
+3. [`VoiceStreamEventError`][agents.voice.events.VoiceStreamEventError]: 오류 이벤트입니다.
 
 ```python
 
@@ -76,4 +76,4 @@ async for event in result.stream():
 
 ### 인터럽션(중단 처리)
 
-현재 Agents SDK는 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]에 대해 내장된 인터럽션(중단 처리) 기능을 제공하지 않습니다. 대신 감지된 각 턴마다 워크플로의 별도 실행이 트리거됩니다. 애플리케이션 내부에서 인터럽션(중단 처리)을 처리하려면 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 이벤트를 수신하면 됩니다. `turn_started`는 새 턴이 전사되었고 처리가 시작됨을 나타냅니다. `turn_ended`는 해당 턴에 대한 모든 오디오가 전송된 후 트리거됩니다. 이러한 이벤트를 사용하여 모델이 턴을 시작할 때 화자의 마이크를 음소거하고, 한 턴과 관련된 모든 오디오를 플러시한 후 다시 음소거를 해제할 수 있습니다.
+Agents SDK는 현재 [`StreamedAudioInput`][agents.voice.input.StreamedAudioInput]에 대해 기본 제공 인터럽션(중단 처리) 처리를 제공하지 않습니다. 대신 감지된 각 턴마다 워크플로의 별도 실행을 트리거합니다. 애플리케이션 내부에서 인터럽션(중단 처리)을 처리하려면 [`VoiceStreamEventLifecycle`][agents.voice.events.VoiceStreamEventLifecycle] 이벤트를 수신할 수 있습니다. `turn_started`는 새 턴이 전사되어 처리가 시작되고 있음을 나타냅니다. `turn_ended`는 해당 턴에 대한 모든 오디오가 전달된 후 트리거됩니다. 이러한 이벤트를 사용하여 모델이 턴을 시작할 때 화자의 마이크를 음소거하고, 해당 턴과 관련된 모든 오디오를 플러시한 뒤 음소거를 해제할 수 있습니다.

docs/ko/voice/quickstart.md

@@ -4,9 +4,9 @@ search:
 ---
 # 빠른 시작
 
-## 사전 요구 사항
+## 사전 준비 사항
 
-Agents SDK에 대한 기본 [빠른 시작 지침](../quickstart.md)을 따르고 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택적 음성 종속성을 설치하세요.
+Agents SDK의 기본 [빠른 시작 지침](../quickstart.md)을 따르고 가상 환경을 설정했는지 확인하세요. 그런 다음 SDK에서 선택 사항인 음성 의존성을 설치하세요.
 
 ```bash
 pip install 'openai-agents[voice]'
@@ -14,11 +14,11 @@ pip install 'openai-agents[voice]'
 
 ## 개념
 
-알아야 할 주요 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다.
+알아두어야 할 주요 개념은 [`VoicePipeline`][agents.voice.pipeline.VoicePipeline]이며, 이는 3단계 프로세스입니다.
 
-1. 음성을 텍스트로 변환하기 위해 speech-to-text 모델을 실행합니다.
-2. 결과를 생성하기 위해 일반적으로 에이전트형 워크플로인 코드를 실행합니다.
-3. 결과 텍스트를 다시 음성으로 변환하기 위해 text-to-speech 모델을 실행합니다.
+1. 음성-텍스트 변환 모델을 실행하여 오디오를 텍스트로 변환합니다.
+2. 일반적으로 에이전트형 워크플로인 코드를 실행하여 결과를 생성합니다.
+3. 텍스트-음성 변환 모델을 실행하여 결과 텍스트를 다시 오디오로 변환합니다.
 
 ```mermaid
 graph LR
@@ -48,7 +48,7 @@ graph LR
 
 ## 에이전트
 
-먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 몇 개의 에이전트, 핸드오프, 도구를 사용하겠습니다.
+먼저 몇 가지 에이전트를 설정해 보겠습니다. 이 SDK로 에이전트를 만들어 본 적이 있다면 익숙하게 느껴질 것입니다. 에이전트 몇 개, 핸드오프 하나, 도구 하나를 사용합니다.
 
 ```python
 import asyncio
@@ -195,4 +195,4 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-이 예제를 실행하면 에이전트가 사용자에게 말을 합니다! 직접 에이전트에게 말해 볼 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인하세요.
+이 예제를 실행하면 에이전트가 사용자에게 말을 걸 것입니다! 에이전트와 직접 대화할 수 있는 데모는 [examples/voice/static](https://github.com/openai/openai-agents-python/tree/main/examples/voice/static)의 예제를 확인하세요.

docs/ko/voice/tracing.md

@@ -4,15 +4,15 @@ search:
 ---
 # 트레이싱
 
-[에이전트가 트레이싱되는](../tracing.md) 방식과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다.
+[에이전트가 트레이싱되는 방식](../tracing.md)과 마찬가지로, 음성 파이프라인도 자동으로 트레이싱됩니다.
 
-기본적인 트레이싱 정보는 위의 트레이싱 문서를 참고하시면 되며, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다.
+기본적인 트레이싱 정보는 위의 트레이싱 문서를 참고할 수 있으며, 추가로 [`VoicePipelineConfig`][agents.voice.pipeline_config.VoicePipelineConfig]를 통해 파이프라인의 트레이싱을 구성할 수 있습니다.
 
-트레이싱 관련 핵심 필드는 다음과 같습니다:
+트레이싱 관련 주요 필드는 다음과 같습니다.
 
--   [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱을 비활성화할지 여부를 제어합니다. 기본값은 트레이싱 활성화입니다.
--   [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 오디오 전사본과 같은 잠재적으로 민감한 데이터를 트레이스에 포함할지 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며, Workflow 내부에서 발생하는 모든 것에는 적용되지 않습니다.
+-   [`tracing_disabled`][agents.voice.pipeline_config.VoicePipelineConfig.tracing_disabled]: 트레이싱을 비활성화할지 여부를 제어합니다. 기본적으로 트레이싱은 활성화되어 있습니다.
+-   [`trace_include_sensitive_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_data]: 트레이스에 오디오 전사와 같은 잠재적으로 민감한 데이터를 포함할지 여부를 제어합니다. 이는 음성 파이프라인에만 해당하며, Workflow 내부에서 발생하는 다른 작업에는 적용되지 않습니다.
 -   [`trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]: 트레이스에 오디오 데이터를 포함할지 여부를 제어합니다.
 -   [`workflow_name`][agents.voice.pipeline_config.VoicePipelineConfig.workflow_name]: 트레이스 워크플로의 이름입니다.
--   [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 트레이스의 `group_id`로, 여러 트레이스를 연결할 수 있습니다.
+-   [`group_id`][agents.voice.pipeline_config.VoicePipelineConfig.group_id]: 여러 트레이스를 연결할 수 있게 해 주는 트레이스의 `group_id`입니다.
 -   [`trace_metadata`][agents.voice.pipeline_config.VoicePipelineConfig.trace_metadata]: 트레이스에 포함할 추가 메타데이터입니다.

docs/mcp.md

@@ -40,6 +40,8 @@ agent = Agent(
         # If None, MCP tool failures are raised as exceptions instead of
         # returning model-visible error text.
         "failure_error_function": None,
+        # Prefix local MCP tool names with their server name.
+        "include_server_in_tool_names": True,
     },
 )
 ```
@@ -50,6 +52,7 @@ Notes:
 - `failure_error_function` controls how MCP tool call failures are surfaced to the model.
 - When `failure_error_function` is unset, the SDK uses the default tool error formatter.
 - Server-level `failure_error_function` overrides `Agent.mcp_config["failure_error_function"]` for that server.
+- `include_server_in_tool_names` is opt-in. When enabled, each local MCP tool is exposed to the model with a deterministic server-prefixed name, which helps avoid collisions when multiple MCP servers publish tools with the same name. Generated names are ASCII-safe, stay within the function-tool name length limit, and avoid existing local function tool and enabled handoff names on the same agent. The SDK still invokes the original MCP tool name on the original server.
 
 ## Shared patterns across transports
 
@@ -82,19 +85,23 @@ from agents import Agent, HostedMCPTool, Runner
 async def main() -> None:
     agent = Agent(
         name="Assistant",
+        instructions="Use the DeepWiki hosted MCP server to inspect openai/openai-agents-python.",
         tools=[
             HostedMCPTool(
                 tool_config={
                     "type": "mcp",
-                    "server_label": "gitmcp",
-                    "server_url": "https://gitmcp.io/openai/codex",
+                    "server_label": "deepwiki",
+                    "server_url": "https://mcp.deepwiki.com/mcp",
                     "require_approval": "never",
                 }
             )
         ],
     )
 
-    result = await Runner.run(agent, "Which language is this repository written in?")
+    result = await Runner.run(
+        agent,
+        "Which language is the repository openai/openai-agents-python written in?",
+    )
     print(result.final_output)
 
 asyncio.run(main())
@@ -126,7 +133,7 @@ policies. To make the decision inside Python, provide an `on_approval_request` c
 ```python
 from agents import MCPToolApprovalFunctionResult, MCPToolApprovalRequest
 
-SAFE_TOOLS = {"read_project_metadata"}
+SAFE_TOOLS = {"read_wiki_structure", "read_wiki_contents", "ask_question"}
 
 def approve_tool(request: MCPToolApprovalRequest) -> MCPToolApprovalFunctionResult:
     if request.data.name in SAFE_TOOLS:
@@ -139,8 +146,8 @@ agent = Agent(
         HostedMCPTool(
             tool_config={
                 "type": "mcp",
-                "server_label": "gitmcp",
-                "server_url": "https://gitmcp.io/openai/codex",
+                "server_label": "deepwiki",
+                "server_url": "https://mcp.deepwiki.com/mcp",
                 "require_approval": "always",
             },
             on_approval_request=approve_tool,

docs/models/index.md

@@ -22,7 +22,7 @@ Start with the simplest path that fits your setup:
 
 For most OpenAI-only apps, the recommended path is to use string model names with the default OpenAI provider and stay on the Responses model path.
 
-When you don't specify a model when initializing an `Agent`, the default model will be used. The default is currently [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) for compatibility and low latency. If you have access, we recommend setting your agents to [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) for higher quality while keeping explicit `model_settings`.
+When you don't specify a model when initializing an `Agent`, the default model will be used. The default is currently [`gpt-5.4-mini`](https://developers.openai.com/api/docs/models/gpt-5.4-mini) with `reasoning.effort="none"` and `verbosity="low"` for low-latency agent workflows. If you have access, we recommend setting your agents to [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5) for higher quality while keeping explicit `model_settings`.
 
 If you want to switch to other models like [`gpt-5.5`](https://developers.openai.com/api/docs/models/gpt-5.5), there are two ways to configure your agents.
 
@@ -70,7 +70,7 @@ my_agent = Agent(
 )
 ```
 
-For lower latency, using `reasoning.effort="none"` with `gpt-5.5` is recommended. The gpt-4.1 family (including mini and nano variants) also remains a solid choice for building interactive agent apps.
+For lower latency, using `reasoning.effort="none"` with GPT-5 models is recommended.
 
 #### ComputerTool model selection
 
@@ -123,6 +123,8 @@ provider = OpenAIProvider(
     use_responses_websocket=True,
     # Optional; if omitted, OPENAI_WEBSOCKET_BASE_URL is used when set.
     websocket_base_url="wss://your-proxy.example/v1",
+    # Optional low-level websocket keepalive settings.
+    responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
 )
 
 agent = Agent(name="Assistant")
@@ -203,6 +205,7 @@ If you use a custom OpenAI-compatible endpoint or proxy, websocket transport als
 -   This is the Responses API over websocket transport, not the [Realtime API](../realtime/guide.md). It does not apply to Chat Completions or non-OpenAI providers unless they support the Responses websocket `/responses` endpoint.
 -   Install the `websockets` package if it is not already available in your environment.
 -   You can use [`Runner.run_streamed()`][agents.run.Runner.run_streamed] directly after enabling websocket transport. For multi-turn workflows where you want to reuse the same websocket connection across turns (and nested agent-as-tool calls), the [`responses_websocket_session()`][agents.responses_websocket_session] helper is recommended. See the [Running agents](../running_agents.md) guide and [`examples/basic/stream_ws.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/stream_ws.py).
+-   For long reasoning turns or networks with latency spikes, customize websocket keepalive behavior with `responses_websocket_options`. Increase `ping_timeout` to tolerate delayed pong frames, or set `ping_timeout=None` to disable heartbeat timeouts while keeping pings enabled. Prefer HTTP/SSE transport when reliability is more important than websocket latency.
 
 ## Non-OpenAI models
 
@@ -310,6 +313,7 @@ When you are using the OpenAI Responses API, several request fields already have
 - `parallel_tool_calls`: Allow or forbid multiple tool calls in the same turn.
 - `truncation`: Set `"auto"` to let the Responses API drop the oldest conversation items instead of failing when context would overflow.
 - `store`: Control whether the generated response is stored server-side for later retrieval. This matters for follow-up workflows that rely on response IDs, and for session compaction flows that may need to fall back to local input when `store=False`.
+- `context_management`: Configure server-side context handling such as Responses compaction with `compact_threshold`.
 - `prompt_cache_retention`: Keep cached prompt prefixes around longer, for example with `"24h"`.
 - `response_include`: Request richer response payloads such as `web_search_call.action.sources`, `file_search_call.results`, or `reasoning.encrypted_content`.
 - `top_logprobs`: Request top-token logprobs for output text. The SDK also adds `message.output_text.logprobs` automatically.
@@ -325,6 +329,7 @@ research_agent = Agent(
         parallel_tool_calls=False,
         truncation="auto",
         store=True,
+        context_management=[{"type": "compaction", "compact_threshold": 200000}],
         prompt_cache_retention="24h",
         response_include=["web_search_call.action.sources"],
         top_logprobs=5,
@@ -334,11 +339,13 @@ research_agent = Agent(
 
 When you set `store=False`, the Responses API does not keep that response available for later server-side retrieval. This is useful for stateless or zero-data-retention style flows, but it also means features that would otherwise reuse response IDs need to rely on locally managed state instead. For example, [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] switches its default `"auto"` compaction path to input-based compaction when the last response was not stored. See the [Sessions guide](../sessions/index.md#openai-responses-compaction-sessions).
 
+Server-side compaction is different from [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]. `context_management=[{"type": "compaction", "compact_threshold": ...}]` is sent with each Responses API request, and the API can emit compaction items as part of the response when the rendered context crosses the threshold. `OpenAIResponsesCompactionSession` calls the standalone `responses.compact` endpoint between turns and rewrites the local session history.
+
 ### Passing `extra_args`
 
 Use `extra_args` when you need provider-specific or newer request fields that the SDK does not expose directly at the top level yet.
 
-Also, when you use OpenAI's Responses API, [there are a few other optional parameters](https://platform.openai.com/docs/api-reference/responses/create) (e.g., `user`, `service_tier`, and so on). If they are not available at the top level, you can use `extra_args` to pass them as well.
+Also, when you use OpenAI's Responses API, [there are a few other optional parameters](https://platform.openai.com/docs/api-reference/responses/create) (e.g., `user`, `service_tier`, and so on). If they are not available at the top level, you can use `extra_args` to pass them as well. Do not also set the same request field through a direct `ModelSettings` field.
 
 ```python
 from agents import Agent, ModelSettings
@@ -391,7 +398,7 @@ agent = Agent(
 | Field | Type | Notes |
 | --- | --- | --- |
 | `max_retries` | `int | None` | Number of retry attempts allowed after the initial request. |
-| `backoff` | `ModelRetryBackoffSettings | dict | None` | Default delay strategy when the policy retries without returning an explicit delay. |
+| `backoff` | `ModelRetryBackoffSettings | dict | None` | Default delay strategy when the policy retries without returning an explicit delay. `backoff.max_delay` caps this computed backoff delay only. It does not cap explicit delays returned by a policy or retry-after hints. |
 | `policy` | `RetryPolicy | None` | Callback that decides whether to retry. This field is runtime-only and is not serialized. |
 
 </div>
@@ -417,7 +424,7 @@ The SDK exports ready-made helpers on `retry_policies`:
 | `retry_policies.provider_suggested()` | Follows provider retry advice when available. |
 | `retry_policies.network_error()` | Matches transient transport and timeout failures. |
 | `retry_policies.http_status([...])` | Matches selected HTTP status codes. |
-| `retry_policies.retry_after()` | Retries only when a retry-after hint is available, using that delay. |
+| `retry_policies.retry_after()` | Retries only when a retry-after hint is available, using that delay. This helper treats the retry-after value as an explicit policy delay, so `backoff.max_delay` does not cap it. |
 | `retry_policies.any(...)` | Retries when any nested policy opts in. |
 | `retry_policies.all(...)` | Retries only when every nested policy opts in. |
 

docs/realtime/guide.md

@@ -45,14 +45,14 @@ By default, `RealtimeRunner` uses `OpenAIRealtimeWebSocketModel`, so the default
 -   Voice can be configured, but it cannot change after the session has already produced spoken audio.
 -   Instructions, function tools, handoffs, hooks, and output guardrails all still work.
 
-`RealtimeSessionModelSettings` supports both a newer nested `audio` config and older flat aliases. Prefer the nested shape for new code, and start with `gpt-realtime-1.5` for new realtime agents:
+`RealtimeSessionModelSettings` supports both a newer nested `audio` config and older flat aliases. Prefer the nested shape for new code, and start with `gpt-realtime-2` for new realtime agents:
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",
@@ -261,6 +261,12 @@ agent = RealtimeAgent(
 )
 ```
 
+When a realtime output guardrail trips, the session interrupts the active response, forces
+`response.cancel`, emits `guardrail_tripped`, and sends a follow-up user message that names the
+triggered guardrail so the model can produce a replacement response. Your audio player should still
+listen for `audio_interrupted` and stop local playback immediately, because guardrails run on
+debounced transcript text and some audio may already be buffered when the tripwire fires.
+
 ## SIP and telephony
 
 The Python SDK includes a first-class SIP attach flow via [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel].

docs/realtime/quickstart.md

@@ -45,14 +45,14 @@ agent = RealtimeAgent(
 
 ### 3. Configure the runner
 
-Prefer the nested `audio.input` / `audio.output` session settings shape for new code. For new realtime agents, start with `gpt-realtime-1.5`.
+Prefer the nested `audio.input` / `audio.output` session settings shape for new code. For new realtime agents, start with `gpt-realtime-2`.
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-realtime-1.5",
+            "model_name": "gpt-realtime-2",
             "audio": {
                 "input": {
                     "format": "pcm16",

docs/ref/extensions/litellm.md

@@ -1,9 +1,9 @@
 # `LiteLLM Models`
 
 <script>
-  window.location.replace("../third_party_adapters/");
+  window.location.replace("../models/litellm_model/");
 </script>
 
-This page moved to the [Third-party adapters API reference](third_party_adapters.md).
+This page moved to the [LiteLLM model API reference](models/litellm_model.md).
 
 If you are not redirected automatically, use the link above.

docs/ref/sandbox/entries/mounts/providers/box.md

@@ -0,0 +1,3 @@
+# `Box`
+
+::: agents.sandbox.entries.mounts.providers.box

docs/ref/sandbox/session/archive_ops.md

@@ -0,0 +1,3 @@
+# `Archive Ops`
+
+::: agents.sandbox.session.archive_ops

docs/ref/sandbox/session/manifest_ops.md

@@ -0,0 +1,3 @@
+# `Manifest Ops`
+
+::: agents.sandbox.session.manifest_ops