openai-python 3.48.0 与 openai-node 7.54.0：Agent 会话事件流的混淆填充与 stream_options

官方 SDK 在 2026-11-09 又各发一版：openai-python v3.48.0 与 openai-node v7.54.0。这一批的分工非常不对称——主变更（agent 会话事件流的混淆填充）只在 python 侧落地，node 侧只有两笔类型层与代码生成层面的小改。本文全部事实来源为当日经 GitHub API 读取的 release notes 与 PR 正文、PR 文件级 diff，以及 raw.githubusercontent.com 上的 v3.48.0 / v7.54.0 tag 源码（文档核对版，本站未执行真实流式请求）；PyPI 与 npm 的上架状态经两包 registry API 当日核对。

1. 版本与上架时间线

两包的 release notes 里还各有一笔文档类改动「consolidate AGENTS.md guidance」（python #4254 / node #3121），属仓库自身贡献指南整理，不影响 API 面；python 侧另有锁定依赖 multidict 从 6.9.1 升到 7.1.0 等杂项。上表时间均为 GitHub API 与两包 registry 的原始时间戳（本站 2026-11-10 读取）。

2. 主变更：agent 会话事件流的混淆填充（obfuscation）

python v3.48.0 的核心 feature 是 PR #4251「add stream options for agent sessions」（merge 于 2026-11-05T18:36:43Z，随本版发布）。它给 beta Agents 的事件流加了一套「混淆填充」开关，按 PR 正文的说法是「控制 agent 会话事件流填充的选项」——具体拆开是三件事：

• 创建会话时：请求体新增 stream_options 字段，文档串注明「Options for the event stream. Only allowed when stream is true」；
• 订阅事件流时：GET /agents/sessions/{session_id}/events 新增查询参数 include_obfuscation，布尔、缺省 true；
• 事件对象上：多个事件类型新增可选 obfuscation 字段，文档串写明「Random alphanumeric padding. Present when stream obfuscation is enabled」（随机字母数字填充，stream obfuscation 开启时出现）。

两个开关缺省都是 true——也就是升级到 v3.48.0 之后，默认行为不变（事件里开始可能出现填充字段），想关掉要显式传 false。

3. 两个开关的位置：session create 的 stream_options 与 events 查询参数

从 v3.48.0 tag 的类型文件里照录（文档核对版）：

# openai-python v3.48.0 tag：src/openai/types/beta/agents/session_create_params.py（节选）
class StreamOptions(TypedDict, total=False):
    """Options for the event stream. Only allowed when `stream` is `true`."""

    include_obfuscation: bool
    """Whether to include obfuscation padding in events on this connection.

    Defaults to `true`.
    """

创建「边建边流」的会话时（stream=True），可以预置填充选项：

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    environment=...,  # 必填：内联执行环境或模板引用（形状本篇不展开）
    input="...",      # stream=True 且环境非 self_hosted 时必填（类型文档串口径）
    stream=True,
    stream_options={"include_obfuscation": True},  # 缺省即 True，可显式关
)

对既有会话单独订阅事件流时，include_obfuscation 直接作查询参数（SDK 方法签名随本版加了同名形参）：

events = client.beta.agents.sessions.events.stream(
    "sess_123",
    include_obfuscation=False,  # 连接级开关，缺省 True
)
for event in events:
    print(event.type, event.obfuscation)

等价的原始 REST 调用（路径前缀 /v1/agents 与本库既有 sessions 资源一致，world-state 既有记录）：

curl -s "https://api.openai.com/v1/agents/sessions/sess_123/events?include_obfuscation=false" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

三处口径的对应关系要分清：stream_options 是创建会话时的预置（只对走 stream=True 的那次创建有意义）；events 端点的 include_obfuscation 是订阅时的连接级开关（文档串原文「on this connection」）；事件上的 obfuscation 字段是开关开启时的产物，不是第三个开关。

4. 事件对象上的 obfuscation 字段：33 个事件类型文件

PR #4251 的文件级 diff 实测：44 个变更文件里，src/openai/types/beta/ 下有 33 个事件类型文件全部新增了同一个可选字段——

