openai-python 3.42.0 与 openai-node 7.46/7.47 更新解读：Agent 压缩与审查设置、外部密钥管理与 SIP DTMF

openai-python v3.42.0 与 openai-node v7.46.0、v7.47.0 在 2026-10-31 一天内发布：python 与 node 同日投放同一组 API 面——Agents 会话的上下文压缩开关、动作审查模式与会话级支出上限，实验性时间感知，组织管理面的外部密钥五端点，Live sideband 的 SIP DTMF 收发，WebSocket 暖场类型化与逐发送方投递回执，以及图像编辑的 markup 引导蒙层。本文全部参数名、枚举值与文档串引文取自两仓 tag 源码（2026-11-01 核对），不凭 release notes 标题推断。

1. 版本与上架状态

三个版本的上架时间线（2026-11-01 经 GitHub API 与 PyPI/npm registry 核对）：

python v3.42.0 含 13 个 commit、87 个文件变更；node v7.46.0 含 17 个 commit，v7.47.0 只有 2 个 commit、改动集中在 Responses 两个客户端文件——单独成版就是为了把一个类型字段尽快发出去（见第 6 节）。两包功能集合同日对齐，属于同一 API 批次的双端投放；node 多出的条目（typed Realtime references #3081、hosted tool usage #3071、sessions metadata 过滤 #3070、本地解析 #3079）分别是 python v3.41.0 既有能力的 node 侧补齐。

2. Agents 会话：压缩、审查与支出上限

session create 参数（src/openai/types/beta/agents/session_create_params.py）新增三个设置，全部作用于会话级：

compaction（上下文压缩方式）：对象只有 async 一个布尔字段，文档串写明省略或 null 默认 true（后台压缩），false 为阻塞式压缩（blocking compaction），并注明 Background compaction may increase token usage。会话创建后，Agent 对象上新增的只读字段 compaction（Agent.Compaction）返回实际生效的设置。

review（动作审查模式）：Literal["none", "auto_review"]。类型文件对两个取值的原文——none 为保持既有执行行为、不做自动动作审查；auto_review 为 Review eligible actions automatically. Deny manual approval fallbacks（自动审查合格动作，并拒绝人工审批回退）。

spend_control（会话支出上限）：可选对象，limit 必填、正整数美元分或 null；省略字段或置 null 都创建不设限会话。超限后的行为类型层未写。

from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    environment={"type": "openai_hosted"},
    agent={
        "model": "gpt-6.1-sol",
        "compaction": {"async": False},          # 阻塞式压缩（默认 true 为后台）
        "experimental": {"time_awareness": True}, # 实验性时间感知
        "service_tier": "ultrafast",              # 本版进入枚举
    },
    review="auto_review",
    spend_control={"limit": 50000},               # 上限 500.00 美元（单位为美元分）
)

同批在会话参数上还可直接传 vault_ids（本会话可用的 vault ID 列表），Agent 配置里的 tools 文档串注明解析后的工具列表整体不得超过 3 MiB（3,145,728 字节）压缩 UTF-8 JSON。

3. 实验性时间感知 time_awareness

Agent 对象（src/openai/types/beta/agent.py）新增 experimental: Experimental 只读字段，内含布尔开关 time_awareness。文档串原文两处一致：whether the model receives periodic current-time reminders / whether to give the model periodic current-time reminders——给模型周期性的当前时间提醒。release notes 把整批 agent 设置都标了 experimental（add experimental agent time awareness），写代码时把它当实验面处理：字段本身是普通布尔，没有额外的门控参数。

这条与既有的 multi_agent（v2）配置并列在 agent 配置里，service_tier 枚举在本版从 auto/default/flex/priority/fast 扩为六值——新值 ultrafast 对应官方 changelog 2026-10-16 的 Agents API Ultrafast 模式条目（agent.service_tier 置 ultrafast）。

4. 组织外部密钥管理 external_keys

client.admin.organization.external_keys 是本批唯一的新资源面，五个端点（api.md 2026-10-31 版）：

