作为程序员，这两年最避不开的关键词就是大模型和AI Agent。但说实话，我见过太多人停留在“调API、发聊天”的阶段，拿到Agent相关的教程要么太偏理论，要么就是某个框架的广告软文，真正能动手跑起来的少之又少。这一篇我打算换个讲法：不空谈概念，也不依赖任何特定平台或供应商，直接带你把一个能联网搜索、会自己拆任务、带长期记忆的调研型Agent从零写出来。你跟着流程走完，既能理解Agent的工作原理，也能自己动手改造成适合业务场景的版本。这篇内容比较长，值得先收藏再慢慢看。
1. 为什么程序员都要学AI Agent
1.1 从“对话框”到“数字员工”：Agent到底是什么
先说一个我自己的观察。前两年大家玩大模型，最多的是让AI帮忙写代码、写文案、翻译，本质上还是“我问一句，它答一句”的对话模式。这种模式最大的问题是：模型再聪明，也只是一个“没有手脚的大脑”。它不能帮你查实时天气，不能帮你操作Excel，不能在你问完一个问题后主动去数据库拉数据再算一遍。一句话，它能说，但不能做。
AI Agent（智能体）解决的就是这个问题。你可以把Agent理解成一个“数字员工”：它有一个大脑（大模型），有手和脚（能调用各种工具），有记性（短期和长期记忆），还会自己安排工作步骤（任务规划）。当你交给它一个目标，比如“帮我调研一下某领域最新的技术动态，整理成一份带来源的报告”，它不会只给你一段泛泛而谈的文字，而是会自己拆解成“搜索资料、筛选来源、阅读摘要、生成报告”这几个步骤，一步步做完整。
之所以说程序员必须学这个，是因为Agent是当前大模型落地最实用的形态。做工具类产品、做自动化脚本、做内部知识库问答，甚至做自动化测试，都开始用Agent来串流程。早一步掌握它的设计思路，对职业发展确实有实打实的好处。
1.2 什么场景真正需要Agent
我见过不少团队把Agent用错地方。比如一个简单的意图分类，明明用一次带示例的提示词就能解决，非得套一个Agent框架，结果又慢又贵。真实需要Agent的场景，通常有两个特征：一是任务本身有多个步骤，二是流程中存在模型自己搞不定的外部操作。
举几个我实际接触过的例子：
- 运维告警处理Agent：收到告警后，自动去查监控数据、翻历史工单、定位变更记录，最后给出可能的故障原因和处理建议。
- 文档审阅Agent：拿到一份合同或技术方案，自动对照规范库逐条检查，发现问题就标记出来，并引用规范原文。
- 数据归因Agent：业务指标出现波动时，自动拉取多个数据源的报表，做一轮多维度交叉分析，生成归因报告。
这些任务的共同点是：光靠大模型“想”是不够的，必须通过API、命令行、数据库、浏览器等工具去“做”。而这恰恰是Agent的用武之地。搞清楚这些场景，你就知道学Agent不是追热点，而是围绕真实需求去解决“模型与外部世界连接”的问题。
2. Agent核心架构拆解：五个模块看懂本质
2.1 大脑：模型选型与提示词角色定位
所有Agent的中心是一个大模型，它承担“决策中枢”的角色。选型上，如果任务涉及复杂的推理和工具调用，优先选支持函数调用即Function Calling能力较强的模型，因为这类模型被专门训练过输出结构化的调用指令，准确率高不少。如果只是简单的文本分类或问答，用轻量模型成本更低，速度也更快。
除了模型能力，提示词的角色定位也很关键。我在写Agent的System Prompt时，通常会明确三件事：第一，告诉模型它现在是一个Agent系统的大脑，负责根据当前目标决定下一步做什么；第二，要求它在信息不足时主动选择调用工具，而不是凭记忆编造；第三，要求它在每次行动后输出一句话小结，方便我通过日志追踪它的思路。
提示词模板的大致结构如下：
你是智能体的大脑。你的任务是完成用户给定的目标。 你有以下工具可以使用： - search_web(关键词)：搜索最新资料 - fetch_page(链接)：读取网页正文 - save_note(标题, 内容)：保存阅读笔记 每次决策请输出：thought（思考过程）+ action（工具名）+ action_input（工具参数）。 当你认为目标已完成时，输出 final_answer。这样做的好处是，让模型的行为可预期、可调试。模型第一步做什么、第二步做什么，每一步用了什么工具、拿到什么结果，都是明明白白的，出现问题时一眼就能定位到是哪一步决策错了。
2.2 手脚：工具调用与Function Calling机制
工具调用是Agent区别于普通聊天最关键的能力。常见的实现方式有两种。
第一种是让模型直接输出一段要执行的动作文本，比如search_web(query="xxx")，程序收到后用正则或解析器拆出工具名和参数，再执行对应的Python函数。这种方式虽然简单，但模型容易写错参数格式，稳定性和安全性都差一些。
第二种是主流大模型厂商都支持的 Function Calling 机制。你在请求里以JSON Schema的格式声明工具有哪些、每个参数是什么类型、哪些必填，模型在自己需要数据时，会返回一个结构化的“调用请求”，而不是普通文本。程序只需要按这个结构化数据去执行函数，然后把结果填回对话里就好。这种方式错误率低，也更安全，因为参数边界是定义好的。
我实践下来，工具定义有几个要点：
- 工具说明要写清楚“什么时候用”和“参数含义”，不要只写参数类型，模型非常依赖这些描述来判断调用时机。
- 工具返回结果尽量精简，避免把整个网页原始HTML塞回上下文，后面会讲到上下文窗口的问题。
- 每个工具要有失败返回的约定，比如搜索失败后返回
{"error": "timeout"}，模型看到错误信息后会决定是重试还是换方案。
2.3 记忆：短期工作区与长期知识库
Agent的记忆分两层。短期记忆就是对话上下文本身。在单轮任务中，Agent每执行一步，结果都会追加到上下文里，所以它能记住刚才搜索到了什么、下一步该干什么。这个机制简单，但代价是上下文是有限的，累积太多内容就会把窗口撑爆。
长期记忆则复杂一些。Agent需要跨对话记住用户偏好、历史结论、业务规则等。一个小而清晰的实现方式是把文本切成块，做向量化后存进向量数据库，需要时通过语义相似度检索相关片段回填到上下文。之所以要检索而不是全部塞进去，是因为人脑工作记忆也是有限的，只会把“当前需要的那部分知识”临时调出来用，这个类比放到Agent上同样成立。
实际搭建时，按照这个规则来：
- 任务过程中的中间结论，放短期记忆里就好，任务结束就能丢。
- 需要长期复用的知识（比如团队的代码规范、用户的写作风格偏好），才写入长期记忆。
- 写入之前做一次去重和压缩，避免向量库里堆积大量低质量重复内容。
我踩过的坑是，一开始把所有搜索历史都写进长期记忆，没过多久向量库就满了，检索结果全是旧内容，信噪比很低。后来改成只有“被最终报告引用到的结论”才写入，效果好很多。
2.4 规划：任务分解与自我反思
规划能力决定了Agent是“指一步走一步”还是“一次自主跑完”。最简单的是“单次规划”方式：拿到用户目标后，让模型先输出一个完整步骤清单，然后程序按顺序执行，每完成一步再让模型生成下一步。这种方式可控性强，适合流程固定的场景。
更灵活的是“动态规划”方式：模型每完成一步，就根据当前结果重新决定下一步做什么。比如搜索后发现某个方向资料太少，就自动换关键词再搜一轮；读到一篇有争议的博客，就主动再去查两篇对比。这种方式更像人做事的习惯，但对模型能力要求更高，也更容易出岔子，需要给循环次数设上限。
另外，规划里还藏着一个关键能力：自我反思。每次行动之后，让模型用一句话总结“这次行动是否有效”，如果连续两次行动没有得到有效信息，就让模型换个思路，而不是在原地打转。这个小技巧帮我解决了很多Agent“钻牛角尖”的问题，后面调试部分会展开说。
2.5 协作：多Agent的分工模式
单个Agent在复杂业务场景下常常手忙脚乱，所以多Agent协作逐渐成了标配。最经典的主从模式是：一个“主管Agent”负责接收任务、拆解分配、汇总结果，几个“执行Agent”各自负责一个专业方向，比如代码审查Agent、资料检索Agent、报告撰写Agent。
多Agent协作在技术上并不神秘，本质是Agent与Agent之间通过消息队列或共享状态来传递任务目标与结果。好处是专业分工明确，提示词可以写得非常聚焦，坏处是上下文传递有开销，而且沟通调度的复杂性成倍增加。我的建议是：优先把一个Agent的能力打磨成熟，再考虑拆分多Agent。一上来就做多Agent协作，很容易陷入互相等待、消息丢失的泥潭。
3. 环境准备与方案选型
3.1 开发环境清单
动手之前，先把环境理清楚。Agent开发本质上是写Python程序，所以基础的Python环境就够用，不需要什么特殊的IDE。我的开发机配置很普通，只要网络能连通大模型API就能跑。
你需要的核心工具包括：
- Python环境：建议3.10以上，类型注解和语法糖用起来方便。
- 大模型API：选择支持Function Calling的模型服务，准备好密钥。各个厂商的API大同小异，代码里做一层统一封装即可。
- 网络请求库：使用标准的requests或httpx就能满足工具调用需求。
- 向量数据库：本地开发阶段完全可以用内存向量库代替，就是把向量存进一个字典，数据量大再换正式数据库。
- 日志与调试工具：最简单的方式就是print，但走到稍微复杂的任务时，建议启用标准库logging，按模块记录Agent每步动作，排查问题会省非常多时间。
3.2 框架选型：编排框架与自研轻量实现的取舍
现在市面上的Agent编排框架不少，有的功能强大，学了能用很久；有的上手快但过度封装，出了问题很难排查。我的建议是：先不要碰任何框架，用几百行代码把核心流程写一遍。等你亲手实现过主循环、工具解析、记忆管理这三块核心逻辑，再看框架的源码就会一目了然，知道它帮你封装了什么、隐藏了什么，出了问题也能顺着日志定位到对应机制。
自己动手的好处很直接。
第一，你完全清楚整个系统的数据流——用户消息进入后去了哪里，工具返回结果在哪个环节被处理，上下文是怎么拼接的，排查问题不用靠猜。用框架时遇到诡异问题，往往只能上网搜类似问题再自行测试，定位成本高得多。
第二，遇到超出框架预设的功能需求，你可以直接改代码。比如有些任务需要工具调用的中间结果按特定格式做缓存，自研方案里只需要加一个装饰器就能搞定，框架方案却要学它的插件机制。
第三，不用背上沉重的依赖体积。框架通常自带大量你用不到的功能模块，版本一升级可能就有兼容问题，自研轻量实现完全杜绝这种隐患。
当然，自研不是万能的。如果项目工期紧、团队又刚接触Agent，那么适度使用成熟框架也是合理的。关键是带着“理解原理”的心态去用，而不是把框架当成黑盒。
4. 实战：30分钟搭一个选题调研Agent
4.1 需求定义与总体流程
我把这个示例的目标定为：输入一个调研主题，Agent自动完成搜索、阅读、整理、报告四个环节，最后输出一份带来源链接的调研简报。
整体流程这样设计：
- Agent先确认调研主题和范围，拆出几个子方向。
- 对每个子方向调用搜索工具，获取候选网页链接。
- 逐个读取网页正文，提取关键信息，以结构化条目形式保存。
- 汇总所有信息，按引言、现状盘点、观点对比、资料来源四个模块生成简报。
为了便于复现，我不依赖任何第三方大模型封装库，直接写一个统一的LLM响应处理函数，用JSON格式与模型交互。模型调用部分你换成自己用的服务即可，逻辑完全不动。
4.2 定义工具：让Agent拥有搜索和摘要能力
先把工具层写清楚。这里我用两个纯Python函数来模拟真实的工具能力：一个负责聚合搜索结果（实际场景换成你用的搜索API），另一个负责读取网页并做简单清洗。
需要说明的是，搜索API的接入每个厂商都有自己的密钥和鉴权方式，但思路一致：构造请求、解析返回结果、提取标题与链接。
import json import re import requests def search_web(keyword: str) -> dict: """模拟搜索接口：返回与关键词相关的网页标题和链接。""" # 这里可以替换为实际的搜索服务调用，例如调用某个公开的搜索接口 # 出于演示目的，我们先在本地构造两条模拟结果 mock_results = [ {"title": f"{keyword} 入门教程", "url": f"https://example.com/{keyword}-intro"}, {"title": f"{keyword} 最新实践", "url": f"https://example.com/{keyword}-practice"} ] return {"results": mock_results} def fetch_page(url: str) -> dict: """抓取网页正文，去掉标签后截取前2000个字符。""" try: resp = requests.get(url, timeout=10) text = re.sub(r"<[^>]+>", "", resp.text) return {"content": text[:2000]} except Exception as e: return {"error": f"页面抓取失败: {e}"}你可能觉得这个搜索工具太“假”了，但我要强调的是，工具实现本身不是重点，重点是“工具的输入输出契约”。只要搜索结果以JSON返回、页面正文能被清洗截断、失败时有明确的error字段，主循环完全可以正常工作。
4.3 实现主循环：思考-行动-观察
Agent的核心主循环是“思考-行动-观察”。拿到用户目标后，把当前对话历史发给模型，让模型产出结构化动作，程序执行动作，将结果加回对话历史，再交给模型做下一步判断，直到模型输出最终答案或达到最大步数。
我用下面的伪代码来实现这个循环，关键交互逻辑都放在call_llm函数里，这个函数默认模型返回JSON结构体。
def call_llm(messages, tools=None): """调用大模型接口，返回结构化结果。 实际项目中把这段换成你自己使用的大模型服务的API请求即可。 """ # prompt与tools会拼进请求体 prompt = build_prompt(messages, tools) # 以流式或一次性方式拿到响应 response = requests.post(LLM_ENDPOINT, json={"prompt": prompt}) # 默认要求模型按JSON格式输出 return response.json()主循环逻辑大致是：
def run_agent(user_goal: str, max_steps: int = 8): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_goal} ] tools = { "search_web": search_web, "fetch_page": fetch_page, } for step in range(max_steps): response = call_llm(messages, tools=tools) action = response.get("action") if action == "final_answer": return response["result"] tool_name = action.get("tool") tool_args = action.get("args") print(f"[step {step}] 调用工具: {tool_name}({tool_args})") # 执行工具调用，并把观察结果回填到上下文 result = tools[tool_name](**tool_args) messages.append({"role": "tool", "name": tool_name, "content": json.dumps(result)}) return "达到最大执行步数，任务未完成"这段代码里最关键的设计有三点。第一是每一轮模型输出都要求带action字段，它能区分该调用工具还是直接给出最终答案。第二是工具执行结果会以role: tool的形式回填到消息列表，模型下一轮就能看到刚才的工具反馈，再决定下一步动作。第三是步数上限，它避免Agent在一个问题上无限循环，宁可多设几个安全阀也不能让它失控跑飞。
4.4 加上长期记忆：让Agent记住你的偏好
主循环能跑通之后，我再给它加一个“长期记忆”模块。这里的实现不依赖任何数据库，用一个本地JSON文件来持久化，适合快速验证。
import hashlib import json import os MEMORY_FILE = "agent_memory.json" def generate_embedding(text: str) -> list: """生成文本的向量表示。 实际项目中会用专门的向量模型生成embedding，这里用hash做降维替代。 注意：这里仅演示流程，真实场景请使用正规的向量化接口。 """ return [float(hashlib.md5(chunk.encode()).hexdigest(), 16) % 1e6 for chunk in text.split("。") if chunk] def save_longterm_memory(key: str, content: str): """将Agent确认有价值的结论写入长期记忆。""" memory = {} if os.path.exists(MEMORY_FILE): memory = json.load(open(MEMORY_FILE)) embedding = generate_embedding(content) memory[key] = {"content": content, "embedding": embedding} json.dump(memory, open(MEMORY_FILE, "w", encoding="utf-8"), ensure_ascii=False, indent=2) def recall_memory(query: str, top_k: int = 3) -> str: """根据问题检索最相关的历史结论。""" if not os.path.exists(MEMORY_FILE): return "" memory = json.load(open(MEMORY_FILE)) query_embedding = generate_embedding(query) # 这里简化处理：直接按关键词重叠度排序，替代向量余弦相似度 scored = [] for key, item in memory.items(): score = len(set(key) & set(query)) scored.append((score, item["content"])) scored.sort(reverse=True) return "\n".join([c for _, c in scored[:top_k]])坦白说，上面代码里的generate_embedding只是一个非常粗糙的占位实现，真正生产环境一定用专门的向量模型和向量检索库。但我想通过这个示例让你理解“记忆”的定位：它在每次循环开始时，把历史摘要和用户的固定偏好插进System Prompt，让Agent在做决策时能参考过往经验，而不是每轮对话都从零开始。理解了这一点，你后续换任何成熟组件都只是替换接口的事。
4.5 调试与运行实录
代码写完后，我建议立刻用一个具体主题跑一遍，比如“大模型幻觉缓解技术”。运行过程中，我会在每步打印日志，从日志里能看到Agent内部到底在做什么。
我自己跑出来的一个运行片段大致是这样的：
[step 0] 决策：先搜索整体现状 [step 0] 调用工具: search_web("大模型幻觉 缓解 技术 综述") [step 1] 决策：阅读第一篇搜索结果 [step 1] 调用工具: fetch_page("https://example.com/llm-hallucination-survey") [step 2] 决策：搜索结果里提到了“检索增强生成（RAG）”，需要再确认RAG常见方案 [step 2] 调用工具: search_web("RAG 幻觉缓解 实践") [step 3] 决策：信息已经足够，开始整理报告 [step 3] 输出 final_answer这个输出虽然只有几行，但说明Agent具备基本的“动态规划”能力：它没有照着预设的僵硬流程一步步走，而是会根据上一步的结果调整下一步动作。发现“RAG是关键方向”之后，它主动发起了第二轮搜索，而不是拿着旧结果糊弄过去。这种表现就是“Agent感觉”的来源——模型有了工具和决策循环之后，行为逻辑开始接近一个做事的人，而不光是说话的人。
5. 常见问题与排查技巧实录
5.1 Agent陷入死循环
这是新手会遇到的第一个大坑。现象是Agent反复调用同一个工具，参数几乎不变，结果也一样，就是不死心。我见过一个案例，Agent连续八次调用同一个搜素接口，就为了找一个评分高于9.0的资料，而那种资料根本不存在。
排查思路是打开日志，看看每步的action和thought是否在重复。如果确定是重复执行，有三个办法：一是给每一步动作加上状态记录，要求模型每次调用工具前必须引用“上一步的结论”，避免它无视已有结果；二是把最大步数降到一个合理范围，比如6到8步，省成本也能逼它尽快收敛；三是在System Prompt里加一句规则，“如果连续两次工具返回相同结果，必须改变策略或直接输出基于现有信息的答案”，这句话对大部分模型的约束力相当明显。
5.2 上下文被无意义内容刷爆
上下文窗口是Agent最容易撞上的天花板。很多新手不知道，每执行一次工具调用，工具返回的内容都会拼接到消息列表里，连续搜索五次、读取三个网页之后，窗口就被塞满了，于是模型开始忘掉前面的关键信息，行为变得混乱。
解决这个问题最有效的办法是分层管理信息。第一层：原始网页内容只保留关键段落，抓取时做摘要；第二层：每一步工具返回，主循环只保留“结构化抽取后的条目”；第三层：关联性不强但可能有用的信息，存入临时文件或长期记忆，而不是继续占着上下文。本质上，上下文是非常昂贵的工作内存，不是仓库，仓库要建在外部。
5.3 工具返回格式解析失败
模型有时会输出一个无法通过JSON解析的“伪工具调用”，比如少了一个引号，或者中文标点混进去了。这类问题在模型能力弱或者提示词不明确时非常常见。我的做法是在调用函数前后做一层容错处理：先尝试直接解析模型返回的JSON，失败的话再调用模型自身做一次“修复式JSON解析”，让它把错误文本改写成合法JSON。两次都失败，就明确告知模型“本轮工具调用无效，请重新输出”，并把它从死胡同里拉回来。
容错逻辑写出来并不复杂，但能实实在在提高Agent的稳定度。生产环境中我还建议把每次解析失败的消息体记录下来，积累到一定程度就会发现，需要特定修正的模型在某些专业名词前后特别容易出错，这时就能针对性地补充提示词示例。
5.4 幻觉导致错误结论
幻觉是所有大模型应用的痼疾，Agent也不例外，甚至更隐蔽。因为Agent自己搜索了半天资料，于是很容易让用户认为它输出的每一句话都是有依据的。实际上，当搜索到的信息不足以支撑结论时，模型经常会把“看起来合理”的内容补进去。
缓解方案结合了工程和提示词两个层面。工程上，每次搜索和取回的网页必须连同一段小摘要，并把来源URL标记清楚，在生成报告时强制要求每一条论断后接引用的来源编号。如果某条论断找不到对应来源，就要求模型标注“无直接来源”。提示词上，我习惯在系统提示中加一句：“如果你不能基于已有的搜索结果回答用户问题，请直接说信息不足，不要编造。”这句话看似朴实，但效果比很多花哨的技巧都强。
5.5 成本失控
Agent的多轮调用注定比单次问答费钱，一次完整调研可能消耗几十万Token。我踩过最狠的一次，是一个循环失控的Agent在十分钟内把一天的预算烧掉了大半。痛定思痛，我总结出了三条成本控制手段。
第一，每次调用前先压缩历史消息，把不必要的细节摘要化。尤其工具返回的大段JSON，在回填上下文之前先做字段裁剪。第二，给不同环节配置不同强度的模型。比如判断“是否需要调用工具”这类简单决策用轻量模型，真正的复杂推理和 report 生成才用强模型。第三，全链路记录Token消耗并设置熔断。当前步数、累计消耗、单次响应长度都在监控范围内，超过阈值立即终止整个Agent流程，保护预算不失控。
6. 进阶方向与我的几点体会
6.1 从单Agent到多Agent的演进
当你把单个Agent调稳之后，可以尝试多Agent架构。最实用的是“主管-专员”模式：主管Agent负责任务拆解与结果汇总，每个专员Agent只负责一个细分能力。举例来说，写行业分析报告时，资料收集Agent只负责搜和读，数据分析Agent只负责处理表格，知识整理Agent负责把零散信息按主题归类，最后由主管Agent统稿。这样各Agent的提示词都能写得很聚焦，输出质量也比一个全才Agent稳定不少。
但多Agent的复杂度是成倍增加的：消息如何路由、任务超时怎么办、各Agent之间怎么共享临时结果，这些都要事先设计好。我的建议是，先把单个Agent做到“十次任务有八次能稳定收敛”，再考虑多Agent编排。否则，一个不稳定的单点乘以N，只会得到方差更大的不可控系统。
6.2 评测是Agent工程最容易忽略的一环
最后我想重点说一个很多教程都不提的环节：评测。Agent代码写出来不是结束，它能不能稳定达到预期效果，必须用评测集说话。我会准备一个由几十条任务组成的评测集，每条任务都有明确的验收标准。比如调研类任务，验收标准是“是否包含至少三个来源、是否有结构化总结、是否有明确结论”。每次改动提示词或工具逻辑之后，我都用同一套评测集回归一遍，看通过率变化。
回归评测看似枯燥，但它能防止一个非常隐蔽的问题：你以为你修好了A问题，结果某个提示词改动让B类任务的准确率悄悄掉了一大截。没有评测集，这种劣化可能要很久之后才在用户反馈中暴露，到时候定位又得从头翻日志，那滋味绝对不好受。
做Agent这件事，我的体会是：核心能力不是会用某个框架，而是能读懂Agent的思考轨迹，知道每一步为什么这么决策、数据在哪个环节流动、哪里最脆弱最容易出错。代码和框架总会被淘汰，但排查和设计这种底层的工程能力只会越来越值钱。去动手写一个你自己的最小Agent吧，踩过几个坑之后，你对“什么是Agent”的理解会超越市面上大部分教程的范畴。
