本文是《从零到上线:Agent 应用开发完整路线图》系列第一篇。

如果你正打算做一个 AI Agent 应用,大概率会被铺天盖地的框架名称淹没:LangGraph、CrewAI、AutoGen、Dify……每个都说自己是”最佳实践”。这篇文章不想再加一个框架横向评测,而是想讲清楚一件更重要的事:Agent 应用的本质是什么,以及你应该按什么顺序学会它。

我们会从手写一个最简陋的 Agent 循环开始(没有任何框架),理解清楚之后再引入框架,最后给出一份可落地的技术选型建议。

一、Agent 到底是什么

剥离所有框架的包装,一个 Agent 本质上是这个循环:

1. 把任务 + 可用工具列表 喂给 LLM
2. LLM 决定:直接回答,还是调用某个工具
3. 如果是工具调用 → 执行工具 → 把结果塞回上下文
4. 回到第 1 步,直到 LLM 给出最终答案

这个模式有个名字,叫 ReAct(Reasoning + Acting)。所有主流框架,底层做的都是这件事的各种变体。

先别用框架:手写一个最小可用 Agent

理解原理最快的方式是自己写一遍。下面是一个完整的、可以直接运行的最小 Agent,用 Anthropic API,只依赖一个搜索工具:

import anthropic
import json

client = anthropic.Anthropic()  # 需要设置 ANTHROPIC_API_KEY 环境变量

# 1. 定义工具 —— 这是 Agent 唯一能"操作世界"的方式
tools = [
    {
        "name": "search_web",
        "description": "搜索互联网获取实时信息,比如新闻、价格、最新数据",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "搜索关键词"}
            },
            "required": ["query"]
        }
    }
]

def search_web(query: str) -> str:
    """这里用假数据模拟,实际项目接入真实搜索 API(如 Tavily、Serper)"""
    return f"关于'{query}'的搜索结果:示例新闻内容..."

def run_agent(user_message: str, max_turns: int = 5):
    messages = [{"role": "user", "content": user_message}]

    for turn in range(max_turns):
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=tools,
            messages=messages
        )

        # 没有工具调用 = 模型给出了最终答案,循环结束
        if response.stop_reason != "tool_use":
            return response.content[0].text

        # 把模型的响应(包含工具调用请求)加入历史
        messages.append({"role": "assistant", "content": response.content})

        # 执行模型请求的每一个工具调用
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                if block.name == "search_web":
                    result = search_web(**block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })

        # 把工具执行结果喂回去,进入下一轮
        messages.append({"role": "user", "content": tool_results})

    return "达到最大轮次仍未完成"

if __name__ == "__main__":
    answer = run_agent("帮我查一下今天 AI Agent 领域有什么新闻")
    print(answer)

这段代码不到 60 行,但包含了 Agent 的全部核心要素:工具定义、循环控制、终止条件、上下文累积。任何框架做的事情,本质都是把这个循环包装得更好用、更健壮。

理解了这个循环之后,你会对框架文档里那些”AgentExecutor””StateGraph””Crew”之类的抽象概念,有种”哦原来是这个”的感觉——这是阶段1最值得花的一周时间。

二、五个核心组件

不管最终用哪个框架,生产级 Agent 都要解决这五件事:

1. LLM 调用层

模型推理本身,通常是最稳定的部分,各家 API 大同小异。

2. 工具调用(Tool Use)

让模型从”只会说话”变成”能操作世界”。工具的描述质量(description)直接决定 Agent 的可靠性——这是新手最容易忽视、也是最值得花时间打磨的地方。一条经验:工具描述写得越像在给一个新同事交代任务,模型用得越准。

3. 记忆/状态管理

• 短期记忆:当前对话的上下文窗口,简单但会随轮次增长而变贵、变慢。
• 长期记忆:跨会话保留的信息,通常靠向量库做检索(RAG),或者结构化存储(如 key-value)。

4. 规划/编排(Orchestration)

任务到底要不要拆成多步?要不要多个 Agent 协作?这是最容易过度设计的地方,后面会专门讲。

5. 执行环境与可观测性

代码沙箱、浏览器自动化、文件系统访问;以及配套的日志、追踪(trace)、评估集,这些决定了 Agent 能不能从 demo 走到生产。

三、学习路线(建议顺序)

阶段 1:理解原理(1-2 周)

手写上面那种最小 Agent 循环,换几种工具试试(代码执行、文件读写),体会上下文是怎么累积的,故意制造一次死循环,看看不加终止条件会发生什么。

