trpc-group · pcerypeng · Jul 29, 2026 · Jul 30, 2026
diff --git a/docs/mkdocs/en/graph.md b/docs/mkdocs/en/graph.md
@@ -413,7 +413,7 @@ Scenario: Integrate any BaseAgent (e.g., LlmAgent/GraphAgent) as a node in the g
 graph.add_agent_node(
     node_id="delegate",
     agent=delegate_agent,
-    isolated_messages=True,
+    history_scope="branch",
     input_from_last_response=False,
     event_scope="delegate_scope",
     input_mapper=StateMapper.rename({"query_text": STATE_KEY_USER_INPUT}),
@@ -423,12 +423,29 @@ graph.add_agent_node(
 ```
 
 Common options:
-- isolated_messages: Whether to isolate the parent session's message history
+- history_scope: Child history policy. `none` starts without parent history,
+  `branch` inherits only events from the same Agent-node branch (including its
+  nested branches), and `all` inherits the complete parent event history.
+- isolated_messages: Legacy compatibility switch. When history_scope is omitted,
+  `True` maps to `none` and `False` maps to `all`. An explicit history_scope
+  takes precedence.
 - input_from_last_response: Whether to map the parent state's last_response as the child node's user_input
 - event_scope: Event branch prefix for the child Agent
 - input_mapper / output_mapper: Parent-child state mapping (explicit configuration recommended)
 - config / callbacks: Same as add_node
 
+`branch` filters the child Session event log. The transient graph `messages`
+state stays empty and GraphAgent rebuilds model input from those filtered events;
+this keeps persistent Session state JSON-serializable. The policy is useful when
+the same Agent node is entered again in a later outer run without exposing
+private conversations from sibling nodes. During HITL resume, legacy
+`isolated_messages=True` nodes still recover their current branch so the pending
+function-call exchange remains intact.
+
+When a child Agent emits a `LongRunningEvent`, `add_agent_node` promotes it to a parent GraphAgent `interrupt`: the parent graph does not execute downstream nodes, and the Runner event preserves the original tool name and arguments. After the client submits the matching `FunctionResponse`, the parent graph resumes the current Agent node and the SDK maps the response back to the child's original function call. The graph continues only after the child Agent reaches a final result. This supports multiple HITL rounds in one node and persists child state in the SessionService-backed checkpoint for process-restart recovery.
+
+When the Agent node is a TeamAgent, the Leader can use the same HITL flow. Regular Team Members still must not be configured with or invoke `LongRunningFunctionTool`.
+
 GraphAgent does not require (nor support) registering Agent nodes via sub_agents; composition relationships are handled uniformly through add_agent_node.
 
 ## Advanced Usage

diff --git a/docs/mkdocs/en/model.md b/docs/mkdocs/en/model.md
@@ -121,6 +121,32 @@ model = OpenAIModel(
 )
 ```
 
+#### Responses API
+
+`OpenAIModel` uses Chat Completions by default. Enable the Responses API explicitly for OpenAI or compatible
+providers that expose `/v1/responses`:
+
+```python
+model = OpenAIModel(
+    model_name="your-responses-model",
+    api_key="your-api-key",
+    base_url="https://api.openai.com/v1",
+    use_responses_api=True,
+    responses_api_params={
+        "store": False,
+        "reasoning": {"summary": "auto"},
+    },
+)
+```
+
+The switch is opt-in so existing OpenAI-compatible providers continue to use Chat Completions. The adapter maps
+conversation history, function calls and `function_call_output` items, structured output, semantic streaming events,
+reasoning summaries, and token usage into the existing tRPC-Agent types. When `store=False`, the SDK automatically
+requests `reasoning.encrypted_content` so reasoning items can be replayed with tool outputs in the next turn.
+
+`responses_api_params` accepts Responses-only fields such as `store`, `reasoning`, `include`, and `truncation`.
+`model`, `input`, and `stream` are managed by `OpenAIModel` and cannot be overridden there.
+
 #### Advanced Usage
 
 Since version `1.1.10`, `OpenAIModel` supports passing a shared HTTP client provider to enable connection reuse. By default, `OpenAIModel` creates a temporary HTTP client for each model-service request. If you want to reuse connections, use the following configuration:

diff --git a/docs/mkdocs/zh/graph.md b/docs/mkdocs/zh/graph.md
@@ -412,7 +412,7 @@ graph.add_mcp_node(
 graph.add_agent_node(
     node_id="delegate",
     agent=delegate_agent,
-    isolated_messages=True,
+    history_scope="branch",
     input_from_last_response=False,
     event_scope="delegate_scope",
     input_mapper=StateMapper.rename({"query_text": STATE_KEY_USER_INPUT}),
@@ -422,12 +422,26 @@ graph.add_agent_node(
 ```
 
 常用选项：
-- isolated_messages：是否隔离父会话消息历史
+- history_scope：子 Agent 历史策略。`none` 不继承父历史，`branch` 只继承
+  当前 Agent 节点 branch 及其子 branch 的事件，`all` 继承完整父会话事件。
+- isolated_messages：旧版兼容开关。未指定 history_scope 时，`True` 映射为
+  `none`，`False` 映射为 `all`；显式 history_scope 优先。
 - input_from_last_response：是否将父状态 last_response 映射为子节点 user_input
 - event_scope：子 Agent 事件分支前缀
 - input_mapper / output_mapper：父子状态映射（推荐显式配置）
 - config / callbacks：同 add_node
 
+`branch` 过滤 child Session 的事件日志；临时图状态中的 `messages` 保持为空，
+GraphAgent 在需要时从已过滤事件重建模型输入，从而保证持久化 Session state
+仍可 JSON 序列化。该策略适用于同一 Agent 节点在后续外层 run 中再次进入、
+但又不能看到兄弟节点私有对话的场景。HITL 恢复时，旧的
+`isolated_messages=True` 节点仍会恢复当前 branch，以保留挂起的
+function-call 交互链路。
+
+当子 Agent 发出 `LongRunningEvent` 时，`add_agent_node` 会将其提升为父 GraphAgent 的 `interrupt`：父图不会执行后继节点，Runner 返回的事件保留原工具名和参数。客户端提交对应 `FunctionResponse` 后，父图恢复当前 Agent 节点，SDK 将响应映射回子 Agent 的原始 function call；只有子 Agent 最终完成后父图才继续。该机制支持同一节点多轮 HITL，并将 child state 写入 SessionService-backed checkpoint，服务重启后仍可恢复。
+
+TeamAgent 作为 Agent 节点时同样支持 Leader 发起 HITL；普通 Team Member 仍不允许配置或调用 `LongRunningFunctionTool`。
+
 GraphAgent 不需要（也不支持）通过 sub_agents 注册 Agent 节点；组合关系统一用 add_agent_node 完成。
 
 ## 进阶用法

diff --git a/docs/mkdocs/zh/model.md b/docs/mkdocs/zh/model.md
@@ -121,6 +121,31 @@ model = OpenAIModel(
 )
 ```
 
+#### Responses API
+
+`OpenAIModel` 默认仍使用 Chat Completions。对于 OpenAI 或提供 `/v1/responses` 的兼容服务，需要显式开启：
+
+```python
+model = OpenAIModel(
+    model_name="your-responses-model",
+    api_key="your-api-key",
+    base_url="https://api.openai.com/v1",
+    use_responses_api=True,
+    responses_api_params={
+        "store": False,
+        "reasoning": {"summary": "auto"},
+    },
+)
+```
+
+该开关默认关闭，现有 OpenAI-compatible 服务不会改变调用路径。适配层会把多轮消息、函数调用及
+`function_call_output`、结构化输出、语义化流式事件、reasoning summary 和 token usage 映射为现有
+tRPC-Agent 类型。设置 `store=False` 时，SDK 会自动请求 `reasoning.encrypted_content`，以便下一轮
+连同工具结果一起回放 reasoning item。
+
+`responses_api_params` 可传入 `store`、`reasoning`、`include`、`truncation` 等 Responses 专用字段；
+`model`、`input`、`stream` 由 `OpenAIModel` 管理，不能在此覆盖。
+
 #### 高级用法
 
 从版本 `1.1.10`之后 OpenAIModel 支持传入共享的 http client 来解决连接复用的场景，当前的 OpenAIModel 默认每次都会创建临时的 http client 去访问模型服务；如果期望连接复用可以使用如下的方式

diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ classifiers = [
 ]
 dependencies = [
     "pydantic>=2.11.3",
-    "openai>=1.3.0",
+    "openai>=1.66.0",
     "mcp>=1.10.1",
     "aiohttp",
     "httpx>=0.27.0",