docs: update translated document pages (#2565)

Author: github-actions[bot]

docs/ja/agents.md

@@ -4,19 +4,19 @@ search:
 ---
 # 智能体
 
-智能体是你应用中的核心构建块。智能体是一个大语言模型（LLM），并配置了 instructions 和 tools。
+智能体是应用中的核心构建模块。智能体是一个大语言模型（LLM），并配置了 instructions 和 tools。
 
-## 基本配置
+## 基础配置
 
-你将配置的智能体最常见属性包括：
+你将为智能体配置的最常见属性有：
 
--   `name`: 必需的字符串，用于标识你的智能体。
--   `instructions`: 也称为开发者消息或系统提示词。
--   `model`: 使用哪个 LLM，以及可选的 `model_settings`，用于配置 temperature、top_p 等模型调优参数。
--   `prompt`: 使用 OpenAI 的 Responses API 时，通过 id（以及变量）引用一个提示词模板。
--   `tools`: 智能体可用于完成任务的工具。
--   `mcp_servers`: 为智能体提供工具的 MCP 服务。参见 [MCP 指南](mcp.md)。
--   `reset_tool_choice`: 是否在一次工具调用后重置 `tool_choice`（默认：`True`），以避免工具使用循环。参见[强制使用工具](#forcing-tool-use)。
+-   `name`：用于标识智能体的必填字符串。
+-   `instructions`：也称为开发者消息或系统提示词。
+-   `model`：使用哪个 LLM，以及可选的 `model_settings` 用于配置模型调优参数，如 temperature、top_p 等。
+-   `prompt`：在使用 OpenAI 的 Responses API 时，通过 id（及变量）引用提示词模板。
+-   `tools`：智能体可用于完成任务的工具。
+-   `mcp_servers`：为智能体提供工具的 MCP 服务。参见 [MCP 指南](mcp.md)。
+-   `reset_tool_choice`：是否在一次工具调用后重置 `tool_choice`（默认：`True`）以避免工具使用循环。参见[强制使用工具](#forcing-tool-use)。
 
 ```python
 from agents import Agent, ModelSettings, function_tool
@@ -38,17 +38,17 @@ agent = Agent(
 
 你可以通过设置 `prompt` 来引用在 OpenAI 平台中创建的提示词模板。这适用于使用 Responses API 的 OpenAI 模型。
 
-请按以下步骤使用：
+要使用它，请：
 
 1. 前往 https://platform.openai.com/playground/prompts
 2. 创建一个新的提示词变量 `poem_style`。
-3. 创建一个系统提示词，内容为：
+3. 创建一个系统提示词，内容如下：
 
     ```
     Write a poem in {{poem_style}}
     ```
 
-4. 使用 `--prompt-id` 标志运行该示例。
+4. 使用 `--prompt-id` 参数运行示例。
 
 ```python
 from agents import Agent
@@ -95,7 +95,7 @@ result = await Runner.run(
 
 ## 上下文
 
-智能体对其 `context` 类型是泛型的。上下文是一种依赖注入工具：它是你创建并传入 `Runner.run()` 的对象，会被传递给每个智能体、工具、任务转移等，并作为本次智能体运行的依赖与状态集合。你可以提供任何 Python 对象作为上下文。
+智能体的 `context` 类型是通用的。上下文是一种依赖注入工具：它是你创建并传递给 `Runner.run()` 的对象，会被传递给每个智能体、工具、任务转移等，并作为智能体运行所需依赖和状态的集合。你可以提供任何 Python 对象作为上下文。
 
 ```python
 @dataclass
@@ -114,7 +114,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
@@ -135,20 +135,20 @@ agent = Agent(
 
 !!! note
 
-    当你传入 `output_type` 时，这会告诉模型使用 [structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而不是常规的纯文本响应。
+    当你传入 `output_type` 时，这会告诉模型使用[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)，而不是常规纯文本响应。
 
 ## 多智能体系统设计模式
 
-构建多智能体系统的方法有很多，但我们通常看到两种广泛适用的模式：
+设计多智能体系统的方法有很多，但我们常见到两种广泛适用的模式：
 
-1. 管理者（Agents as tools）：一个中央管理者/编排器将专门的子智能体作为工具来调用，并保留对对话的控制权。
-2. 任务转移：对等智能体将控制权转移给一个专门的智能体，由其接管对话。这是去中心化的。
+1. 管理者（Agents as tools）：中心管理者/编排器将专用子智能体作为工具调用，并保留对对话的控制权。
+2. 任务转移：对等智能体将控制权转移给专用智能体，由其接管对话。这是去中心化方式。
 
-更多细节请参见[我们关于构建智能体的实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。
+更多细节请参见[构建智能体实用指南](https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf)。
 
 ### 管理者（Agents as tools）
 
-`customer_facing_agent` 处理所有用户交互，并调用作为工具暴露的专门子智能体。更多内容请阅读 [tools](tools.md#agents-as-tools) 文档。
+`customer_facing_agent` 负责所有用户交互，并调用以工具形式暴露的专用子智能体。更多信息请阅读 [tools](tools.md#agents-as-tools) 文档。
 
 ```python
 from agents import Agent
@@ -177,7 +177,7 @@ customer_facing_agent = Agent(
 
 ### 任务转移
 
-任务转移是智能体可以委派给的子智能体。当发生一次任务转移时，被委派的智能体会接收对话历史并接管对话。该模式支持模块化、专门化的智能体，使其在单一任务上表现出色。更多内容请阅读 [handoffs](handoffs.md) 文档。
+任务转移是智能体可委派的子智能体。发生任务转移时，被委派的智能体会接收对话历史并接管对话。该模式支持模块化、专用化的智能体，使其在单一任务上表现出色。更多信息请阅读 [handoffs](handoffs.md) 文档。
 
 ```python
 from agents import Agent
@@ -198,7 +198,7 @@ triage_agent = Agent(
 
 ## 动态 instructions
 
-在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过一个函数提供动态 instructions。该函数会接收智能体和上下文，并且必须返回提示词。支持普通函数与 `async` 函数。
+在大多数情况下，你可以在创建智能体时提供 instructions。不过，你也可以通过函数提供动态 instructions。该函数将接收智能体和上下文，并且必须返回提示词。普通函数和 `async` 函数都受支持。
 
 ```python
 def dynamic_instructions(
@@ -215,15 +215,56 @@ agent = Agent[UserContext](
 
 ## 生命周期事件（hooks）
 
-有时，你希望观察智能体的生命周期。例如，你可能希望记录事件，或在某些事件发生时预取数据。你可以通过 `hooks` 属性接入智能体生命周期。对 [`AgentHooks`][agents.lifecycle.AgentHooks] 类进行子类化，并重写你感兴趣的方法。
+有时你会希望观察智能体的生命周期。例如，你可能想在某些事件发生时记录日志、预取数据或记录用量。
+
+有两个 hooks 作用域：
+
+-   [`RunHooks`][agents.lifecycle.RunHooks] 观察整个 `Runner.run(...)` 调用，包括向其他智能体的任务转移。
+-   [`AgentHooks`][agents.lifecycle.AgentHooks] 通过 `agent.hooks` 绑定到特定智能体实例。
+
+回调上下文也会因事件不同而变化：
+
+-   智能体开始/结束 hooks 接收 [`AgentHookContext`][agents.run_context.AgentHookContext]，它包装了你的原始上下文并携带共享的运行用量状态。
+-   LLM、工具和任务转移 hooks 接收 [`RunContextWrapper`][agents.run_context.RunContextWrapper]。
+
+典型 hooks 时机：
+
+-   `on_agent_start` / `on_agent_end`：某个特定智能体开始或结束生成最终输出时。
+-   `on_llm_start` / `on_llm_end`：每次模型调用的前后。
+-   `on_tool_start` / `on_tool_end`：每次本地工具调用的前后。
+-   `on_handoff`：控制权从一个智能体转移到另一个智能体时。
+
+当你希望为整个工作流设置单一观察者时使用 `RunHooks`，当某个智能体需要自定义副作用时使用 `AgentHooks`。
+
+```python
+from agents import Agent, RunHooks, Runner
+
+
+class LoggingHooks(RunHooks):
+    async def on_agent_start(self, context, agent):
+        print(f"Starting {agent.name}")
+
+    async def on_llm_end(self, context, agent, response):
+        print(f"{agent.name} produced {len(response.output)} output items")
+
+    async def on_agent_end(self, context, agent, output):
+        print(f"{agent.name} finished with usage: {context.usage}")
+
+
+agent = Agent(name="Assistant", instructions="Be concise.")
+result = await Runner.run(agent, "Explain quines", hooks=LoggingHooks())
+print(result.final_output)
+```
+
+完整回调范围请参见[生命周期 API 参考](ref/lifecycle.md)。
 
 ## 安全防护措施
 
-安全防护措施允许你在智能体运行的同时，并行对用户输入执行检查/校验，并在智能体输出生成后对其进行检查。例如，你可以筛查用户输入和智能体输出的相关性。更多内容请阅读 [guardrails](guardrails.md) 文档。
+安全防护措施允许你在智能体运行的同时并行检查/验证用户输入，并在智能体输出生成后检查其输出。例如，你可以筛查用户输入和智能体输出是否相关。更多信息请阅读 [guardrails](guardrails.md) 文档。
 
 ## 克隆/复制智能体
 
-通过调用智能体的 `clone()` 方法，你可以复制一个 Agent，并可选地更改任意属性。
+通过在智能体上使用 `clone()` 方法，你可以复制一个 Agent，并可按需更改任意属性。
 
 ```python
 pirate_agent = Agent(
@@ -240,12 +281,12 @@ robot_agent = pirate_agent.clone(
 
 ## 强制使用工具
 
-提供一组工具并不总是意味着 LLM 会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制使用工具。有效取值为：
+提供工具列表并不总是意味着 LLM 会使用工具。你可以通过设置 [`ModelSettings.tool_choice`][agents.model_settings.ModelSettings.tool_choice] 来强制使用工具。有效值有：
 
-1. `auto`：允许 LLM 决定是否使用工具。
-2. `required`：要求 LLM 使用工具（但它可以智能地决定使用哪个工具）。
-3. `none`：要求 LLM _不_ 使用工具。
-4. 设置为特定字符串，例如 `my_tool`：要求 LLM 使用该特定工具。
+1. `auto`，允许 LLM 决定是否使用工具。
+2. `required`，要求 LLM 使用工具（但它可以智能决定使用哪个工具）。
+3. `none`，要求 LLM _不_ 使用工具。
+4. 设置特定字符串，例如 `my_tool`，要求 LLM 使用该特定工具。
 
 ```python
 from agents import Agent, Runner, function_tool, ModelSettings
@@ -265,10 +306,10 @@ 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
@@ -286,7 +327,7 @@ agent = Agent(
 )
 ```
 
-- `StopAtTools(stop_at_tool_names=[...])`：如果调用了任意指定工具则停止，并将其输出作为最终响应。
+- `StopAtTools(stop_at_tool_names=[...])`：如果调用了任一指定工具则停止，并将其输出作为最终响应。
 
 ```python
 from agents import Agent, Runner, function_tool
@@ -310,7 +351,7 @@ agent = Agent(
 )
 ```
 
-- `ToolsToFinalOutputFunction`：一个自定义函数，用于处理工具结果并决定停止还是继续让 LLM 运行。
+- `ToolsToFinalOutputFunction`：自定义函数，用于处理工具结果并决定是停止还是继续调用 LLM。
 
 ```python
 from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
@@ -348,4 +389,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` 生成新的工具调用，如此无限重复。