MCP 与工具调用

Function Calling JSON Schema 指南

设计函数调用JSON Schema，明确必填字段、类型与约束；调用前校验参数，调用后验证输出。

查找此工作流的工具在 Playground 中测试此工作流

发布日期：2026年4月2日 · QVeris团队制作

Illustrated monitor comparing valid and invalid weather-tool arguments against JSON Schema required fields, types and enums. — JSON Schema 校验示意：按必填字段、类型与枚举值检查天气工具的输入参数。

摘要

问题：AI Agent 在工具执行时经常失败，不是因为推理错误，而是因为无效或模糊的 JSON Schema。缺失的必填字段、弱类型定义或不一致的输出 Schema 可能悄然破坏生产 Agent。

解决方案：JSON Schema 定义了工具接受什么输入、返回什么输出、如何强制执行验证以及 Agent 如何避免无效的工具调用。它是 Agent 推理层和工具执行层之间的契约。

结果：正确的 Schema 设计可以实现可靠、安全和生产级的 AI Agent 工具执行 — 在 API 调用失败之前捕获参数不匹配。

什么是函数调用中的 JSON Schema？

JSON Schema 定义 AI Agent 系统中工具输入与输出的结构，明确哪些参数必填、允许哪些类型、格式应如何以及有哪些约束，从而在 Agent 推理层与工具执行层之间建立确定性的契约。

在函数调用中，模型接收包含每个函数参数 JSON Schema 的函数定义列表。当模型决定调用 get_stock_price 时，它必须输出符合 Schema 的参数 — {"symbol": "AAPL"} 在 symbol 是必需字符串时有效；{"ticker": "AAPL"} 将因参数名称不匹配而验证失败。Schema 是防止最常见生产失败模式的护栏：模型输出与工具期望之间的参数不匹配。

为什么 Schema 对 AI Agent 很重要

❌

没有 Schema

Agent 容易臆造参数，工具在运行时以难以理解的错误失败，输出不可靠且无法程序化验证。调试时只能人工阅读原始 API 响应；只要某个工具返回意外格式，多工具编排就可能中断。

✅

有 Schema

工具调用变得确定：模型清楚哪些参数有效；验证自动完成，执行层会在 API 调用前发现不匹配；无效调用会被阻止而不是贸然执行；每次验证失败都有明确原因，调试也更加结构化。

输入 Schema vs 输出 Schema

Schema 类型	用途	示例
输入 Schema	定义 Agent 向工具发送什么	`{"symbol": "string", "interval": "enum"}`
输出 Schema	定义工具向 Agent 返回什么	`{"price": "number", "timestamp": "string"}`

两种 Schema 同等重要。定义良好的输入 Schema 防止无效调用。定义良好的输出 Schema 支持下游 Agent 推理 — Agent 确切知道期望什么字段，并可以在将其纳入工作流之前验证响应。

必填字段与验证规则

stock_price_schema.json — Terminal

// Production JSON Schema for a stock price tool { "tool": "get_stock_price", "input_schema": { "type": "object", "required": ["symbol"], "properties": { "symbol": {"type": "string", "description": "Stock ticker symbol"}, "interval": {"type": "string", "enum": ["1d", "1h", "15m"]}, "include_metadata": {"type": "boolean", "default": false} } }, "output_schema": { "type": "object", "properties": { "price": {"type": "number"}, "timestamp": {"type": "string", "format": "date-time"}, "source": {"type": "string"} } } }

✓ 必填字段必须明确

所有必填参数必须列入required数组。未明确标为必填的字段可能被模型省略，不能要求模型自行猜测。

✓ 类型必须严格声明

使用string、array和object等明确类型，避免any或未声明类型。宽松类型容易造成生产环境中的静默失败。boolean、number、

✓ 枚举必须限制允许值

参数的有效值有限时，用enum限定。例如只允许["1d","1h","15m"]时，{"interval":"weekly"}应校验失败。（{"interval": "weekly"}）

✓ 可选字段必须明确标注为可选

不要把可选字段放入required数组；适当提供默认值，让模型明确哪些字段可省略。

Schema 类型与约束

类型	使用场景	约束示例
字符串	代码、标识符与时间戳	`enum`, `pattern`, `format`, `minLength`
数字	价格、数量与百分比	`minimum`, `maximum`, `multipleOf`
布尔值	标志、开关与包含/排除选项	`default`
数组	代码列表与多值参数	`minItems`, `maxItems`, `uniqueItems`
对象	嵌套配置与复杂输入	`required`, `additionalProperties`

常见的 Schema 设计错误

❌ 缺少必填字段该required数组为空或不完整时，模型会遗漏关键参数，导致缺少参数错误。应在定义结构时提前防止。

❌ 类型约束过弱字段声明为{"type": "string"}没有枚举、模式或约束时，模型可能发送"1day"，而API要求"1d"。取值范围有限时应明确约束。

❌ 缺少校验规则price字段未设置最小值时，模型可能发送负数价格。添加"minimum": 0以避免无意义的值进入API。

❌ 输出结构不一致输出结构声明price声明为数字，工具却有时返回字符串，会破坏下游解析。应验证真实输出符合声明的结构。

❌ 缺少错误结构工具未定义错误响应格式，失败时智能体无法判断应重试、回退还是报告失败。应同时定义成功和错误响应结构。

MCP 和工具调用中的 Schema