推荐精读 Anthropic 的 Building Effective Agents,这篇文章讲清楚了一个被低估的问题:很多场景根本不需要”Agent”,一个固定步骤的工作流(workflow)就够了,而且更便宜、更可控、更好调试。

判断标准很简单:如果任务的步骤你能提前列清楚,用工作流;只有当任务路径依赖运行时才能确定的信息(比如”不知道要查几次资料才够”),才真的需要让 LLM 自主决策下一步做什么。

阶段 2:用框架做出第一个可用 Agent(1-2 周)

选一个轻量框架,接入 2-3 个真实工具(搜索 + 代码执行是不错的组合)。这一阶段重点不是学框架 API,而是练这几件事:

• 工具 schema 怎么写才让模型调用更准
• 工具执行失败时怎么把错误信息喂回模型,让它能自我纠正
• 怎么设置合理的最大轮次/超时,防止失控烧 token

阶段 3:记忆与 RAG(2 周)

接入向量库(Chroma、Qdrant、Pinecone 任选)做长期记忆或知识库检索。这一步最容易踩的坑是滥用 RAG——很多时候直接把文档塞进工具、让 Agent 按需查询,比强行做向量检索更简单可靠。先问自己:这个信息是”知识库”性质,还是更像一个”可以直接查询的数据源”?

阶段 4:多 Agent / 复杂编排(2-3 周)

学习几种常见模式:

• Supervisor 模式:一个主 Agent 负责拆解任务、调度子 Agent
• 并行子任务:多个子任务互不依赖时并发执行,省时间
• Human-in-the-loop:关键决策点暂停,等人工确认再继续

同时补上可观测性——记录每一步的输入输出、工具调用、耗时,否则多 Agent 系统一旦出错,你会完全无从下手排查。

阶段 5:生产化

加护栏(校验工具调用参数、过滤危险操作)、限流、成本监控,以及一个评估集(eval set)——用一批固定的测试 case,在每次改 prompt 或换模型后跑一遍,确认没有回归。这一步最容易被跳过,但也是 demo 和生产系统最大的分水岭。

四、开源方案怎么选

方案	定位	适合场景	学习曲线
LangGraph	图编排框架(LangChain 团队出品)	需要精细控制状态流转、多 Agent、可视化流程图	中
CrewAI	多 Agent 协作框架,角色化设计	团队协作型任务(如”研究员 + 撰写员 + 审核员”)	低
AutoGen(微软)	多 Agent 对话框架	复杂多轮协商型任务、研究场景	中
LlamaIndex Agents	RAG 起家,Agent 是延伸能力	知识库密集型应用	中
OpenAI Agents SDK	官方轻量 SDK	简单可控、不想要太多抽象	低
Dify	低代码/可视化平台	快速搭建、非工程团队主导、想要 UI	低(灵活性受限)
n8n	工作流自动化平台,内置 AI Agent 节点	偏自动化集成、连接各种 SaaS	低
Pydantic AI	类型安全的轻量框架	Python 重类型校验场景	低-中
Claude Agent SDK	Anthropic 官方,Claude Code 同源能力	代码执行、文件系统操作密集的 Agent	低-中

选型建议:

• 想快速验证想法、不太想写代码 → 先用 Dify 或 n8n 跑通一个原型,验证产品逻辑再决定要不要重写
• 工程师主导、要可控性和生产级部署 → LangGraph(生态最成熟,配套调试工具完善)或 OpenAI Agents SDK(概念更少,上手快)
• 任务天然适合”多角色协作”(比如内容生产流水线:研究 → 写作 → 审核) → CrewAI
• 做编程助手/文件操作类 Agent → 直接看 Claude Agent SDK

五、一个容易被忽略的建议

不要一上来就上多 Agent 框架。

多数”看起来需要 Agent”的需求,其实用单 LLM + 工具调用 + 简单循环就能搞定——也就是文章开头那 60 行代码的思路,顶多多加几个工具。复杂度越低,越好调试、越省钱、越容易交给团队其他人维护。

真正需要多 Agent 编排的场景,通常有个共同特征:任务可以被清晰地拆成几个角色不同、关注点不同的子任务,并且子任务之间确实需要独立的上下文(比如一个负责检索资料,完全不需要知道最终输出格式)。如果你的任务达不到这个复杂度,引入 CrewAI/LangGraph 这类框架带来的额外心智负担,往往大于收益。

先把最小循环做扎实,真遇到瓶颈了,再逐步引入编排框架——这是性价比最高的路径。