openai-python 3.49.0 与 openai-node 7.55.0：Agents 函数工具 async 设置的类型补齐

openai-python v3.49.0 与 openai-node v7.55.0 于 2026-11-10T06:47Z 前后同分钟发布，主变更是同一个：给 beta Agents API 的函数工具形状补上既有 async 设置的类型标注（python #4264、node #3140，标题同名 add typed async function tools）。本文全部事实经 GitHub API（release 对象与 PR 正文）、PR diff 与 v3.49.0 / v7.55.0 tag 源码当日核对；紧邻前一版（v3.48.0 / v7.54.0）的基线对照也做了，用于确认字段确为本批新增。

1. 版本与上架时间线

两包 release notes 的 feature 条目同名：api: add typed async function tools。python 侧另有一条 fix；node 侧其余全是依赖 bump，无功能变更。

2. 改了哪些形状：beta Agents 的四个 function 变体

四个新字段分布在 beta Agents 的两对「请求 / 响应」形状上：

这四个形状服务 beta Agents 的 agents、sessions、automations 三类资源——node 仓库的测试改动能对上：agents / automations / sessions 三个测试文件的函数工具夹具都加了 async: true。作用域边界：本批 diff 只触及上述四个形状，Responses API 的函数工具类型不在其中（见第 5 节）。

3. python 侧：async_ 别名字段与保留字 TypedDict

响应模型（v3.49.0 tag 的 agent_tool.py 照录，PersistedAgentToolResourceFunction 同型）：

class AgentToolResourceFunction(BaseModel):
    """A function defined by the application."""

    defer_loading: bool
    """Whether the function is deferred and discovered through tool search."""

    description: str
    """A description of what the function does."""

    name: str
    """The name of the function."""

    parameters: Dict[str, object]
    """A JSON Schema object describing the function's arguments."""

    type: Literal["function"]
    """The type of the object. Always `function`."""

    async_: Optional[bool] = FieldInfo(alias="async", default=None)
    """Whether the agent continues without waiting for the function result."""

请求侧因为 async 是 Python 保留字、TypedDict 里却能直接写字符串键，代码生成器用一个保留字 mixin 来组织（agent_tool_param.py 照录）：

_AgentToolConfigParamFunctionReservedKeywords = TypedDict(
    "_AgentToolConfigParamFunctionReservedKeywords",
    {
        "async": bool,
    },
    total=False,
)


class AgentToolConfigParamFunction(_AgentToolConfigParamFunctionReservedKeywords, total=False):
    """A function defined by the application."""

PR 正文还给了两个序列化口径：读响应此前要靠 getattr(tool, 'async') 或 tool.model_extra['async'] 读未声明的额外字段，现在直接读 tool.async_；model_dump(by_alias=True, exclude_unset=True) 能正确保留 true / false / 省略三种状态，而裸的 model_dump(by_alias=True) 会把省略值写成 async: None。

4. node 侧：四个 interface 的 async 可选属性

v7.55.0 tag 的 agents.ts 里，四个 interface 各加一段（请求侧两个带 Defaults to false 句，照录 AgentToolConfigParamFunction 的尾部）：

export interface AgentToolConfigParamFunction {
  /**
   * A description of what the function does.
   */
  description: string;

  /**
   * The name of the function.
   */
  name: string;

  /**
   * A JSON Schema object describing the function's arguments.
   */
  parameters: { [key: string]: unknown };

  /**
   * The type of the object. Always `function`.
   */
  type: 'function';

  /**
   * Whether the agent continues without waiting for the function result. Defaults to
   * `false`.
   */
  async?: boolean;
}

基线对照（skill 要求的「紧邻前一版」）：v7.54.0 tag 的同名文件里，async?: 只出现在两个 Compaction interface（后台压缩开关）上——函数工具形状零处；v3.48.0 tag 的 agent_tool.py 零处 async_。两包的字段都确为本批新增，不是「早已存在」。

5. 与既有 async 工具调用的关系：类型补齐而非新机制

三句边界，都有当日可复现的来源：

• 能力本身不是本批发布的。node PR 正文原话：callers have been gaining typed access to the existing async setting——给既有设置补类型。Responses API 的函数工具参数类型（responses/function_tool_param.py）在 v3.48.0 与 v3.49.0 两个 tag 都带可选 "async": bool 键（同为保留字 mixin 形态），本批 diff 未触及它。
• 本批的类型只落在 beta Agents 形状上。beta Responses 的 function_tool.py 在两个 tag 均无 async_——不要把本批写成「Responses API 新增 async」。
• 官方文档层尚未跟进。本批未检查到 agents-api 指南对 AgentTool 形状 async 字段的描述更新（本批以 GitHub PR 与 tag 源码为白名单来源，未把文档当依据）；写生产代码前以你所用版本的实际类型文件为准。

6. python 同批修复：Microphone.record() 的 PCM WAV 编码

python 侧本批另一条是 fix #3900（merge 于 2026-11-10T02:09:16Z，标题 encode microphone recordings as valid PCM WAV，改动 src/openai/helpers/microphone.py，另新增 tests/lib/test_microphone.py）。PR 正文给出的机制：

• 修复前，Microphone.record() 把每种采集 dtype 直接写进整数 PCM WAV——float32 的 IEEE float 字节会被按有符号整数解读；int8 的静音值 0 会被当成最负样本，因为 8 位 WAV PCM 是无符号的。
• 修复后，float32 录音先转 16 位 PCM 再写，int8 先偏移成无符号 8 位再写（按转换后的采样位宽写头）；int16 / int32 / uint8 三种编码不变，return_ndarray=True 时仍原样返回原始 dtype 与数据。
• PR 正文自述回归测试覆盖全部五种采集 dtype、立体声元数据与 ndarray 返回，其中 float32 与 int8 两个 WAV 用例修复前失败。

这条修复只动 python 的本地录音 helper，与 API 形状无关；node 侧无对应条目。

7. 常见错误与排查

• 响应字段取不到：python 侧读 tool.async_，不要写 tool.async（语法错误）或再去读 model_extra——本批起它是已声明字段。
• 序列化后多了 null：model_dump(by_alias=True) 不带 exclude_unset=True 会输出 async: None；回放或比对请求体时先统一 dump 参数。
• 别在文章或代码注释里写「Responses API 新增 async」：本批类型只落在 beta Agents 的四个形状上，Responses 侧的请求键早已存在（v3.48.0 tag 实测）。
• 文档串措辞差异不是笔误：node 请求侧多出 Defaults to false、响应侧没有——两侧 tag 源码本来如此，引用时按侧引用。

下一步

• 上一批 SDK 双包（3.48.0 / 7.54.0）的解读见《openai-python 3.48.0 与 openai-node 7.54.0：Agent 会话事件流的混淆填充与 stream_options》。
• beta Agents 会话的压缩 / 审查 / 支出上限等既有会话设置见《openai-python 3.42.0 与 openai-node 7.46/7.47 更新解读：Agent 压缩与审查设置、外部密钥管理与 SIP DTMF》。
• 全部 OpenAI 发布节点按时间线浏览见《OpenAI 模型更新日志（2026 持续更新）》。