docs: Add Chinese translation for documents

.github/workflows/update-docs.yml

@@ -19,6 +19,7 @@ on:
       - mkdocs.yml
       - '!docs/ja/**'
       - '!docs/ko/**'
+      - '!docs/cn/**'
 
 permissions:
   contents: write

docs/cn/agents.md

@@ -0,0 +1,285 @@
+# 智能体
+
+智能体是应用程序中的核心构建块。一个智能体是一个大型语言模型（LLM），配置了指令和工具。
+
+## 基本配置
+
+智能体最常用到的配置属性包括：
+
+-   `name`: 一个必需的字符串，用于标识你的智能体。
+-   `instructions`: 也称为开发者消息或系统提示。
+-   `model`: 使用哪个LLM，以及可选的 `model_settings` 来配置模型调优参数如temperature、top_p等。
+-   `tools`: 智能体可以用来完成任务的工具。
+
+```python
+from agents import Agent, ModelSettings, function_tool
+
+@function_tool
+def get_weather(city: str) -> str:
+    """returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+agent = Agent(
+    name="Haiku agent",
+    instructions="Always respond in haiku form",
+    model="gpt-5-nano",
+    tools=[get_weather],
+)
+```
+
+## 上下文
+
+智能体对于其 `context` 类型是通用的。上下文是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会传递给每个智能体、工具、交接等，作为智能体运行的依赖项和状态的容器。你可以提供任何Python对象作为上下文。
+
+```python
+@dataclass
+class UserContext:
+    name: str
+    uid: str
+    is_pro_user: bool
+
+    async def fetch_purchases() -> list[Purchase]:
+        return ...
+
+agent = Agent[UserContext](
+    ...,
+)
+```
+
+## 输出类型
+
+默认情况下，智能体会产生纯文本（即 `str`）输出。如果你想让智能体产生特定类型的输出，可以使用 `output_type` 参数。一个常见的选择是使用 [Pydantic](https://docs.pydantic.dev/) 对象，但我们支持任何可以包装在 Pydantic [TypeAdapter](https://docs.pydantic.dev/latest/api/type_adapter/) 中的类型 - 数据类、列表、TypedDict等。
+
+```python
+from pydantic import BaseModel
+from agents import Agent
+
+
+class CalendarEvent(BaseModel):
+    name: str
+    date: str
+    participants: list[str]
+
+agent = Agent(
+    name="Calendar extractor",
+    instructions="Extract calendar events from text",
+    output_type=CalendarEvent,
+)
+```
+
+!!! note
+
+    当你传递一个 `output_type` 时，这告诉模型使用 [结构化输出](https://platform.openai.com/docs/guides/structured-outputs) 而不是常规的纯文本响应。
+
+## 多智能体系统设计模式
+
+设计多智能体系统有很多方法，但我们通常看到两种广泛适用的模式：
+
+1. 管理器（智能体作为工具）：一个中央管理器/编排器调用作为工具公开的专门子智能体，并保持对对话的控制。
+2. 交接：对等智能体将控制权委托给一个专门的智能体，该智能体接管对话。这是分散式的。
+
+更多详细信息请参见[我们的智能体构建实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。
+
+### 管理器（智能体作为工具）
+
+`customer_facing_agent` 处理所有用户交互，并调用作为工具公开的专门子智能体。更多详细信息请参见 [tools](tools.md#agents-as-tools) 文档。
+
+```python
+from agents import Agent
+
+booking_agent = Agent(...)
+refund_agent = Agent(...)
+
+customer_facing_agent = Agent(
+    name="Customer-facing agent",
+    instructions=(
+        "Handle all direct user communication. "
+        "Call the relevant tools when specialized expertise is needed."
+    ),
+    tools=[
+        booking_agent.as_tool(
+            tool_name="booking_expert",
+            tool_description="Handles booking questions and requests.",
+        ),
+        refund_agent.as_tool(
+            tool_name="refund_expert",
+            tool_description="Handles refund questions and requests.",
+        )
+    ],
+)
+```
+
+### 交接
+
+交接是智能体可以委托的子智能体。当发生交接时，被委托的智能体接收对话历史并接管对话。这种模式使得在单一任务上表现出色的模块化专门智能体成为可能。更多详细信息请参见 [handoffs](handoffs.md) 文档。
+
+```python
+from agents import Agent
+
+booking_agent = Agent(...)
+refund_agent = Agent(...)
+
+triage_agent = Agent(
+    name="Triage agent",
+    instructions=(
+        "Help the user with their questions. "
+        "If they ask about booking, hand off to the booking agent. "
+        "If they ask about refunds, hand off to the refund agent."
+    ),
+    handoffs=[booking_agent, refund_agent],
+)
+```
+
+## 动态指令
+
+在大多数情况下，你可以在创建智能体时提供指令。然而，你也可以通过函数提供动态指令。该函数将接收智能体和上下文，并必须返回提示。既可以使用普通函数，也可以使用 `async` 函数。
+
+```python
+def dynamic_instructions(
+    context: RunContextWrapper[UserContext], agent: Agent[UserContext]
+) -> str:
+    return f"The user's name is {context.context.name}. Help them with their questions."
+
+
+agent = Agent[UserContext](
+    name="Triage agent",
+    instructions=dynamic_instructions,
+)
+```
+
+## 生命周期事件（钩子）
+
+有时候，你可能想要观察智能体的生命周期。例如，你可能想要记录事件，或者在某些事件发生时预取数据。你可以通过 `hooks` 属性在智能体的生命周期中设置钩子。子类化 [`AgentHooks`][agents.lifecycle.AgentHooks] 类，并覆盖你感兴趣的方法。
+
+## 护栏
+
+护栏允许你在智能体运行的同时并行运行对用户输入的检查/验证，并在智能体输出产生后对其进行检查/验证。例如，你可以根据相关性筛选用户输入和智能体输出。更多详细信息请参见 [guardrails](guardrails.md) 文档。
+
+## 克隆/复制智能体
+
+通过使用智能体上的 `clone()` 方法，你可以复制智能体，并选择性地更改任何属性。
+
+```python
+pirate_agent = Agent(
+    name="Pirate",
+    instructions="Write like a pirate",
+    model="gpt-4.1",
+)
+
+robot_agent = pirate_agent.clone(
+    name="Robot",
+    instructions="Write like a robot",
+)
+```
+
+## 强制工具使用
+
+提供工具列表并不总是意味着LLM会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制工具使用。有效值包括：
+
+1. `auto`，允许LLM决定是否使用工具。
+2. `required`，要求LLM使用工具（但它可以智能地决定使用哪个工具）。
+3. `none`，要求LLM _不_ 使用工具。
+4. 设置特定字符串，例如 `my_tool`，要求LLM使用该特定工具。
+
+```python
+from agents import Agent, Runner, function_tool, ModelSettings
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+agent = Agent(
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
+    model_settings=ModelSettings(tool_choice="get_weather")
+)
+```
+
+## 工具使用行为
+
+`Agent` 配置中的 `tool_use_behavior` 参数控制如何处理工具输出：
+
+- `"run_llm_again"`: 默认。工具运行后，LLM处理结果以产生最终响应。
+- `"stop_on_first_tool"`: 第一个工具调用的输出用作最终响应，无需进一步的LLM处理。
+
+```python
+from agents import Agent, Runner, function_tool, ModelSettings
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+agent = Agent(
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
+    tool_use_behavior="stop_on_first_tool"
+)
+```
+
+- `StopAtTools(stop_at_tool_names=[...])`: 指定したツールのいずれかが呼び出された場合に停止し、その出力を最終応答として使用します。
+
+```python
+from agents import Agent, Runner, function_tool
+from agents.agent import StopAtTools
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+@function_tool
+def sum_numbers(a: int, b: int) -> int:
+    """Adds two numbers."""
+    return a + b
+
+agent = Agent(
+    name="Stop At Stock Agent",
+    instructions="Get weather or sum numbers.",
+    tools=[get_weather, sum_numbers],
+    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
+)
+```
+
+- `ToolsToFinalOutputFunction`: ツール結果を処理し、停止するか LLM を継続するかを判断するカスタム関数です。
+
+```python
+from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
+from agents.agent import ToolsToFinalOutputResult
+from typing import List, Any
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+def custom_tool_handler(
+    context: RunContextWrapper[Any],
+    tool_results: List[FunctionToolResult]
+) -> ToolsToFinalOutputResult:
+    """Processes tool results to decide final output."""
+    for result in tool_results:
+        if result.output and "sunny" in result.output:
+            return ToolsToFinalOutputResult(
+                is_final_output=True,
+                final_output=f"Final weather: {result.output}"
+            )
+    return ToolsToFinalOutputResult(
+        is_final_output=False,
+        final_output=None
+    )
+
+agent = Agent(
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
+    tool_use_behavior=custom_tool_handler
+)
+```
+
+!!! note
+
+    为了防止无限循环，框架会在工具调用后自动将 `tool_choice` 重置为 "auto"。此行为可通过 [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice] 进行配置。无限循环的发生是因为工具结果被发送给LLM，然后由于 `tool_choice` 导致LLM再次生成工具调用，如此循环往复。

docs/cn/config.md

@@ -0,0 +1,98 @@
+---
+search:
+  exclude: true
+---
+# 配置 SDK
+
+## API 密钥和客户端
+
+默认情况下，SDK 会在导入后立即查找 `OPENAI_API_KEY` 环境变量以进行 LLM 请求和追踪。如果你无法在应用启动前设置该环境变量，可以使用 [set_default_openai_key()][agents.set_default_openai_key] 函数来设置密钥。
+
+```python
+from agents import set_default_openai_key
+
+set_default_openai_key("sk-...")
+```
+
+或者，你也可以配置要使用的 OpenAI 客户端。默认情况下，SDK 会创建一个 `AsyncOpenAI` 实例，使用来自环境变量或上面设置的默认密钥的 API 密钥。你可以通过使用 [set_default_openai_client()][agents.set_default_openai_client] 函数来更改此设置。
+
+```python
+from openai import AsyncOpenAI
+from agents import set_default_openai_client
+
+custom_client = AsyncOpenAI(base_url="...", api_key="...")
+set_default_openai_client(custom_client)
+```
+
+最后，你还可以自定义使用的 OpenAI API。默认情况下，我们使用 OpenAI Responses API。你可以通过使用 [set_default_openai_api()][agents.set_default_openai_api] 函数来覆盖此设置以使用聊天完成 API。
+
+```python
+from agents import set_default_openai_api
+
+set_default_openai_api("chat_completions")
+```
+
+## 追踪
+
+追踪默认启用。它默认使用上面部分中的 OpenAI API 密钥（即环境变量或你设置的默认密钥）。你可以通过使用 [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] 函数来专门设置用于追踪的 API 密钥。
+
+```python
+from agents import set_tracing_export_api_key
+
+set_tracing_export_api_key("sk-...")
+```
+
+你还可以通过使用 [`set_tracing_disabled()`][agents.set_tracing_disabled] 函数来完全禁用追踪。
+
+```python
+from agents import set_tracing_disabled
+
+set_tracing_disabled(True)
+```
+
+## 调试日志记录
+
+SDK 有两个 Python 日志记录器，没有设置任何处理程序。默认情况下，这意味着警告和错误会发送到 `stdout`，但其他日志会被抑制。
+
+要启用详细日志记录，请使用 [`enable_verbose_stdout_logging()`][agents.enable_verbose_stdout_logging] 函数。
+
+```python
+from agents import enable_verbose_stdout_logging
+
+enable_verbose_stdout_logging()
+```
+
+或者，你可以通过添加处理程序、过滤器、格式化程序等来定制日志。你可以在 [Python 日志记录指南](https://docs.python.org/3/howto/logging.html) 中阅读更多内容。
+
+```python
+import logging
+
+logger = logging.getLogger("openai.agents") # 或 openai.agents.tracing 用于追踪日志记录器
+
+# 要使所有日志显示
+logger.setLevel(logging.DEBUG)
+# 要使信息及以上级别显示
+logger.setLevel(logging.INFO)
+# 要使警告及以上级别显示
+logger.setLevel(logging.WARNING)
+# 等等
+
+# 你可以根据需要自定义此设置，但默认情况下这会输出到 `stderr`
+logger.addHandler(logging.StreamHandler())
+```
+
+### 日志中的敏感数据
+
+某些日志可能包含敏感数据（例如，用户数据）。如果你想禁用记录这些数据，请设置以下环境变量。
+
+要禁用记录 LLM 输入和输出：
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
+```
+
+要禁用记录工具输入和输出：
+
+```bash
+export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1
+```