Tool-Use Agent 新手训练营

这个 pack 包含什么

这是一个从没写过 function call、想把 agent 跑到生产环境的开发者会走的训练营 —— 不是 30 个框架的购物清单。每一个 pick 都有活跃的 GitHub 仓库、像样的文档、在链条里有不可替代的位置。安装顺序经过精心安排：每一个工具都为下一个铺路。

如果你已经会 Python 或 TypeScript，一个周末能把十个全部跑通。周日晚上你手里就有一个小 agent：吃一句自然语言、自己挑工具（搜索 / 邮件 / GitHub）、返回带类型的结果，CI 里有回归 eval 兜底。

推荐安装顺序

1. Fireworks JSON Mode + Function Calling on Open Models —— 从这里开始。最便宜的方式让你亲眼看到一次完整的 function-call 来回，不用先掏钱买 OpenAI。你喂一个 schema，模型返回合法 JSON，你解析。先把这个循环烂熟于心，再去碰任何框架。
2. Groq Tool Use — Llama 3.3 at 280 tok/s —— 一样的思路，速度让迭代不痛。把你在 Fireworks 上写的 prompt 直接拿来对 Groq 跑一遍，观察工具选择怎么随着模型变聪明而变化。生产环境里这也是你的备用 provider。
3. Structured Outputs — Force LLMs to Return Valid JSON —— 概念入门。JSON-mode 和 function-calling 都是「受约束生成」的特例。先读这个再上库，否则你只是在 cargo cult。
4. Instructor — Typed Structured Outputs for LLMs —— Python 侧的工效层。你定义一个 Pydantic 模型，Instructor 处理 schema / retry / validation。原生 response_format 调用的无痛替代品。装完这个，你这辈子就别再手写 JSON-schema dict 了。
5. Outlines — Structured Outputs with Any Model —— Instructor 在开源世界的表亲。Instructor 包装的是 provider 自带的 JSON 模式；Outlines 在本地做 constrained decoding（logits masking）。哪个适合你的栈就用哪个，两个都值得学。
6. Composio — 250+ Tool Integrations for AI Agents —— 当你信任了结构化输出，你需要工具去调用。Composio 自带 250+ 预制集成（Gmail / GitHub / Slack / Notion / Linear / Stripe），auth 都帮你搞定。别再第三次写自己的 send_email 包装。
7. PydanticAI — Type-Safe AI Agent Framework —— 第一个真正的 agent 循环。轻量、类型安全、Python 原生。把第 4 步的 Pydantic 模型 + 第 6 步的 Composio 工具丢进去，PydanticAI 负责 call/retry/handoff。表面积小、坑少。
8. OpenAI Agents SDK — Multi-Agent Systems in Python —— OpenAI 钦定的备选。你如果就赖在 OpenAI/Azure 上、想要 handoff/guardrail/tracing，选它更合适。比 PydanticAI 类型没那么严，但开箱即用程度更高。
9. LangGraph — Stateful AI Agents as Graphs —— 当单个 agent 循环不够用时升级到这里。带状态、可分支的工作流；显式状态机；checkpoint。依赖重、学习曲线陡，但多步研究 / 审批流 / human-in-the-loop 这些场景这就是正确答案。
10. Promptfoo — Test & Red-Team LLM Apps —— 收尾的 eval。所有用工具的 agent 都会在 provider 偷偷更新模型那天悄无声息地坏掉。Promptfoo 在 CI 里跑你的 tool-use 测试集、对 JSON schema 断言、做 prompt injection 红队。不挂 eval 别发版。

它们怎么协同

[Fireworks JSON Mode] ──┐
                         ├──► 原生受约束生成入门
[Groq Tool Use] ─────────┘
         │
         ▼
[Structured Outputs 教程] ──► 概念框架
         │
         ▼
[Instructor] ◄──► [Outlines]   ── 按栈选库
         │
         ▼
[Composio] ──► 预制工具集（Gmail / GitHub / Slack…）
         │
         ▼
[PydanticAI] ──或── [OpenAI Agents SDK]   ── 第一个真 agent 循环
         │
         ▼
[LangGraph]   ── 单循环不够用时升级到图状态
         │
         ▼
[Promptfoo]   ── CI 里跑 tool 选择 + JSON 合法性 eval

Structured Outputs → Instructor/Outlines → Composio → PydanticAI 这四件套是分水岭。这之下你在「玩 JSON mode」，这之上你在「造 agent」。顶上的 Promptfoo 别跳 —— 每个生产 agent 都会在模型更新那天悄无声息地坏，只有 eval 套件能抓到。

你会遇到的取舍

• Instructor vs Outlines —— Instructor 借力 provider 自带的 JSON/tool 模式（OpenAI / Anthropic / Gemini），又快又稳。Outlines 自己做 constrained decoding，能用在任何本地模型上但慢。OpenAI/Anthropic 用 Instructor，vLLM/Ollama 用 Outlines。
• PydanticAI vs OpenAI Agents SDK —— PydanticAI 是 provider 无关、类型严格、轻量。OpenAI SDK 自带 handoff/guardrail/tracing，但最适合你不出 OpenAI 生态圈的情况。今天才开始的新手：先试 PydanticAI。
• Composio vs 自己撸工具 —— Composio 收一个 SaaS 依赖 + 一点点延迟代价。换来的是「我又得写一遍 Gmail OAuth 流」这种重复劳动彻底消失。只有当 Composio 目录里没有那个工具，或者高频率高调用量对成本极敏感时，才自己撸。
• 过早用 LangGraph —— 新手常常一开始就上 LangGraph，因为看着唬人。别。单循环 agent（PydanticAI / OpenAI Agents SDK）覆盖 80% 场景。只有当你有显式的 human-in-the-loop / 分支 / checkpoint 需求，再考虑 LangGraph。

常见踩坑

• 没 schema 就别上 agent。工具的 input 不定类型（Pydantic / Zod / JSON Schema），模型必定幻觉字段。先定 input 再接工具。
• 工具数量隐藏代价。第 30 个工具加进去，工具选择就悄悄退化了。生产 agent 一般每个 8-12 个工具封顶，超出就路由到子 agent。
• 忘了 validation 失败重试。模型偶尔会输出能 parse 但过不了业务校验的 JSON。Instructor 自动处理；原生 response_format 不会。没有 retry 层别上线。
• 靠感觉 eval。「我试了一下没问题」不是 CI 门禁。从第一天起就装 Promptfoo —— 哪怕只有 10 个 case 也比没有强 —— 每次发现真实失败就加一个 case。
• provider 锁定泄漏到业务代码。OpenAI 的 tool 格式和 Anthropic 的 tools 块有细微差异。用 Instructor / PydanticAI / OpenAI Agents SDK 抽一层，别在业务代码里写裸的 provider JSON。