层级	如何使用 Schema
MCP	定义工具 Schema 如何在服务器清单中暴露，是负责发布 Schema 的协议层。
工具调用	使用 Schema 在执行前验证输入、执行后检查输出，属于 Agent 执行层。
函数调用	依据 Schema 把模型输出格式化为有效的结构化参数，属于模型输出层。
QVeris 检查	在发现阶段验证 Schema，选择工具前检查其声明的 Schema 是否符合 Agent 要求。

Schema 是所有层之间的共享契约。MCP 发布它。工具调用执行它。函数调用根据它格式化输出。QVeris 在 Agent 承诺使用工具之前检查它。当任何层的 Schema 处理中断时，整个工具执行链变得不可靠。

Agent 如何在运行时使用 Schema

Schema 不仅仅是设计时的产物。它驱动 Agent 运行时工具执行管道的每一步：

1. 工具发现

智能体按任务检索工具，结构说明与参数名称是能力匹配的重要信号。包含symbol与price等明确字段的工具，比只有通用字段的工具更适合股票查询。

2. Schema 检查

选择工具前，Agent 会检查输入 Schema：必填参数是否齐全？类型是否与 Agent 可提供的数据匹配？枚举约束是否符合任务？这就是 QVeris 的 Inspect 阶段。

3. 输入校验

执行层会先依据声明的输入 Schema 验证模型的函数调用输出，再发送给 API。缺少必填字段或类型不匹配会在这里被发现，而不是等到 API 返回后。

4. 输出校验

工具响应会依据声明的输出 Schema 验证；意外字段、缺少必需输出或类型不匹配都会在响应进入 Agent 推理层前被标记。

QVeris Schema 检查层

QVeris 在 检查阶段帮助 Agent — 在 Agent 承诺调用工具之前验证 Schema。它不定义 Schema；它检查并验证它们。

📐

检查输入 Schema

核对必填字段、类型、枚举和约束，并在执行前确认 Agent 已具备全部所需信息，尽早发现 Schema 不匹配。

📋

检查输出 Schema

检查工具声明的输出结构是否符合下游工作流预期。不兼容的输出 Schema 可能导致难以察觉的集成失败。

🔀

Schema 不匹配时路由

如果工具 Schema 不符合 Agent 要求，应路由到 Schema 匹配的回退工具，而不是尝试注定失败的调用。

✓

验证供应商约束

除了类型定义，还要检查 Schema 元数据中的提供商说明、速率限制、认证要求和 API 限制。

QVeris 不负责定义 Schema。它帮助 Agent 在执行前检查和验证 Schema — 在发现时而不是在 API 调用时捕获不匹配。阅读文档 → 或查看定价 →。

快速上手指南

☐定义严格的输入 Schema — 必填字段、类型、枚举、约束

☐为每个工具定义输出 Schema — 不要让输出无类型

☐避免松散类型 — 永远不要使用无约束的 any、无类型或自由文本类型

☐验证必填字段确实是必需的 — 通过省略每个字段来测试

☐在域有限时添加枚举 — 不要为约束值接受任意字符串

☐在所有工具中标准化错误响应格式

☐如果使用 MCP 暴露的工具，将 Schema 与 MCP 服务器清单对齐

☐在生产中每次工具调用前添加 Schema 验证

☐使用 QVeris Inspect 在 Agent 工具选择前验证 Schema 兼容性

让每次工具调用都经过 Schema 验证使每个工具调用都经过 Schema 验证

QVeris Inspect 在发现时验证工具 Schema — 在您的 Agent 承诺调用之前。及早捕获不匹配，路由到兼容工具，并保持 Agent 工具执行的可靠性。Discover 和 Inspect 永久免费。

构建安全的 AI Agent →查看QVeris文档

常见问题

为什么 JSON Schema 在函数调用中很重要？

JSON Schema 定义工具输入和输出的结构 — 什么参数是必需的、允许什么类型、什么格式有效。没有它，Agent 会产生幻觉参数，工具在运行时因不透明错误而失败，输出变得不可靠。Schema 是Agent 推理层和工具执行层之间的契约 — 它是生产 AI Agent 最有影响力的可靠性改进。

AI Agent 可以不使用 JSON Schema 吗？

可以，但可靠性显著下降。没有 Schema 验证，Agent 猜测参数名称和类型。symbol 变成 ticker。interval 变成 1day 而不是 1d。这些失败发生在 API 层而非推理层，使其难以调试。Schema 验证在任何 API 调用之前捕获这些不匹配 — 这就是为什么它对生产级系统不是可选的。

MCP 会取代 JSON Schema 吗？

不。MCP 使用 JSON Schema 作为在服务器清单中描述工具输入和输出的格式 — 它是 MCP 服务器声明其工具接受什么参数的方式。MCP 标准化了 Schema 的暴露方式；JSON Schema 定义了 Schema 的内容。它们一起工作：MCP 是协议层；JSON Schema 是内容格式。

大多数函数调用失败由什么导致？

不正确或不完整的 Schema 定义。最常见的问题：缺失必填字段（模型省略关键参数），使用 any 或自由文本类型的弱类型（模型发送错误格式），没有枚举约束（模型编造 API 不接受的值），不一致的输出 Schema（工具返回意外格式），以及没有错误 Schema（Agent 无法确定是重试还是回退）。

QVeris 如何帮助处理 JSON Schema？

QVeris 在 检查阶段运行 — 它在发现时验证工具 Schema，在 Agent 承诺调用工具之前。如果工具的输入 Schema 需要 Agent 无法提供的字段，或其输出 Schema 与 Agent 工作流期望的不匹配，QVeris 会路由到兼容的回退方案，而不是尝试必然失败的调用。QVeris 不定义 Schema；它检查并验证它们。