最近一段时间，手边隔三差五就有刚入行做 AI 应用的朋友甩来一句话：“网上聊 Agent 的都说得天花乱坠，但我连 Agent 到底是什么都没想明白。”这个感觉我太熟悉了。Agent 这个词，一边被营销文案染得五颜六色，一边又在工程圈里迅速“祛魅”——尤其当 Anthropic 官方关于 Agent 架构的文档陆续出来之后，所谓“智能体”的拼图才真正清晰起来。这篇指南就是我把这些内容消化之后的一份个人梳理：既讲清楚 Anthropic 那套 Agent 架构观是什么，也附上我从零跑通一个 Agent 原型、再到接上 MCP 工具链的完整过程。适合还没写过一行业务级 Agent 代码、但想认真上手的开发者，也适合已经跑过 Demo、却总觉得哪里不对劲的初学者。
1. 先把“Agent”这个词拆明白：为什么同一句话指的东西完全不一样
1.1 从“万能模型”的想象到工程上的清醒定义
在真正开始写 Agent 之前，我建议你先做一件事：把脑子里那个“什么都懂、什么都能干”的科幻形象删掉。因为工程语境里的 Agent，并不是一个比大模型更聪明的存在，它只是一个“由模型驱动、能自行决策下一步动作”的软件系统。Anthropic 把这种现象描述得很直白：开发者在构建 AI 应用时，实际上只有两种结构可选——一种是 Workflow（工作流），一种是 Agent（智能体）。
Workflow 是“预先写好的代码路径”在控制流程，LLM 只是其中某个环节的决策者。比如一个客服工单分类系统，代码先判断工单类型，再让模型对不同的类型做不同格式的回复，这个流程是开发者在部署前就定死的。Agent 则反过来，是模型在运行过程中自己决定“下一步该做什么”——调用哪个工具、按什么顺序做、做到什么程度算完成，都由模型根据当前上下文临时决策。你给它一个目标，它用你提供的工具去拆解路径。
我最早犯的误解就是：觉得 Agent 一定比 Workflow 高级。后来才发现这完全不对。Anthropic 给的建议恰恰是“能用 Workflow 解决就不要上 Agent”，因为 Agent 把决策权交给了模型，随之而来的是不确定性、成本放大和调试难度的上升。
1.2 Workflow 与 Agent：生产线和现场工人的区别
为了让自己和团队里不写代码的同学都能快速理解这条分界线，我常用一个类比：Workflow 是一条固定生产线，零件从 1 号工位流到 5 号工位，每道工序做什么是提前设定的，生产线不会因为某个零件比较特殊就自发调整顺序；Agent 则像一个有临场决策权的现场工人，他手里有工具箱，老板只告诉他“把这批货处理好”，至于先检查哪个、用什么工具、要不要返工，他自己判断。
这个类比能解释很多工程现象。比如同样是“写一篇产品宣传稿”，如果用 Workflow，你的代码会先给模型一个写稿指令，再给另一个模型做审校，最后交给第三个模型按固定格式输出；如果用 Agent，你只给它“写一篇宣传稿并最终交付 Markdown 文件”的目标，它会自己决定先搜索产品资料、再拟定大纲、然后写稿、再自我检查格式。哪个更灵活一目了然，但哪个更难预测也一目了然。
所以我在看 Anthropic 的实践建议时，最深的感受是：他们并不鼓励开发者把 Agent 当默认选项，而是把 Agent 定位成“当任务的灵活性和开放性足够高、且你有办法约束模型行为时，才值得使用的架构”。初学者的第一步，应该是分清自己手里的任务属于哪一类，而不是急着把循环写起来。
1.3 两个容易误导初学者的说法
第一个说法是“只要调用了底层模型，就算做了个 Agent”。这种理解把 Agent 的复杂度严重低估了。只调一次模型，拿到结果就返回，那是普通的 API 调用，连 Workflow 都算不上，更谈不上 Agent。真正的 Agent 一定包含“模型决定动作 -> 代码执行动作 -> 把结果喂回给模型 -> 模型再决定下一步”这样的循环。
第二个说法是“Agent 可以自动纠正一切错误”。在实际运行中，模型可能会连续调用同一个工具、可能陷入重复输出、也可能在一半的时候把任务改得面目全非。如果你没有给循环设置上限、没有对工具调用结果做校验，Agent 的“自主性”很快就会变成你的运维噩梦。我的结论是：把 Agent 当做一个需要谨慎设计的状态机，而不是一个信得过的实习生。
2. Anthropic 眼中的 AI 应用分层地图：从模型到 Agent 到底差了几步
2.1 先认清你站在哪一层
当我第一次认真翻 Anthropic 的工程实践相关材料时，发现他们并不直接教你“怎么写 Agent”，而是先给了一张地图——把模型能力、AI 应用、Agent 这三个层次分开。我在这里把它转成一张我自己能看懂的层级图，可能是初学者最容易忽略的部分。
最底层是模型本身的能力：文本生成、代码生成、视觉理解、长上下文、扩展思考等。这一层只解决“模型能不能理解并生成合理内容”的问题。第二层是 AI 应用：你在应用里调用模型来做某个明确的功能，比如客服问答、文档总结、内容审核。应用层有价值，但它不要求复杂的决策循环，模型被“嵌”在代码里，输出结果直接呈现给用户。第三层才是 Agent：模型不再只是回答问题的工具，而是任务的执行者，它拥有工具、拥有目标、能够在多轮循环里主动推进。
这个分层最大的价值在于告诉初学者：你不需要一上来就冲 Agent。如果你只是想让网站多一个智能搜索框，那是第二层的事；如果你想让一个程序自己去读取多个数据源、比对信息并生成报告，才需要考虑第三层。
2.2 从模型能力到 Agent 的四个扩展维度
从 Claude 这个模型本身，到跑起来一个 Agent，中间到底加了什么？我梳理下来是四个扩展：工具扩展、记忆扩展、行动扩展、决策扩展。
工具扩展让模型能调用外部函数，比如搜索、计算、读文件，这是 Agent 的手脚。记忆扩展让模型能够在多轮对话之外保存和读取长期状态，比如把关键信息写到数据库。行动扩展是让 Agent 能驱动真实环境里的操作，比如发送邮件、修改配置、提交代码。决策扩展是让模型能够在多个可能的下一步里做选择，而不是只走一条预设路径。Anthropic 把这类能力统称为“Agentic”能力，所以你看他们的文档时经常会看到“Agentic”这个词，它强调的是“具备自主决策倾向”的能力，而不是某一个特定的产品形态。
明白了这四个扩展，你就明白了学习路径：先保证模型能力能用好（提示词、结构化输出），再学会加工具（函数调用、工具循环），然后考虑记忆和状态管理，最后才谈得上让模型自己规划复杂任务。
2.3 初学者应该先握住哪一层
以 Anthropic 的生态为例，现在摆在初学者面前的有几条路：直接用聊天产品快速体验、用 Agent SDK 构建自己的应用、以及直接用 API 自己写循环。我的建议是：如果你想理解 Agent 的运行机制，一定先从 API 自己写循环开始，而不是第一次就用现成框架把循环藏起来。
为什么这么说？因为 SDK 和框架帮你把“工具调用 -> 结果回填 -> 再次推理”这个循环封住了，你只看到输入和输出，感受不到每一步发生了什么。而自己写一遍循环之后，你才会真正理解：模型返回的 tool_use 请求是什么样的、为什么要把工具执行结果放在 user 消息里回传、什么时候该终止循环。这些知识是所有 Agent 开发的共同地基，早学会早受益。
3. Agent 平稳运行的三个支点：模型推理、工具调用、上下文管理
3.1 工具调用：模型的手，而不是模型的记忆
我在给团队做技术分享时经常说一句话：“不要指望模型替你执行任何操作，模型只负责决定应该执行什么操作。”这句话的核心就是工具调用机制。
你可以把工具调用理解为一种特殊的约定：模型收到用户问题后，如果在预设工具里发现有合适的函数，它不会直接回答，而是在回复里带上一段结构化的“工具使用请求”，比如“我建议调用 read_file 这个函数，参数 filepath 是‘/data/orders.csv’”。真正读文件的是你的代码，代码拿到结果后，再以消息的形式把结果交还给模型，模型才能基于真实数据继续推理。
为什么这么设计？因为模型本质上是一个基于文本的推理引擎，它没法真的去操作文件系统、数据库或网络服务，但它可以非常准确地“描述”应该调用哪个函数、传什么参数。工具调用把“想”和“做”分开了：模型负责想，代码负责做。这也是所有 Agent 架构里最关键的解耦点。
在实际实现过程中，有一个细节新手几乎都会踩：工具调用的结果必须被包装成正确的消息格式回传给模型，否则模型不知道刚才那次调用到底执行成功还是失败。在我自己的数据分析助手例子里，如果工具返回的数据超过模型上下文窗口能承载的量，还需要对结果做摘要或截断处理。这一点放到后面“上下文管理”详细说。
3.2 System Prompt：Agent 的岗位说明书
很多初学者把 System Prompt 当成“给模型加点语气”的地方，其实对于 Agent 来说，System Prompt 就是岗位说明书，是约束模型行为最重要的工具。Anthropic 的建议非常清晰：给 Agent 提供详细的指令，包括它的身份、可用步骤、限制条件、以及遇到异常时该怎么办。
我写过一个数据分析助手的 System Prompt 模板，结构大致是这样的：
你是一个数据分析助手。你的任务是帮助用户读取并分析本地数据文件。 在执行任务时，必须按照以下步骤进行：
- 先用 list_files 工具查看当前目录下有哪些文件；
- 用 read_file 工具读取目标文件的前若干行，确认字段结构；
- 基于字段结构提出分析思路，再选择相应工具执行计算；
- 给出结论时，必须引用工具返回的真实数据，禁止编造数字。 如果工具执行失败，请明确说明失败原因，并提议另一个可行方案。
这个模板的作用不是让模型显得更专业，而是把“决策空间”缩到一个可控制的范围内。Agent 的决策自由度不是越多越好，而是在边界内越高效越好。边界写在哪里，取决于你对风险的容忍度：如果 Agent 的每一步操作都会影响线上数据，那么 System Prompt 就应该写上“任何写入操作前必须向用户确认”。
我在长期实践中得到的经验是：System Prompt 要随着 Agent 的故障模式不断迭代。你每发现一种模型会犯的错，就把它变成一条指令写进去。Agent 开发与其说是写代码，不如说是“通过提示词给模型立规矩”。
3.3 上下文窗口：不是越大越好，而是够用就行
Agent 在循环过程中，每一轮的工具返回结果都会被塞进对话历史，下一轮推理时模型会重新阅读全部上下文。这就带来一个很现实的问题：上下文窗口是有限的，而工具结果往往是庞大的。
举一个实际例子。我的数据分析助手第一次原型里，read_file 工具会返回文件的前 200 行原始内容。用户让它分析一个几万行的 CSV，模型光读前 200 行就占了一万多个 token，依然没看到全局数据。循环到第三轮，我已经能明显感到模型开始“丢三落四”——它记住了前面的字段名，却忘了用户最初的要求。
后来我做了两个调整。第一个调整是缩小默认读取范围，只返回前 20 行加上一个“行数统计”字段；第二个调整是增加一个 profile_file 工具，专门返回数据的统计摘要（均值、最值、缺失值数量），这样模型既能掌握全局分布，又不需要吃掉全部原始数据。这个改动把单轮工具调用的 token 消耗降到了原来的十分之一左右，同时模型回答的准确率明显提升。
所以我说上下文管理的核心不是“把窗口做大”，而是“让每一轮输入都足够必要且高度浓缩”。给 Agent 配工具时，宁可多写几个专用小工具，也不要一个工具返回海量原始数据。
4. 从零跑通一个本地 Agent 原型：我用 Claude Agent SDK 做数据分析助手的完整过程
4.1 环境准备与选型思路
这一节给一段完整的实操记录。我建议初学者直接在本地 Python 环境里做，不需要复杂的云服务依赖。我那次选型非常简单：Python 3 以上环境、官方 SDK、一个存放测试数据的目录。没有用任何端到端大框架，就是裸写工具循环。
选型的逻辑是：我这次的目标是理解 Agent 机制，不是为了最快做出产品。所以我不介意多写几十行循环代码，因为每行代码都在帮我建立“模型只会给指令、执行靠代码”的肌肉记忆。等我自己写完一遍工具循环后，再去用 Agent SDK 的封装能力，才知道封装到底帮我省了什么。
这里补充一句：Agent SDK 提供的是构建 Agent 的组件和最佳实践，它把循环、工具注册、上下文管理这些事都做了更高层的抽象。初学者第一次搞懂循环之后，第二遍就可以用 SDK 重写同一个例子，你会立刻感受到抽象带来的便利。
4.2 一个极简的工具循环骨架
下面这段代码是一个简化版的数据分析 Agent 骨架，它只做了两件事：定义工具、循环执行模型决策。
import json from anthropic import Anthropic client = Anthropic() TOOLS = [ { "name": "list_files", "description": "列出当前目录下的所有文件。", "input_schema": { "type": "object", "properties": {}, }, }, { "name": "read_file_head", "description": "读取指定文件的前 N 行，N 不超过 20。", "input_schema": { "type": "object", "properties": { "filepath": {"type": "string"}, "lines": {"type": "integer"}, }, "required": ["filepath"], }, }, ] def execute_tool(name, args): if name == "list_files": import os return "\n".join(os.listdir(".")) elif name == "read_file_head": with open(args["filepath"], "r", encoding="utf-8") as f: return "".join(f.readlines()[: args.get("lines", 20)]) return "未知工具" def run_agent(user_prompt, max_iterations=6): messages = [{"role": "user", "content": user_prompt}] for _ in range(max_iterations): response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1024, tools=TOOLS, messages=messages, ) if response.stop_reason == "tool_use": messages.append({"role": "assistant", "content": response.content}) for block in response.content: if block.type == "tool_use": result = execute_tool(block.name, block.input) messages.append( { "role": "user", "content": [ { "type": "tool_result", "tool_use_id": block.id, "content": result, } ], } ) else: return response return "达到最大迭代次数，任务未完成" result = run_agent("请分析当前目录下的销售数据文件，告诉我总共有几行数据。") print(result)如果你第一次接触这段代码，只需要盯着三个点看：第一个是 tools 参数把能力清单交给了模型；第二个是 stop_reason 等于 tool_use 时，说明模型还想要更多信息，它返回的不是最终答案；第三个是 tool_result 必须关联到对应的 tool_use_id，否则模型无法判断结果对应哪一次请求。
我把 max_iterations 设成 6，不是因为模型六步就一定够，而是为了防止“模型陷入无限循环导致账单失控”。生产环境里这个值要根据任务复杂度、工具数量、上下文长度综合评估。
4.3 实测中的意外情况与修复
第一次跑通这个原型之后，我以为万事大吉，结果遇到了三个意外，正好可以作为初学者的避坑参考。
第一个意外是模型连续三次调用同一个工具。原因是我不小心让 read_file_head 在每次调用时读的几乎都是同一个文件，模型越读越觉得“信息不够”，于是不停重复。我最后的解法是：给每条工具结果加一行摘要，说明这个文件总行数、字段名，从而减少模型对“再读一次”的依赖。
第二个意外是工具返回内容里出现了无法解析的字符。CSV 文件字段里某个特殊符号导致读取结果在传入模型时格式错乱，模型直接忽略了后续指令。解法是在 execute_tool 里加一层文本清洗，把不可见字符剔除掉再回传。
第三个意外是用户在 prompt 里问了一个超出工具能力的问题，比如让模型“预测明年销售额”，模型手里的工具根本提供不了这个数据，但它还是基于文件前几行编造了一个结论。这正是我在 System Prompt 里三令五申“禁止编造数字”的原因。如果没有这条约束，Agent 会表现得非常自信，而它的结论可能完全不可用。
我后来给每个 Agent 原型都加了一条基础规范：所有结论必须标注数据来源，凡是工具没有提供的信息，必须明确说“不知道”。这条规范比任何调参都管用。
4.4 从裸循环切到 Agent SDK：抽象带来的效率提升
裸循环跑通后，我很快用 Agent SDK 重写了一个等价版本。SDK 最大的价值在于：工具注册不再需要手写 JSON schema 那么繁琐，循环终止、错误重试、上下文整理都内置了。你只需要定义函数，然后声明“这个函数可以被模型调用”，SDK 会在背后自动完成类型转换和消息组装。
对于初学者，我推荐这个顺序：先用裸 API 写一遍循环，再用 Agent SDK 重写一遍。前一遍建立理解深度，后一遍建立生产效率。很多人在第一步直接上了 SDK，结果出了问题根本不知道错在哪一层——到底是模型不懂怎么调用工具，还是你的工具函数本身有 bug，还是上下文里信息冲突？没有基础理解，排查会非常被动。
5. MCP：把 Agent 从“只会聊天”变成“能操作世界”的那一层
5.1 MCP 是什么：统一“插头”解决连接问题
当你的 Agent 需要访问本地文件、数据库、浏览器、外部 API 时，最原始的做法是为每一个数据源写一套专门的集成代码。这会产生一个很典型的问题：每接一个数据源，就要重新实现一套鉴权、请求、错误处理逻辑，而且这些代码往往不能复用。
MCP 解决的就是“连接”这个问题的标准化，你可以把它想象成 Agent 世界的 USB-C。以前每个设备都有自己独特的充电线，你要准备一堆转接头；MCP 定了统一协议之后，Agent 只要支持标准协议，就能连接所有实现了 MCP 服务的工具。Anthropic 在这方面的推进力度很大，这也是我在 Agent 开发中强烈建议初学者尽早接触 MCP 的原因——它不是某个模型的私有功能，而是一个跨平台的标准。
从架构上看，MCP 分两端：MCP Server 负责暴露能力，MCP Client 负责发现和调用这些能力。Agent 作为客户端，向 MCP Server 发出请求，获取“当前有哪些工具可用、参数是什么”，然后像调用本地函数一样调用这些远端工具。
5.2 写一个极简 MCP Server 并接进 Agent
下面我用伪代码展示一个非常简单的 MCP Server，它暴露一个“统计数据文件行数”的工具。这里不贴过度复杂的实现，只让你理解 MCP 的注册逻辑。
from mcp.server.fastmcp import FastMCP mcp = FastMCP("文件统计助手") @mcp.tool() def count_lines(filepath: str) -> str: """统计指定文件的文本行数。""" with open(filepath, "r", encoding="utf-8") as f: total = sum(1 for _ in f) return f"文件 {filepath} 共有 {total} 行" if __name__ == "__main__": mcp.run()这段代码看起来就是普通的 Python 工具函数，但关键在于：它通过 MCP 的注册机制，把函数的名字、参数、说明暴露给了任何支持 MCP 的 Agent 客户端。你的 Agent 不需要关心这个文件是本地还是远程，不需要单独写一套文件访问逻辑，它只需要知道“有一个工具叫 count_lines，传入文件路径就能得到行数”。
我这个例子不是为了展示 MCP 的全貌，而是想说明一个道理：MCP 的价值是让“工具生态”标准化，从而让 Agent 的能力边界快速扩展。你写好一个 MCP Server，它可以被多个 Agent 应用复用；别人也写好了 MCP Server，你也可以直接接入，不用重复造轮子。
5.3 MCP 配置里最常见的坑
我接 MCP 的过程并不顺利，至少踩过三个层面的坑，在这里分享给你。
第一个坑是“工具返回太随意”。MCP Server 里的函数最好不要直接返回一个 Python 对象，因为协议传输是文本化的。如果返回了复杂的嵌套结构，Agent 客户端可能理解不了。我后来统一约定：所有工具都返回简洁的文本或 JSON 字符串，并尽量带上可读性摘要。
第二个坑是“权限边界模糊”。让你的 Agent 连接一个 MCP Server，等于给了模型一把新钥匙。我之前为了让 Agent 能读数据，给它挂了文件系统的 MCP Server，结果模型在循环里试图读取各种系统文件。虽然我加了路径校验，但这种风险提醒我：MCP Server 内部要做好权限控制，不是所有暴露给模型的工具都允许自由调用。给模型的工具越少，出错的概率越低。
第三个坑是“配置了但 Agent 没感知到”。有时候 MCP Server 已经启动，但 Agent 没有正确发现工具，或者工具发现列表缓存没有刷新。遇到这种情况，先别急着改 Agent 代码，检查连接配置是否生效，再确认工具是否出现在可用工具列表里。排查 MCP 问题的最好手段是分开验证：先用 MCP 客户端直接连接测试，确认工具本身可用，再去检查 Agent 侧是否成功加载。
6. 初学者最容易踩的五个坑，和我现在坚持的“先 workflow 后 agent”原则
6.1 五个教训，每个都是真金白银换来的
把这段时间的实操浓缩一下，我认为初学者在 Agent 开发上最容易踩五个坑。
第一个坑是“一上来就做开放式 Agent”。你可能觉得任务越复杂越能体现 Agent 的价值，但实际结果是：模型很容易在一个分支里来回打转，你甚至说不清它下一步要干嘛，也无从验收。正确做法是先给 Agent 一个边界明确的小任务，比如“读取指定目录的最后一个 CSV 并生成统计摘要”，跑通了再逐步放开自由度。
第二个坑是“忽略了工具输出的体积”。很多新手只关心工具能返回什么，不关心返回结果占用多少 token。工具结果一多，后面的推理质量直线下降。我的原则是“工具输出宁精勿多”，能用摘要表达就不要给全量，能返回路径就不要返回内容。
第三个坑是“循环没有上限，成本失控”。模型陷入无限循环的概率比你想象的高，尤其当你给的工具数量很多、任务描述模糊时。每次调用都是真金白银，没有止步条件的 Agent 等于一台没有刹车的车。我在生产环境的 Agent 里不仅设置了最大迭代次数，还设置了单次任务的时间预算和 token 预算。
第四个坑是“把上下文窗口当记忆数据库”。模型并不记得上一次任务结束时的任何东西，Agent 只是在一个请求内通过对话历史来模拟记忆。如果你希望 Agent 跨会话记住用户偏好或历史结论，必须显式把关键信息存到外部存储。许多人误以为“它能记住”是因为单次会话足够长，这其实是一种错觉。
第五个坑是“用肉眼观察替代验证”。很多初学者跑通一个 Demo 后，发现模型看起来“挺对”，就直接部署了。Agent 的输入空间极大，你看到的几次成功可能只是冰山一角。我给自己定的流程是：每一个 Agent 功能都必须配套至少五个验证用例，覆盖正常输入、边界输入、错误输入三个类型，然后再谈上线。
6.2 我现在做技术选型时的判断顺序
踩完这些坑之后，我给自己总结了一条非常实用的选型原则，这里分享出来。
第一，如果任务只有一个步骤、决策空间很小，直接用普通的模型 API 调用就行，连 Workflow 都不需要。第二，如果任务需要两步以上、但步骤可以预先确定，优先用 Workflow，用代码把流程固定下来，这样每一步都可以单独测试、单独回滚。第三，如果任务步骤确实不固定、且每一步都依赖于上一步的结果，这才考虑 Agent。第四，即使决定用 Agent，也要尽量把任务拆小：一个 Agent 只负责一个大环节，而不是让一个 Agent 从头到尾接管所有事情。
这条原则本质上是把 Agent 当成“最后手段”，而不是“默认选项”。Anthropic 官方建议的主旨也是如此：智能体是强大工具，但只有在真正需要灵活性时才值得付出不确定性成本。
6.3 一条适合初学者的学习路线
如果你看完这篇指南准备上手，我建议你按下面这条路线走，而不是从第一篇热门教程跳到另一篇。
第一步，先用裸 API 写一个最简单的工具调用循环，让模型调用一个自定义函数，比如计算字符串长度。这一步的目的是理解 tool_use 和 tool_result 的机制。第二步，用 Agent SDK 重写同一个例子，感受抽象带来的效率提升。第三步，自己动手写一个 MCP Server 并接入到 Agent 里，把工具从“本地硬编码”扩展成“标准协议服务”。第四步，用 Workflow 把一个真实的业务流程过一遍，比如 PDF 信息提取、邮件分类、数据清洗，为每一步配上验证用例。第五步，才把一个需要临场决策的环节拆出来，用 Agent 去驱动它。到这一步，你已经明白 Agent 的优劣势，不会盲目崇拜它。
我在实际使用中感受最深的一件事是：Agent 开发的技术门槛没有想象中那么高，真正的门槛在于“你是否愿意花时间观察模型在循环里的每一次行为”。很多问题不是模型不够聪明，而是开发者在设计阶段没想清楚边界、工具和验证方式。希望这份指南能帮你少走一段弯路，也欢迎你在实践后回来交流你的踩坑记录。