obfuscation: Optional[str] = None
"""Random alphanumeric padding. Present when stream obfuscation is enabled."""

覆盖面按事件名分组：会话生命周期（agent.session.created / failed / idle / in_progress / requires_action；error 事件的字面量是单独的 error，不带 agent.session. 前缀）、环境生命周期（environment.pending / ready / connected / disconnected / expired / failed / suspended / reset）、turn 生命周期与内容事件（turn.created / in_progress / completed / failed / cancelled、turn.item.added / done、turn.content_part.added / done、turn.output_text.delta / done）、推理摘要四件（agent.session.turn.reasoning_summary_part.added / .done、agent.session.turn.reasoning_summary_text.delta / .done——reasoning_summary 后接下划线，非点分）、subagent 三件（created / active / closed）、输出增量（agent.output.command_execution_output.delta）。换句话说，无论订阅到哪类事件，都可能遇到这个字段；消费侧按可选字段处理即可。

5. node 侧现状与官方文档跟进状态

两包对照（本批核对日 2026-11-10）：

官方文档侧：agents-api 的会话事件指南（本站 2026-11-10 抓取 .md 全文变体，约 21KB）通篇没有 obfuscation 字样——这批是「SDK 类型层先行于官方文档」，与此前 prompt caching TTL「指南先行于 SDK 文档串」的次序正好相反。依赖这两个开关写生产代码的话，以你所装版本的实际类型文件为准。

6. 同批其余变更：rosalind 进 beta Responses 与 agent scheduling 保留

• gpt-6-rosalind 进 beta Responses 模型联合（python #4257、node #3126，两包 PR 在 2026-11-08T16:17 同分钟 merge）：diff 里可见的枚举序列为 gpt-5.6-cyber、gpt-6-cyber、gpt-rosalind-research 之后插入 gpt-6-rosalind。背景：stable Responses 联合早在 11-05 批的 v3.46.0/#4243（node v7.51.0/#3109）已收录 rosalind（本站 2026-11-06 核对），本批补的是 beta 命名空间——两处联合至此对齐。gpt-6-cyber 此前进联合的过程见《GPT-6 Cyber 官宣：Astra 的网络安全特化变体登陆 API，ExploitGym 48.5%、Preparedness 升至 Critical》。
• agent scheduling API 保留（python #4255 merge 于 2026-11-07T03:39:32Z、node #3123 merge 于 03:40:31Z）：PR 正文只有一句「Retains the existing agent scheduling APIs」；两包的文件级 diff 均只有 .castiron.stats.yml（代码生成配置哈希变化）——仓库内没有任何源码级 API 变更可指认。「保留」是否对应上游规格再生时的某次取舍，官方文本没有说明，本站只记录动作本身。
• python 侧杂项：文档类「consolidate AGENTS.md guidance」（#4254）、锁定依赖 multidict 6.9.1 → 7.1.0（#4259）与若干开发依赖升级——不影响 API 面。

7. 常见错误与排查

• stream_options 报错：先确认会话创建确实传了 stream=True——文档串原文写明该对象「Only allowed when stream is true」；非流式创建带上它没有意义。
• 升级后事件里多出 obfuscation 字段：这是 v3.48.0 的默认行为（缺省 true），不是异常；不想看到填充就按第 3 节两个入口显式传 include_obfuscation=false。
• node 项目里找不到这些参数：不是你的版本问题——截至 v7.54.0 node 类型层确实没有这套开关（tag 实测）；别照 python 示例硬传。
• filler 字段的语义问题：官方只说它是随机字母数字填充；用途与计费官方未说明，遇到具体问题以官方后续文档为准，本站不推测。

下一步

• 上一批 Agents 会话设置（compaction / auto_review / spend_control）的逐项解读见《openai-python 3.42.0 与 openai-node 7.46/7.47 更新解读：Agent 压缩与审查设置、外部密钥管理与 SIP DTMF》。
• beta Agents 资源面的首次落地（托管环境、挂起与过期事件）见《OpenAI SDK 出现托管 Agent 环境资源：prewarmed 预热创建、闲置挂起与过期事件》。
• 两包版本节奏与全量发布线浏览见《OpenAI 模型更新日志（2026 持续更新）》。