做 AI Agent 的人最容易犯的错，是还没想清楚要不要框架，就先选了一个最重的框架。这往往让一个三行循环能解决的事，变成一坨没人敢动的图结构。这篇从「要不要框架」讲起。
要不要框架
判断标准很朴素：你的 agent 是一个循环加两三个工具，还是有多步状态、条件分支、长时间运行的任务。前者手写更干净，框架反而是负担；后者才值得上框架。很多人卡在中间，用一个简单循环硬套 LangGraph，最后发现维护成本比手写还高。一个更实用的提醒是：框架解决的是复杂度，不是 hello-world，等复杂度真出现再引入也不迟。
手写的最小实现
不引入框架时，一个带工具调用的最小循环长这样：模型先给结论，需要调工具就执行，把结果塞回上下文再问一次，直到它不再要工具为止。
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "查询城市天气",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}
]
def run(prompt: str):
messages = [{"role": "user", "content": prompt}]
for _ in range(5):
resp = client.messages.create(
model="claude-haiku-5-5",
max_tokens=512,
messages=messages,
tools=tools,
)
if resp.stop_reason == "tool_use":
for block in resp.content:
if block.type == "tool_use":
result = {"city": block.input["city"], "weather": "晴"}
messages.append({"role": "assistant", "content": resp.content})
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result),
}],
})
continue
return resp.content[0].text
这个循环把工具调用这件事讲清楚了，也暴露了手写的天花板：重试、超时、并发、状态持久化都得自己补。反过来，它也是理解所有框架的起点——框架本质上就是在这一层之上加了状态管理、可观测和重试。
框架的取舍
真到要框架，常见的是 LangGraph 和 CrewAI。LangGraph 把流程建模成显式的图，节点和边都看得见，适合有复杂状态、需要断点续跑和审计的生产场景，代价是学习曲线陡，简单线性流程也要付「图」的税。CrewAI 把 agent 抽象成有角色和目标的团队，上手快，一下午能出多 agent 原型，但长任务缺少原生 checkpoint，跑到 90 分钟撞上限流就得从头再来。还有一个常被忽略的选项是 Pydantic AI：它把 LLM 输出校验成结构化 schema，适合在 typed Python 服务里要「可靠输出」的场景。
模型无关与 MCP
这四个框架都不绑模型，Claude、GPT、Gemini 都能接，切模型不用重写 agent 逻辑。另一个趋势是工具接入越来越走 MCP，而不是各框架自己的 tool 格式——理解了 MCP，换哪个框架都能复用同一批工具。
工具设计
工具是 agent 的手脚，设计得差，框架再好也没用。几个要点：工具名和描述要写清参数、返回值和副作用，模型靠这些决定什么时候调；一个工具只做一件事，别把「查订单」和「改订单」揉在一起，让模型在副作用上出错；返回值要结构化，宁可多给一点字段，也别让模型去猜。工具设计比选框架更影响最终效果，这一点常被忽略。
可观测
生产环境里，agent 的可靠性取决于你能不能看清它每一步干了什么。给每次 LLM 调用记录输入、输出、工具调用、耗时和 token，LangSmith、Langfuse 这类平台做的是同一件事。没有这层追踪，一个五步的 agent 在第三步挂了，你只能靠猜。可观测要在上线前就接好，而不是出了事故再补。
从原型到生产
从 demo 到生产，差距不在框架而在工程化：重试、超时、限流、状态持久化、人工介入点。原型里模型偶尔答错无伤大雅，生产里一次错误的工具调用可能直接改数据。把关键操作设成需要人工确认，把长任务拆成可断点续跑的步骤，这两条比任何框架特性都更能决定系统能不能长期跑。很多团队在原型阶段堆了一堆框架，到了生产反而被框架的复杂度拖住，问题恰恰出在没先想清楚这两条。
高频坑
第一，框架混用，LangChain 和 CrewAI 掺在一起，抽象互相打架。第二，跳过可观测，上线后出问题不知道哪个 agent、哪一步、什么输入，LangSmith、Langfuse 这类追踪要在上线前接好。第三，盲目并行，一下开十个 agent，撞上限流和账单，先串行跑通再并行。这三点比选错框架更常见，也更好避免。总结一句：先把业务逻辑和框架解耦，agent 的 prompt、约束、示例单独放，框架只做调度，这样将来换框架不用重写业务。