ExternalKey 类型（src/openai/types/admin/organization/external_key.py）的关键字段：purpose 为 Literal["ekm", "psp_decryption"]；云厂商字段按三云分组——AWS 侧 kms_arn / role_arn / kms_key_location，GCP 侧 kms_key_ring_name / kms_project_id / workload_identity_pool_id / workload_identity_project_number / workload_identity_provider_id，Azure 侧 tenant_id / vault_uri / key_name / key_version。ekm（external key management，外部密钥管理）与 psp_decryption（支付服务商解密）两个用途的官方语义说明不在类型层，本站不推断。

release notes 标题为 add organization external key management（#4205 python / #3073 node）。它与既有 client.api_keys（OpenAI 签发的调用凭据）是并存的两套资源，类型层没有任何替代或迁移表述。

5. SIP DTMF：sideband 发送命令 + 服务器接收事件

DTMF（电话按键信令）本批补齐双向：

发送方向：Live sideband 连接新增 transport.dtmf.send 事件（SDK 侧为 SidebandConnection 上的 transport.dtmf 资源，send() 方法）。文档串原文：Send one DTMF keypress to the SIP trunk through a Live sideband connection. This command is supported only for SIP calls. A successful send emits transport.dtmf.sent on sideband. If you provide event_id, the success notification includes it as client_event_id; a failure includes it as error.client_event_id. Send separate events for multiple keypresses.——仅 SIP 通话支持；一次命令发一个按键，连续按键分多次发送；成功回执 transport.dtmf.sent，event_id 用于对账（成功回带 client_event_id，失败在 error.client_event_id）。

# 通过 Live sideband 连接发送一个 DTMF 按键（仅 SIP 通话）
connection.transport.dtmf.send(event="5", event_id="press-1")

接收方向：Realtime 服务器事件新增 input_audio_buffer.dtmf_event_received（src/openai/types/realtime/input_audio_buffer_dtmf_event_received_event.py），类型文档串标注 SIP Only——用户按下的电话按键（0-9、*、#、A-D），event 为按键字符，received_at 为服务器收到事件的 UTC Unix 时间戳。

6. WebSocket：暖场进类型、投递回执进队列

暖场（warmup）：node v7.47.0（release notes 原文 support typed Responses WebSocket warmup，#3084）给 response.create 客户端事件补上 generate?: boolean，文档串原文：Whether to generate output for this response. Defaults to true when omitted. Set to false to prepare request state without model output; the response ID can be used as previous_response_id on a later turn。python 侧该用法在 v3.42.0 的 responses_websocket README 已有文字描述（用既有 extra-field 支持，构造 ResponseCreate 时置 generate=False，经 lane.send() 发出、lane.get_final_response() 收尾，响应 ID 作后续 turn 的 previous_response_id）；python release notes 对应条目为 support WebSocket warmup and preserve cleanup cancellation（#4215）。

投递回执：python #4213（improve WebSocket recovery and delivery reporting）重写了 _send_queue.py——新增 SendReceipt 类，文档串原文 An admitted ordinary sender's own failure, if another caller sends it，带 raise_if_failed() 与 raise_if_unsent() 两个查询方法；队列元素从二元组变为三元组（数据、字节长度、回执）。语义变化最有力的证据是重连测试的改写，新注释原文：A failed flush consumes its attempt, so both queued sends are attempted before recovery succeeds on the third socket. Neither is replayed.——失败的 flush 消耗当次重连尝试，已尝试未送达的消息不再静默重放到后续重连尝试，改为经回执把结果交回发送方。enqueue() 还新增 only_if_pending 条件发送形态（队列为空时不做 UTF-8 转换直接拒绝入队，测试断言了这条零分配路径）。

node 侧对应条目是 v7.46.0 的 #3081（add typed Realtime references and improve WebSocket delivery）与 #3059（realtime：honor the selected WebSocket session target 修复）；src/internal/realtime-credentials.ts 新增经 WebSocket 子协议传递 openai-organization.<id> / openai-project.<id> 路由元数据的逻辑。

7. 图像编辑 markup 蒙层与 GPT Image 2.6 首次露面

