教程文档AI Agent人工智能大模型【免费下载链接】awesome-agentic-ai-zhA trilingual (繁中 / English / 简中) learning roadmap for agentic AI: from LLM basics to multi-agent systems, with 240 curated resources and hands-on examples. 中文 AI agent 學習地圖。项目地址https://gitcode.com/gh_mirrors/aw/awesome-agentic-ai-zh点击查看免费下载Function Schema函数模式是模型与程序之间共享的接口契约它决定了 LLM 在收到用户请求时是否调用工具、调用哪一个工具、填入什么参数。本文基于 awesome-agentic-ai-zh 仓库的 schema-design-cheatsheet.en.md 展开系统讲解编写工具模式的 5 条黄金规则、5 个常见反模式与 schema 演进策略并对照仓库中 Exercise 6 的 bad/good 双版本 starter 与 mock 测试给出可直接复用的设计模板、A/B 验证方法和评估结果卡。读完你将具备写出模型能靠它排除错误工具的生产级 schema 的能力。说明本文档为 Stage 3 — 工具使用与第一个 Agent Loop 的配套速查表规格核验日期为 2026-08-27 UTC。核心立场是schema 是模型与程序共享的接口清晰的 schema 能降低歧义但永远无法替代应用层的校验与固定 eval。先理解背景Schema 是模型做工具选择时最依赖的 prompt在进入规则之前先明确 schema 在 Agent 循环中的位置。Stage 3 给出的工作定义是schema → call → execute → result → answer五步循环模型读取工具名、description、schema 与对话上下文决定是否发出 Tool Call工具调用程序随后校验、执行并返回 Tool Result。关键事实有仓库文档与源码支撑Schema 本身就是 prompt 的一部分而且是模型选择工具时最依赖的那部分见 Exercise 6 README 的 Why this mattersSchema 用 JSON Schema 描述工具的信息卡名称、用途、字段与数据类型见 Stage 3 核心术语 的 Tool Schema 一节Schema 只能约束形状程序仍然必须校验值、权限与业务规则——这是贯穿全篇的铁律。黄金规则一description是写给 LLM 的不是写给人的模型不会读你的实现代码它只能通过工具名、description、schema 和对话上下文来做决策。因此描述要回答**什么时候用when 做什么what**而不是内部怎么实现。# Bad太短模型无法判断适用边界 description: Get weather data. # Good明确触发场景 明确排除场景 description: Get current weather for a specified city. Use this when the user asks about current weather, temperature, humidity, or is it raining for any specific location. Do NOT use for forecasts (use get_forecast instead) or historical data.反面示例# Bad把 description 写成实现文档 description: Uses OpenWeather API v2.5 returning JSON. # Good描述行为而非实现 description: Get current weather for a city. Returns temperature in C/F, humidity, and conditions.仓库证据在 starter_bad.py 中bad schema 的描述是Process data.与Convert a value.——如此模糊的描述会让 qwen2.5:3b 把摄氏 32 度转华氏误路由到process_data而 starter_good.py 中process_data的描述改为Use only to summarize structured JSON table rows. Do not use for temperature conversion.明确用否定句排除了温度转换场景。要点描述里同时写什么时候用和什么时候不要用是帮助模型排除错误工具的最有效手段。黄金规则二使用正确的type用enum收敛模糊参数LLM 对type: string非常宽松会把任意文本塞进去。凡是取值空间已知的参数都应尽量收紧类型模糊写法收敛写法unit: stringcelsius? fahrenheit? kelvin?unit: enum[celsius, fahrenheit]priority: stringlow/medium/HIGH?priority: enum[low, medium, high]count: stringfive?count: integerenabled: stringtrue/Trueenabled: booleantags: stringa,b,c? JSON?tags: array of string仓库证据starter_good.py中convert_temperature的 schema 正是这一规则的落地{ name: convert_temperature, description: Use this when the user asks to convert temperatures between Fahrenheit and Celsius., parameters: { type: object, properties: { value: {type: number, description: Temperature value to convert}, unit: {type: string, enum: [celsius, fahrenheit], description: Unit of the input value}, }, required: [value, unit], additionalProperties: False, }, }而 test.py 会直接断言 schema 结构good_temp[function][parameters][properties][unit][enum] [celsius, fahrenheit]且additionalProperties is False说明测试不仅看模型选没选对还检查 schema 是否真的收紧了。要点在收紧类型之外数值参数还可以叠加minimum/maximum约束如{type: integer, minimum: 1, maximum: 100}进一步缩小合法输入空间。黄金规则三谨慎处理required与可选字段在普通 JSON Schema 中required列出的是缺了就无法执行的字段有默认值 ≠ 提供方会自动帮你填默认值必须由程序显式应用OpenAI strict mode 是例外每个 property 都必须列入required真正可选的字段要用包含null的类型表示并配合additionalProperties: falseAnthropic、Ollama 及其他兼容端点的 strict mode 各不相同不要把某一家提供商的规则当成通用规则。# Bad把 timezone 列为 required → LLM 即使没被提及也会臆造 Asia/Taipei required: [city, timezone] # 非 strict schema 的正确写法 required: [city], properties: { timezone: {type: string, default: UTC, description: ...} }仓库佐证Stage 3 在讲解 Exercise 1 时特别提醒——additionalProperties: false对 schema 有帮助但Ollama 与 OpenAI strict-mode 的保证并不相同程序仍必须自行校验。也就是说兼容端点不等于行为一致这是跨 provider 开发时最容易踩的坑。黄金规则四工具名与参数名要自描述do_thing(x, y, z)与get_weather(city, unit)会产生截然不同的 LLM 行为。命名应遵循✅ 动词开头 名词宾语get_user_profile(user_id)、convert_temperature(value, unit)❌ 模糊命名fetch(id)、process_data(input)命名要能传达这是查询、变更还是动作。仓库证据bad starter 故意使用process_data(data)与convert_temperature(value, unit)但参数全为 string 且无约束模型把温度转换请求塞给process_datagood starter 中convert_temperature(value: float, unit: str)与process_data(data: list[dict], operation: str)的职责边界一目了然。黄金规则五错误必须是可恢复的当工具执行失败时程序先捕获错误再决定是否向模型返回一个最小、可行动的错误结果。错误可以结构化{ error: City not found, code: INVALID_CITY, retry_hint: Check spelling, or try a major city nearby }绝对不要只返回Error 500。各 SDK 有自己的失败标记方式Anthropic 客户端工具用is_error: true标记失败配合对应的tool_use_id回传tool_result且不能把工具结果塞进 system prompt其他 API 有各自的格式。无论哪家 provider程序都必须设置最大重试次数、超时与停止条件。Stage 3 的错误分类表可作为落地参考见 Stage 3 Exercise 5 与 examples/stage-3/05-error-handling错误类型程序首先做什么是否回传给模型网络超时/限流有界重试并记录错误通常先不传Tool Call JSON 解析失败不执行工具报告格式错误是作为错误结果未知工具/未授权参数拒绝执行留审计日志是但绝不放松权限工具查不到数据返回清晰、最小的语义错误是让模型修正或放弃达到MAX_STEPS/成本上限立即停止不重试五个常见反模式反模式一God Tool万能工具# Bad一个工具包办一切读、建、改混在一起 def do_database_op(operation: str, table: str, data: str) - str: Do anything with the database.这种工具把读、建、改全部混在一个入口里导致最小权限least-privilege配置无从下手。对策拆成职责单一的工具如query_users、create_order、update_inventory再用固定 eval 验证工具选择率是否因此提升。反模式二把 description 当 docstring# Bad写的是接口文档不是使用时机 description: GET /api/v2/weather endpoint. Returns JSON. See API docs. # Good写的是什么时候有用 description: Get current weather for a city. Returns temperature in C/F, humidity, and conditions.LLM 不读代码它要的是**这个工具何时有用**。反模式三一切皆 string# Bad模型可能传 five、yes、[a, b, c] 或 a, b, c {properties: { count: {type: string}, active: {type: string}, list: {type: string} }} # Good用真实类型 范围约束 {properties: { count: {type: integer, minimum: 1, maximum: 100}, active: {type: boolean}, list: {type: array, items: {type: string}} }}这正好呼应黄金规则二string 是一切皆可塞的逃生通道能收紧就收紧。反模式四一次成功就宣布 schema 可靠清晰的示例如description: Search products by query text, such as red shoes. Do not use for product ID lookup; use get_product_by_id.能帮助模型理解输入但证明不了 schema 可靠。正确做法准备 5–10 个用例覆盖正常、歧义与对抗性场景在相同问题集上分别跑 bad 与 good 两版 schema记录工具选择、参数合法性、程序是否拒绝了未授权输入——不要只盯着最终句子好不好看。Stage 3 Exercise 6 直接给出了可复制的结果卡模板Fixed prompt: ________________ Bad schema | success __ / 5 | main error: ________________ Good schema | success __ / 5 | main improvement: ________________ Conclusion | most helpful field: ________________反模式五静默失败如果工具失败后只返回null或{}模型可能把空数据当成成功。应显式返回状态成功 →{success: true, data: {...}}失败 →{success: false, error: ..., retry_hint: ...}需要说明这种 JSON 形状是应用层约定不是所有 API 的强制格式但程序仍必须处理模型忽略错误、反复重试或提前停止的情况。仓库中 starter_good.py 的实现正是如此——process_data与convert_temperature在失败时返回{error: ..., retry_hint: ...}结构化字典而不是空字符串。用仓库 Exercise 6 亲手验证bad vs good 对照awesome-agentic-ai-zh 的 examples/stage-3/06-schema-design 提供了两个运行路径用同一个问题把摄氏 32 度转华氏对照两种 schema。Path A默认、本地免费用 Ollama qwen2.5:3bAPI 费用 $0不含硬件、内存与电力成本pip install -r requirements.txt ollama pull qwen2.5:3b ollama serve python starter_bad.py # 观察坏 schema 如何误导 qwen 挑错工具 python starter_good.py # 观察好 schema 如何让 qwen 挑对工具Path BAnthropic云端对照每次运行先预留 $0.05费用按输入 tokens × $1/100万 输出 tokens × $5/100万计算价格核验日 2026-08-27Tool Use 还会增加 prompt tokenspip install -r requirements.txt $env:ANTHROPIC_API_KEY your-key python starter_bad_anthropic.py python starter_good_anthropic.py不花 API 额度验证逻辑mock 测试$0/次python test.py # 验证 Path A 的 starter_bad starter_good python test_anthropic.py # 验证 Path B 的 starter_*_anthropic两套测试都用unittest.mock不打真实 API且直接断言 schema 结构good 有requiredenum、bad 没有不只是看 LLM 怎么选。对照表如下设计维度BadGoodDescriptionProcess data.Use only to summarize structured JSON table rows. Do not use for temperature conversion.参数类型全部stringnumber/array/ 对应真实类型Required无[value, unit]Enum 收敛无[celsius, fahrenheit]失败返回普通字符串结构化 dict retry_hint教学观察点不同模型对 schema 质量的反应可能不同。固定 prompt、schema 与测试题用 eval 记录行为——Ollama 尤其适合观察这一差异bad/good 是否猜对、差距多大都要用固定 eval 测量。这引出一个生产结论想在生产环境用便宜模型qwen / mistralschema 必须写到能直接上线的程度。仓库还给了三个延伸练习故意删掉 good schema 的一个 enum 看 qwen 是否开始挑错新增一个与convert_temperature用途相近但边界模糊的第三工具观察选择以及把 05-error-handling 的结构化错误模式接进来形成schema 设计 错误处理的生产级组合。Schema 演进指南变更不是小事加参数之前先查 provider 规则普通 schema 可以加带默认值的可选字段OpenAI strict mode 则要求列入required并用null表示省略改变参数语义 → 发布新工具如get_weather_v2先弃用旧工具再移除而不是原地改语义改动description→ 重跑同一套 eval不要假设一小段文字改动没有行为影响上线前用 eval 工具验证对模型是否在 5–10 个典型查询中选对工具做量化评估如 promptfoo 这类 eval harness而不是凭一次成功下结论。延伸与 MCP 的关系MCPModel Context Protocol服务器同样使用工具 schema但宿主、权限与协议层与直接 Function Calling 不同见 Stage 5 — Claude Code 生态 第 5.2 节。本速查表的规则在 MCP 场景依然适用——schema 质量决定工具被发现与选择的准确率但权限边界与协议层需要按 MCP 的机制另行处理。相关仓库资料导航速查表原文resources/schema-design-cheatsheet.en.md本文档另有 繁中版 与 简中版主练习章节stages/03-tool-use-and-hello-agent.en.mdExercise 6 完整双路径examples/stage-3/06-schema-design/README.en.mdbad/good 对照源码starter_bad.py、starter_good.py、starter_good_anthropic.py结构断言测试test.py、test_anthropic.py错误处理配套examples/stage-3/05-error-handling/README.en.md学习方法论docs/HOW_TO_USE.md赞分享教程文档AI Agent人工智能大模型【免费下载链接】awesome-agentic-ai-zhA trilingual (繁中 / English / 简中) learning roadmap for agentic AI: from LLM basics to multi-agent systems, with 240 curated resources and hands-on examples. 中文 AI agent 學習地圖。项目地址https://gitcode.com/gh_mirrors/aw/awesome-agentic-ai-zh点击查看免费下载相关推荐awesome-agentic-ai-zh 实战用 Function Calling 跑通第一个 Agent 工具闭环get_weather 最小示例awesome agentic ai zh 实战用 Function Calling 跑通第一个 Agent 工具闭环get_weather 最小示例 本教程文档AI Agent人工智能大模型Flowbite 快速上手指南在 Tailwind CSS 项目中使用这套 UI 组件库与 JavaScript 交互Flowbite 快速上手指南在 Tailwind CSS 项目中使用这套 UI 组件库与 JavaScript 交互 Flowbite 是一套开源的 UI教程文档AI Agent人工智能大模型Schema Evolution 实战指南把模糊的 Function Schema 一步步修到清晰可用awesome-agentic-ai-zhSchema Evolution 实战指南把模糊的 Function Schema 一步步修到清晰可用awesome agentic ai zh 本文源自教程文档AI Agent人工智能大模型上一篇TensorFlow.NET 神经网络实现手写数字识别教程下一篇在macOS上构建Pistache框架的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考