实测14个Agent框架怎样生成工具参数
用同一个带 Google 风格文档字符串的 Python 函数测试 14 个框架,只有 5 个默认把参数说明写入 JSON Schema,8 个将其留在工具描述中。生成的工具定义占用 178 至 301 个 Token。
AI 深度解读
同一个带 Google 风格 docstring 的 Python 函数,交给 14 个 AI Agent 框架注册为工具,默认只有 5 个把六个参数的说明分别写进 JSON Schema。另有 8 个把说明留在工具简介里,AutoGen 则用参数名填充说明。生成的工具定义从 178 到 301 tokens,相差近七成。
如果你在做 AI 工具调用,或者要把工具暴露给 MCP 客户端,这个差异会影响参数说明能否出现在表单和审批界面,也会影响哪些参数可以省略。作者测的是框架实际生成的定义,工具调用准确率还没有测。
同一个函数,参数说明为什么会落在不同地方
作者在 2026 年 11 月 20 日从 PyPI 安装了 14 个框架,每个框架用独立的 virtualenv,次日用默认配置运行测试。测试函数 search_flights 有一行摘要和一个 Google 风格的 Args: 段。origin、destination、depart_date 都是必填的 str,max_price_usd 是默认值为 None 的 Optional[float],cabin 是默认 economy 的 Literal["economy", "premium", "business"],nonstop_only 是默认 False 的 bool,函数返回 str。
把说明写进 properties.*.description 的有 OpenAI Agents SDK(openai-agents 0.25.0)、Pydantic AI(pydantic-ai 2.71.0)、smolagents 1.26.0、Strands Agents(strands-agents 1.65.0)和 agno 3.2.1。
默认把 Args: 原文留在工具 description 里的有 LangChain/LangGraph(langchain-core 1.8.4)、crewai 1.15.44、google-adk 2.15.0、llama-index-core 0.14.26、haystack-ai 3.5.0、Microsoft Agent Framework(agent-framework 1.26.0)、dspy 3.5.0 和 ag2 1.3.3。AutoGen(autogen-core 0.7.5)的 FunctionTool 要求显式传入工具的 description,它不读取 docstring,并把每个字段的说明设为字段名。
模型仍能看到工具简介里的 Args:。区别出现在按字段消费 Schema 的地方。比如前端根据 MCP inputSchema 渲染表单时,通常会从字段自己的 description 取提示文案。审批界面逐项展示参数时也是如此。说明全挤在工具简介里,客户端就得额外解析一段自然语言。如果为了节省上下文截短简介,参数文档也可能一起被裁掉。
同一个可选参数,为什么有的必须传,有的可以省略
OpenAI Agents SDK 设置 strict: true 和 additionalProperties: false,并把六个字段全列进 required。这是 OpenAI strict 模式的要求。原本有默认值的三个参数,到了模型这一侧也得显式发送。没有预算上限时,max_price_usd 可以传 null,因为 Schema 用 anyOf 同时允许 number 和 null。cabin 和 nonstop_only 则每次都要给出值,Python 函数收到了这些实参,自然不会再用自己的默认值补齐。CrewAI 的 convert_tools_to_openai_schema 也把六项设为必填,字段说明依然留在工具简介里。
Strands Agents 对 max_price_usd 发出的是 "type": "number", "default": null。JSON Schema 的 default 是注解,校验器通常不会因为这个默认值就拒绝整份 Schema。可一旦模型照着默认值真的传了 null,实参就过不了 number 校验。smolagents 使用的 nullable: true 则属于 OpenAPI 3.0,标准 JSON Schema 校验器不会据此允许 null。原文点名了 cabin 和 nonstop_only,但没有展示完整定义来交代每处 nullable 的位置。
Agno 选择让 max_price_usd 保持 number,同时把它留在 required 之外。调用方可以省略字段,由 Python 使用默认值。这两种表达各有适用条件。用 OpenAI strict 模式时,字段必须出现,如果业务允许无值,就要在类型里明确接纳 null。允许省略字段时,则可以直接用 required 表达这一点。
每轮带上的工具定义,哪些 tokens 可以省
作者用 tiktoken 的 o200k_base 对紧凑 JSON 计数,统计 name、description、parameters,框架设置了 strict 就一并计入。Agno 最短,为 178 tokens,LlamaIndex 最长,为 301 tokens,约为前者的 1.69 倍。LlamaIndex 把 Python 函数签名放在工具简介的首行,单这一行就占 55 tokens。LangChain 默认用了 213 tokens,打开 parse_docstring=True 后,六项说明都进入对应字段,定义缩到 194 tokens,少了 19。原来的 Args: 段会再写一遍每个参数名。
还有 7 个框架保留了 Pydantic model_json_schema() 生成的 title。比如 max_price_usd 已经是属性名,又有一个 Max Price Usd 标题。作者只删除这些标题并重新计数,每个工具省了 31–39 tokens,占完整定义的 11%–17%。如果同一份 Schema 还给前端表单用,是否删除要看界面有没有拿 title 当显示标签。
框架通过 MCP 重新导出工具时,这些字段可能原样进入服务端的 inputSchema。原文援引的报告把 MCP 2026-07-28 修订解读为允许使用 JSON Schema 2020-12 关键字,并建议 tools/list 保持稳定顺序,方便提示缓存命中。稳定排序有利于复用缓存,字段内容也得稳定。Microsoft Agent Framework 按字母排列参数,这个顺序可重复,但和 Python 函数签名里的参数顺序不同。
123 tokens 的差距乘以 20 个工具,得到每个请求约 2,460 个输入 tokens。这是线性外推。原文另举了一个三工具客服 Agent 的账单示例,30 天的 gpt-5 总费用为 $3.042,其中工具 JSON 占 $0.5655。实际开销还要看每轮带了哪些工具、供应商如何包装定义,以及使用哪套 tokenizer。Claude 和 Gemini 的计数口径就和这次实验不同。
我的判断
对前端和全栈团队,最有说服力的是字段说明和可选值这两处。字段文档能不能直接渲染,省略字段与传入 null 会不会得到同一个结果,都可以拿最终发出的 Schema 当场验证。作者只测了一个函数,也没有给模型调用成功率的对照数据。逐字段说明是否能提高模型选参的准确率,仍是经验判断。
和手写 Schema 相比,自动生成省掉了重复维护函数签名和参数类型的工作,前提是框架能表达你需要的调用约定。只缺字段说明时,先试框架已有的注解或解析选项,改动通常比换框架小。若工具同时服务于模型、表单和审批,团队更需要明确维护这份 Schema 对三方的约定。178 和 301 的差距来自这一条函数,单凭这个结果很难给框架选型排序。
能拿来做什么
- 新接一个工具时,把实际交给模型客户端的定义打印出来。用它检查
properties.*.description、required、枚举和可空类型。如果还要给前端渲染参数表单,就用同一份inputSchema验证字段提示能否直接读到。 - 先用框架已有的入口补全字段说明。LangChain 可以开
parse_docstring=True,AutoGen 可以用Annotated[str, "..."],基于 Pydantic 的封装可以试Field(description=...)。改完重新导出,确认说明确实到了字段上。 - 对接工具参数校验时,分别验证省略
max_price_usd、传null和传数字这三种输入。启用 strict 模式后,也检查显式传入的舱位和布尔值是否符合原先依赖的 Python 默认行为。 - 如果工具列表每轮都要发,拿实际发送的整份列表做计数。准备删除自动生成的
title前,先检查表单和审批界面是否用到了这些标题。