images.edit（src/openai/types/image_edit_params.py）新增必填时为 FileTypes 的 markup 参数，文档串原文：A transparent PNG overlaid on the first image to guide the edit. Must match that image's dimensions after orientation and contain transparent pixels. Supports GPT Image 2.5 and 2.6. Cannot be combined with mask.——叠在第一张图上的透明 PNG 引导蒙层；尺寸须与该图按方向（EXIF）校正后一致；必须含透明像素；支持 GPT Image 2.5 与 2.6；不可与 mask 同用。

值得单说的是 GPT Image 2.6：截至 2026-11-01 核对，官方 changelog 与模型目录页都没有它的独立条目或模型卡，这是该模型名首次出现在可抓取的官方渠道（SDK 类型层文档串）。本站只记录露面事实，不推断定价与可用性。

8. 响应格式中途切换、本地解析与按请求解析的 API key

configuration_update 扩展：Responses 与 beta 两处同名的 configuration_update 输入项类型新增 text 字段——Text.format 为 ResponseFormatText | ResponseFormatTextJSONSchemaConfigParam 联合，文档串：Use a JSON schema for structured output or text to return to plain text（JSON schema 结构化输出或回退纯文本）；条目说明从只支持 reasoning 扩为 Supply reasoning, text, or both. Each setting stays in effect until a later update replaces it。也就是说会话中途可切换后续响应的输出格式。

本地解析：python responses.parse 新增 parse_as 形参（type[TextFormatT] | None 重载），ParsedResponseOutputText.parsed 增加 __api_exclude__ 序列化排除；node ResponsesParser 对应条目 #3079（parse Responses using the latest text format update），parseAs 的文档串原文：Parse with this format without sending it to the API（用这个格式做本地解析、不发往 API）。

callable API key 作用域：#4216（keep callable API keys scoped to each request）落在 _client_auth.py——新增 _set_request_api_key() 把键的解析下沉到单次请求：请求头里已有显式 Authorization 覆盖（含 Omit 哨兵与大小写变体）时完全不动，否则按该次请求解析出的键补 Bearer 头。以回调函数提供 API key 的客户端，此前解析时机由客户端层决定，本版起限定在每次请求内。

9. 升级建议与常见坑

• 三个版本都是常规 minor 升级（python 3.41→3.42、node 7.45.1→7.46→7.47），release notes 未标注破坏性变更；node 从 7.45.1 直升 7.47.0 会一并拿到 #3059 的会话目标修复。
• spend_control.limit 的单位是美元分——写 50000 是 500 美元，不是 5 万美元；类型层对超限行为没有描述，别在生产里赌它。
• review="auto_review" 会拒绝人工审批回退（类型文档串原文），接了人工审批链路的应用升版前先确认这条语义符合预期。
• DTMF 发送只支持 SIP 通话；给 WebRTC 会话发 transport.dtmf.send 不在官方支持范围内。
• markup 蒙层与 mask 互斥，且透明 PNG 的尺寸基准是方向校正后的图——预处理的 EXIF 旋转要与蒙层对齐。
• GPT Image 2.6 只在类型文档串露面，模型目录与定价页还没有它；新代码不要把 2.6 写进默认模型名。

10. 下一步

• 上一批 SDK 解读（缓存断点 TTL 语义、Response.tool_usage、Realtime item 引用）见《openai-python 3.40/3.41 与 openai-node 7.45.1 更新解读：缓存断点 TTL 语义、响应级工具用量与 Realtime item 引用》。
• Agents 会话与托管环境的基础面（prewarming、挂起/过期事件）见《OpenAI SDK 出现托管 Agent 环境资源：prewarmed 预热创建、闲置挂起与过期事件》。
• 上下文压缩的事件面（compaction_trigger 与 response.compaction.compacting）见《Responses API 压缩进度事件解读：response.compaction.compacting、compaction_trigger 与长会话上下文压缩》。
• 官方 changelog 近期条目（GPT-6 Rosalind、订阅送 API 额度、12 小时缓存）见《OpenAI 10 月 changelog 补录：GPT-6 Rosalind 生命科学模型、ChatGPT 订阅送 API 额度与 12 小时 prompt caching》。