01 · 框架全景图

🎯 难度：中级⏱ 预计：30 分钟# 选型# 生态# 权衡

你已经手写过循环，现在再看框架。它们是工程工具，不是学习 Agent 的前置条件。

按问题选工具，不按热度选

工具 / 生态	主要关注点	什么时候考虑
OpenAI Python SDK	模型 API 和协议对象	小型项目、需要自己控制循环
LangGraph	状态图、路由、检查点、中断	长任务、可恢复流程、人工确认
LangChain	模型、工具、检索集成与高层抽象	想减少不同服务的适配代码
LlamaIndex	文档、检索与知识工作流	数据连接、RAG 为主的应用
OpenAI Agents SDK	Agent、工具、handoff、tracing	符合其模型与 API 能力约束的应用
CrewAI 等协作框架	角色和任务协作	职责确实可以拆分的流程
AI SDK / Mastra	TypeScript 应用与 Agent 生态	想把已有前端/Node 经验直接用起来

这些定位会重叠，版本演进也会改变边界。不要同时学习所有框架。本教程重点学 LangGraph 的状态图，以及独立于框架的 MCP 协议。

Python 是重要路线，不是唯一答案

Python 在 AI 数据、模型与研究生态中非常常见；TypeScript 在全栈 AI 产品、交互层和 Node 工具链中也很实用。没有必要把 Python 当作不可替代的门槛，也不需要宣称学完几课就「掌握所有生态」。

对你来说，推荐组合是：Python 理解与实现 Agent 核心，JS/TS 发挥前端交互优势，按项目需求决定服务端语言。

使用框架前问五个问题

1. 我需要的模型支持哪些 API 能力？集成是否覆盖？
2. 我能看到底层 messages 和工具结果吗？
3. 状态如何持久化、恢复和隔离用户？
4. 如何限制循环、超时、调用次数和费用？
5. 框架失效时，我能否绕过它诊断？

不要把业务规则完全埋进 Prompt 或框架默认值里。确认、授权、支付等关键规则由程序掌控。

版本与复现约定

• 基础课使用 OpenAI SDK 1.x 的 Chat Completions 接口。
• LangGraph 课使用 1.x 图 API。
• MCP 实战固定 mcp==1.12.4，展示经典 FastMCP / ClientSession 路径。MCP SDK 2.x 已有不同 API，不能混用示例。
• 各练习项目独立保存 uv.lock；升级时先跑测试，再读迁移指南。

下一课：LangGraph 入门。