做了这么多年后端，有个感受特别深：ChatGPT刚火那阵子，大家觉得大模型就是个人形聊天框。结果过了不到两年，风向全变了，张嘴闭嘴都是Agent。我见过太多刚入门的程序员，被“智能体”“自主规划”“工具调用”这些词砸得晕头转向，一搜教程全是概念堆砌，看完还是不知道从哪下手。这篇就是想把这个事讲透。不整那些虚的，就是以一个干活的程序员视角，说明白Agent到底是什么、内部怎么运作、你该怎么从零搭一个能跑的东西出来。文章会直接给出一套可复现的最小实现，再把我踩过的坑和排查思路全抖出来。适合谁看？写过一点Python、用过哪怕一次大模型API的都能跟上。你要是完全没碰过编程，也能看懂大部分原理，只是代码部分可以先跳过。1. 先搞清楚：Agent到底是什么，和普通聊天有什么区别1.1 从“只会说”到“会干活”的本质变化你可以把大模型本身想象成一个特别博学但手无缚鸡之力的顾问。你问他“帮我查一下服务器磁盘怎么扩容”，他能给你写出一篇漂亮的方案，但方案终究是方案，他不会真的打开终端帮你敲命令，也不会去查监控数据。Agent做的事情，就是给这个顾问配上手和脚。它不再只是“生成文字”，而是围绕一个目标，自己去规划步骤、调用工具、检查结果、失败了重来，直到把事办完。这个转变听着小，实际是质变。我打个比方：普通的大模型交互像是你问路，对方给你画了张地图，认不认得路是你的事。Agent则像是你雇了个向导，他拿着地图带你走，走不通还会绕路，到了目的地才跟你交差。区别不在“懂多少”，而在“有没有责到底”。1.2 从“只会说”到“会干活”的本质变化（补一个抽象层级）站在程序员角度看，普通聊天是一次性的：prompt进去，文本出来。Agent则是一个持续运转的循环。这个循环通常长这样：拿到任务，调用大模型做规划，看规划里需要哪些工具，逐个执行，把结果反馈给模型，再根据反馈决定下一步，直到满足终止条件。这里面最核心的一点是：大模型只是Agent的“大脑”，不是全部。大脑负责推理和决策，真正动手的是工具，记东西的是记忆模块，控制循环节奏的是编排逻辑。很多新手学Agent，上来就扎进某个框架的文档里，其实没必要。只要理解了这条循环，所有框架你都能秒懂。这也是为什么我建议新人先别急着上框架，先用最原始的方式把这个循环写一遍。框架会隐藏细节，你很难建立直觉。2. 核心机制拆解：Agent凭什么比普通Prompt更强2.1 规划：把大任务拆成小步骤人到年底要做年度总结，不会直接写出一篇万字文档，而是先列大纲、再补素材、再填内容。Agent的规划机制也一样。现在的实现里有两种流派。一种是让模型在回答前一次性输出完整计划，然后照着执行，叫Plan-and-Execute。优点是思路清晰、可控性强，缺点是中途一旦发现计划错了，调整起来很僵硬。另一种是走一步看一步，模型每轮只决定“下一步做什么”，执行完再决定下下步，类似思维链（Chain-of-Thought）的动态版本，叫ReAct模式。我实际项目中绝大多数时候用的是ReAct风格，灵活，不容易被最初的错误判断锁死。有个点新手容易忽略：规划不是模型凭空想出来的，而是靠提示词逼出来的。你在系统提示词里明确写“你必须将任务分解为最多5步，每步只能调用一个工具”，模型就会遵循。不写，它就会懒散地给你一大段废话。2.2 记忆：短期工作台和长期仓库Agent没有记忆就寸步难行。你想让它“先读取配置文件，再根据配置批量处理图片”，它在第一步读到的内容得留到第二步用，这就是短期记忆，实现上就是把之前所有对话消息一直塞在上下文里。真正复杂的是长期记忆。比如一个客服Agent，需要记住“这个用户上次投诉过网络问题”，这就得靠外部存储。常见的做法是把历史交互摘要写入向量数据库，需要时按相似度召回，再拼进当前上下文。简单理解：短期记忆是手边的工作台，长期记忆是背后的档案柜。我在早期做过一个蠢事：让Agent处理一批文件，每处理一个就往上下文里塞一份完整内容，结果第四五个文件时上下文就爆了，模型开始胡言乱语。后来改成只塞摘要、细节按需查，问题立刻消失。记住：上下文长度再大，也不是让你无限塞的。成本、延迟、注意力分散，三个问题会同时找上门。2.3 工具调用：Agent的“手脚”如何接上工具调用（Function Calling）是Agent能干活的技术基石。它的原理不神秘：你把一堆“工具说明书”以JSON格式塞给模型，模型并不真的执行函数，它只是在回答里告诉你“我要调用get_weather，参数是{city: 北京}”。真正执行代码的是你的程序，执行完再把结果反馈回模型。这里有个关键认知：模型选工具、填参数，靠的是它对工具描述的语义理解。工具描述写得越清楚，参数约束写得越严格，选错工具、填错参数的概率就越低。很多Agent表现不稳定，根源在于工具定义写得太随意。2.4 执行循环：Agent的“心跳”把上面所有东西串起来的，就是一个循环。我写过一个极简版，核心逻辑就三件事：问模型下一步要干什么；如果是工具调用就执行并反馈结果；如果模型说“任务完成”，就退出循环返回最终答案。这个循环看似简单，工程上全是坑。比如模型连续调用同一个工具十几次不结束，你要不要设个最大轮数？比如工具执行报错了，是把错误原样喂给模型还是先清洗？这些问题没有标准答案，但每个做过Agent的人都有一肚子血泪史。后面我会专门开一节讲排查。3. 从一个最小可用Agent开始动手3.1 环境准备与总体设计我不会推荐你装一堆重型框架，先准备一个Python环境、一个能用的API密钥就够了。现在的API接口大多兼容OpenAI的格式，代码可以直接复用。整个项目结构特意做得极简：my_agent/ ├── main.py # Agent循环 ├── tools.py # 自定义工具 └── secrets.env # 存放密钥核心设计就一个原则：工具和主循环解耦。工具是纯函数，输入参数返回结果；主循环只管调度。这样后面加工具、换模型、加记忆，都只改局部。先做一个日历调度Agent，目标是让它根据当前日期，帮我规划未来一周的工作安排。为什么选这个场景？因为它需要工具（查日期、写日程）、需要推理（安排优先级）、结果又容易验证。麻雀虽小五脏俱全。3.2 先定义两个工具# tools.py import datetime def get_current_date() -> str: """返回今天的日期和星期，例如：2026-05-14 星期四""" now = datetime.datetime.now() weekdays = ["一", "二", "三", "四", "五", "六", "日"] return f"{now.strftime('%Y-%m-%d')} 星期{weekdays[now.weekday()]}" def add_schedule(date: str, time: str, event: str) -> str: """向日程表添加一条安排，成功返回确认信息""" # 真实项目里这里会写入数据库或日历API，这里直接打印示意 print(f"[日程写入] {date} {time} -> {event}") return f"已成功在{date} {time}添加安排：{event}"这两个函数本身平平无奇，但它们对应的工具描述才是关键。接着在main.py里定义工具说明书：# main.py import json tools = [ { "type": "function", "function": { "name": "get_current_date", "description": "获取今天的日期和星期。任何涉及时间、日期、星期的任务都必须先调用它。", "parameters": {"type": "object", "properties": {}} } }, { "type": "function", "function": { "name": "add_schedule", "description": "添加一条日程安排。调用前必须从用户输入中提取日期、时间和事件内容。", "parameters": { "type": "object", "properties": { "date": {"type": "string", "description": "日期，格式YYYY-MM-DD"}, "time": {"type": "string", "description": "时间，格式HH:MM"}, "event": {"type": "string", "description": "事件描述"} }, "required": ["date", "time", "event"] } } } ]注意我在描述里写了“任何涉及时间的任务必须先调用它”，这不是废话。模型在不确定时倾向猜，你给了强制条件，它的行为就会收敛。3.3 实现Agent主循环核心调度代码，我把每一步都加了注释：import requests API_URL = "https://你的API网关地址/v1/chat/completions" API_KEY = "你的密钥" def call_llm(messages, tools=None): """通用的大模型调用封装，任何OpenAI兼容接口都适用""" payload = {"model": "你的模型名", "messages": messages} if tools: payload["tools"] = tools resp = requests.post( API_URL, json=payload, headers={"Authorization": f"Bearer {API_KEY}"} ) resp.raise_for_status() return resp.json() TOOL_MAP = { "get_current_date": get_current_date, "add_schedule": add_schedule, } def run_agent(user_input: str, max_steps: int = 5): messages = [ {"role": "system", "content": "你是日程规划助手。严格按用户指令安排日程，拿不准时间时先查今天日期。"}, {"role": "user", "content": user_input} ] for step in range(max_steps): result = call_llm(messages, tools=tools) message = result["choices"][0]["message"] messages.append(message) tool_calls = message.get("tool_calls", []) if not tool_calls: # 没有工具调用，说明任务已完成，直接输出最终答案 return message["content"] for tc in tool_calls: fn_name = tc["function"]["name"] fn_args = json.loads(tc["function"]["arguments"]) print(f"[执行工具] {fn_name}({fn_args})") if fn_name in TOOL_MAP: output = TOOL_MAP[fn_name](**fn_args) else: output = f"错误：未找到工具{fn_name}" messages.append({ "role": "tool", "tool_call_id": tc["id"], "content": json.dumps(output, ensure_ascii=False) }) return "已达最大步数，任务未完成，请简化需求或增加max_steps" if __name__ == "__main__": print(run_agent("今天有什么安排？没有的话，帮我安排下周三早上10点开项目评审会"))这个循环就是整个Agent的骨架了。你喂给它任务，它先查日期，发现今天是周四，然后推断“下周三”具体是哪天，再调用写入工具，最后返回确认。每一次工具结果都会回流到消息列表里，模型能看到自己刚才那一手的后果，这就是Agent能“自主做事”的基本原理。运行一次，你会看到日志里依次出现查日期、写日程两次工具调用，最终模型给出总结。恭喜，你已经有自己的第一个Agent了。3.4 给Agent加一点短期记忆和边界控制上面这个版本有个明显短板：你问完第一句再问第二句，它不记得之前的对话。单轮Agent演示可以，真实场景不够用。最简单的做法是维持一个外部消息列表，每轮对话结束后不清理：messages = [{"role": "system", "content": SYSTEM_PROMPT}] while True: user_input = input("你：") messages.append({"role": "user", "content": user_input}) reply = run_agent_with_messages(messages) print(f"Agent：{reply}")这就是短期记忆的雏形。注意，这种无限追加的方式很快会遇到上下文长度上限。等你发现模型“忘了”最早的内容，或者响应明显变慢，就该上摘要压缩了：把超过一定轮数的历史对话用模型总结成一两句话，替换掉原始内容。这个技巧我几乎在所有项目里都用，简单但极其有效，比一上来就上向量数据库实在得多。4. 工具选型：自己写循环还是用开源框架4.1 手写方案的定位：理解优先、轻量优先我前面让你手写循环，不是为了让你以后所有项目都手写，而是为了让你建立心智模型。手写的优势太明显了：依赖少、无黑盒、调试时你能看到每一步消息流。出问题了，你可以直接打印messages列表，所有状态一目了然。缺点也同样明显。一旦任务复杂，你需要自己处理重试、并发、日志追踪、多Agent通信、人与Agent的审批交互，工作量会迅速失控。这时候你就该引入框架了。判断标准我给一个：如果你的项目只需要单Agent按固定流程调用不超过四五个工具，手写完全够，加框架反而是负担。如果涉及多角色协作、复杂的重试策略、可视化追踪，再考虑框架。4.2 主流框架的选型思路现在市面上的Agent框架不少，我按它们的侧重点给你划个类：框架风格典型特点适合场景全流程编排型设计器拖拽/脚本定义流程，强调工程化业务流程固定、要快速上线的场景自由规划型完全交给模型自主决策步骤，灵活性最高探索类任务、问题没有标准流程多角色协作型支持定义多个Agent角色互相协作需要分工配合的复杂项目轻量工具型只提供工具调用抽象，其他一切自理重度定制项目、已有成熟架构选框架别只看星标数，要看它的抽象方式跟你脑子里的Agent模型对不对得上。有的框架把“Agent”包装得太重，你只是想调个天气工具，它给你初始化一大堆东西，反而不舒服。我自己的建议是：先去读框架的架构文档，看它怎么处理消息循环、怎么管理工具注册。如果它的循环模型跟你手写出来的那个版本长得差不多，那这个框架就是好上手的。反之，如果它发明了一堆你看不懂的名词，先跑一个Demo验证再决定要不要深入。4.3 模型中台选择的三个硬指标聊完框架聊模型。做Agent不比做对话，对模型的要求更特殊，我总结成三个硬指标。第一是指令遵循能力。Agent依赖模型严格按格式输出工具调用。有些模型聊天很溜，一到结构化输出就乱，该给JSON给你来一句“好的我来帮您”。选型时用同一个prompt同时喂给不同模型，比较它们第一次就正确输出工具调用的比例。第二是上下文长度与注意力。长上下文只是敲门砖，关键在于上下文长了之后还能不能准确引用信息。有个笨办法测试：给模型塞一份5000行的日志，问它第3782行写的什么。答对了，说明注意力够强。第三是成本与延迟的平衡。Agent每次任务要调多次模型，成本是普通对话的5-10倍。实时交互强的场景，延迟敏感，你可能要牺牲一点效果换速度。这个没有银弹，只能拿真实负载做压测。5. 实战中的坑：问题排查与避坑清单5.1 死循环：模型反复调用同一个工具这是新手最常撞的墙。模型不知道为什么认准了一个工具来回调用，就像一个人反复开关同一扇门，永远不往里走。我见过最离谱的一次，模型为了查当前时间，连续调了19次日期接口。排查时先看工具结果反馈。最常见的原因是工具返回值太敷衍，模型得不到“足够”的信息。比如查日期只返回一串“2026-05-14”，模型可能不确定该不该继续。解决方法有两个：一是把工具返回值写详细，加上星期、节假日、便于推断的提示语；二是在系统提示里明确要求“每个工具最多调用两次，重复调用前先检查之前的输出”。技术兜底是设max_steps，这个我上面的代码里已经有了。生产环境我还会加一个“卡死检测”：如果连续三轮调用相同参数的工具，就强制终止并上报异常。5.2 工具参数幻觉：模型编造不存在的参数模型会在没拿到信息的时候，煞有介事地编一个。比如让它安排会议，它不知道参会人邮箱，就瞎编一个看起来很像真的地址。这问题在工具场景下很危险，因为写入操作一旦执行，影响是不可逆的。我的应对三板斧：第一，工具描述里明确标注每个参数的来源约束，比如“必须来自用户输入，不得自行推断”；第二，涉及写入、删除、发送类工具，先走“预执行确认”，让Agent输出将要执行的操作，人工或规则确认后再真正执行；第三，在工具函数内部做参数校验，格式不对直接抛错，不做“宽容处理”。第三点看起来最简单，反而最容易被忽略。5.3 Token成本失控：Agent吃钱比你想的快做个简单估算：一次任务平均调6次模型，每次输入3000 token、输出500 token，一个月跑10000次任务，按主流中端模型价格算，成本轻松翻过不少预算线。很多项目都是demo跑得欢，一上线才发现账单吓人。控制手段从粗到细有这么几个：用更小更快的模型处理简单子任务，只有复杂推理才用大模型；给大模型加“输出长度上限”参数，禁止它长篇大论；对工具返回内容做截断，日志文件只取前后各200行而不是全量返回；最后是缓存，完全相同的工具调用结果直接命中缓存，不重复计算。我特别强调一下工具返回的截断。很多人为了省事把完整文本塞回去，模型读起来吃力，token也烧得飞快。工具返回的是“决策所需的摘要”，不是原始数据，这是设计原则。5.4 上下文污染：旧信息干扰新决策当上下文里堆了太多历史工具结果，模型会分不清哪些是当前任务的有效信息。典型表现是：你让它处理第三份文件，它的结论里却引用了第一份文件的数据。缓解办法有几个层次。核心是“隔离”，每份独立文件走独立的子任务上下文，父Agent只接收摘要和结论。其次是“标注”，每条工具结果都强制带上任务ID和时间戳，模型看到来源自然减少混淆。最后是“压缩”，定期把旧消息折叠成结构化摘要，保留关键结论丢掉过程细节。这种问题往往在开发环境测不出来，一上真实数据就爆发。原因很简单，测试数据太少太规整，上下文很干净。建议你在联调阶段故意用脏数据压一遍。5.5 问题排查速查表现象可能原因优先排查动作Agent答非所问系统提示词目标不明确重写prompt，明确任务边界与输出格式反复调用同一工具工具返回信息不足丰富返回值，增加调用次数限制工具参数乱填参数描述不严格强化字段说明，写参数来源约束上下文一长就出错注意力分散或历史堆积启用摘要压缩，隔离子任务上下文成本异常升高循环次数过多/返回太长截断工具结果，限制最大步数和输出长度结果时好时坏模型温度过高把temperature降到0附近，确定性优先6. 进阶方向：Agent之外还需要什么6.1 可观测性：给Agent装上监控仪表盘Agent跑在生产环境里，最大的噩梦是“它到底为什么做出这个决定”。普通程序出bug，断点一打就能定位。Agent的每一步决策是大模型生成的，带有随机性，不可复现。我自己的做法是给所有Agent加日志钩子，记录每一步的完整状态：输入消息、模型原始输出、工具调用的参数、工具返回结果、本轮耗时。这些日志统一推送到一个检索系统，出问题时能按任务ID回放全程。看起来只是工程化的小事，但做过Agent的人都知道，没有回放能力的Agent项目，排查问题就像在黑箱里摸象。6.2 人机协同：把审批权留给人类不是所有操作都该让Agent自主执行。涉及资金、对外发送、删除数据这类高风险动作，成熟的做法是“人机审批模式”：Agent执行到关键节点自动暂停，把待执行操作和理由推给人类确认，确认后才继续。这个设计听着保守，却是我见过的所有生产级Agent项目的标配。它同时解决了两个问题：一是模型可能出错，人工兜底降低风险；二是用户对Agent的信任度，人在关键节点有掌控感，就更愿意放手让它跑其他环节。6.3 评测体系：没有评测的Agent优化都是盲人摸象普通程序有没有bug，跑测试用例就知道。Agent怎么测？总不能每次人工去点。我现在习惯给Agent建一个评测集，里面放三五十个典型任务，每个任务标注了期望的行为路径和最终结果。任何prompt调整、模型切换，都拿评测集跑一遍，看通过率和耗时变化。你可能会问，Agent的输出是开放的，怎么判断对错？我的做法是分两级：硬性规则判断（结果里是否包含关键信息、是否调用了指定工具）和模型评分（让另一个大模型按标准打分）。前者保证稳定，后者覆盖灵活语义。没有这套东西，你对Agent的“感觉好多了”全是错觉。我个人这几年做Agent项目，最大的体会是：Agent的技术壁垒不在模型，不在框架，而在工程化。模型能力会越来越强，框架会越来越顺手，但编排、记忆、观测、评测这些工程问题，永远是你项目能不能落地的分水岭。遇到问题别慌，先看消息循环里发生了什么，绝大多数坑都能从这一步找到根源。最后再分享一个小习惯：每换一个项目，我都会把Agent日志打印格式做得极其完整，甚至牺牲一点美观。因为Agent项目调试，本质上就是“看信”的艺术——你把模型每次收到的和看到的信息都弄清楚，问题就解决了一半。
做了这么多年后端，有个感受特别深：ChatGPT刚火那阵子，大家觉得大模型就是个人形聊天框。结果过了不到两年，风向全变了，张嘴闭嘴都是Agent。我见过太多刚入门的程序员，被“智能体”“自主规划”“工具调用”这些词砸得晕头转向，一搜教程全是概念堆砌，看完还是不知道从哪下手。这篇就是想把这个事讲透。不整那些虚的，就是以一个干活的程序员视角，说明白Agent到底是什么、内部怎么运作、你该怎么从零搭一个能跑的东西出来。文章会直接给出一套可复现的最小实现，再把我踩过的坑和排查思路全抖出来。适合谁看？写过一点Python、用过哪怕一次大模型API的都能跟上。你要是完全没碰过编程，也能看懂大部分原理，只是代码部分可以先跳过。1. 先搞清楚：Agent到底是什么，和普通聊天有什么区别1.1 从“只会说”到“会干活”的本质变化你可以把大模型本身想象成一个特别博学但手无缚鸡之力的顾问。你问他“帮我查一下服务器磁盘怎么扩容”，他能给你写出一篇漂亮的方案，但方案终究是方案，他不会真的打开终端帮你敲命令，也不会去查监控数据。Agent做的事情，就是给这个顾问配上手和脚。它不再只是“生成文字”，而是围绕一个目标，自己去规划步骤、调用工具、检查结果、失败了重来，直到把事办完。这个转变听着小，实际是质变。我打个比方：普通的大模型交互像是你问路，对方给你画了张地图，认不认得路是你的事。Agent则像是你雇了个向导，他拿着地图带你走，走不通还会绕路，到了目的地才跟你交差。区别不在“懂多少”，而在“有没有责到底”。1.2 从“只会说”到“会干活”的本质变化（补一个抽象层级）站在程序员角度看，普通聊天是一次性的：prompt进去，文本出来。Agent则是一个持续运转的循环。这个循环通常长这样：拿到任务，调用大模型做规划，看规划里需要哪些工具，逐个执行，把结果反馈给模型，再根据反馈决定下一步，直到满足终止条件。这里面最核心的一点是：大模型只是Agent的“大脑”，不是全部。大脑负责推理和决策，真正动手的是工具，记东西的是记忆模块，控制循环节奏的是编排逻辑。很多新手学Agent，上来就扎进某个框架的文档里，其实没必要。只要理解了这条循环，所有框架你都能秒懂。这也是为什么我建议新人先别急着上框架，先用最原始的方式把这个循环写一遍。框架会隐藏细节，你很难建立直觉。2. 核心机制拆解：Agent凭什么比普通Prompt更强2.1 规划：把大任务拆成小步骤人到年底要做年度总结，不会直接写出一篇万字文档，而是先列大纲、再补素材、再填内容。Agent的规划机制也一样。现在的实现里有两种流派。一种是让模型在回答前一次性输出完整计划，然后照着执行，叫Plan-and-Execute。优点是思路清晰、可控性强，缺点是中途一旦发现计划错了，调整起来很僵硬。另一种是走一步看一步，模型每轮只决定“下一步做什么”，执行完再决定下下步，类似思维链（Chain-of-Thought）的动态版本，叫ReAct模式。我实际项目中绝大多数时候用的是ReAct风格，灵活，不容易被最初的错误判断锁死。有个点新手容易忽略：规划不是模型凭空想出来的，而是靠提示词逼出来的。你在系统提示词里明确写“你必须将任务分解为最多5步，每步只能调用一个工具”，模型就会遵循。不写，它就会懒散地给你一大段废话。2.2 记忆：短期工作台和长期仓库Agent没有记忆就寸步难行。你想让它“先读取配置文件，再根据配置批量处理图片”，它在第一步读到的内容得留到第二步用，这就是短期记忆，实现上就是把之前所有对话消息一直塞在上下文里。真正复杂的是长期记忆。比如一个客服Agent，需要记住“这个用户上次投诉过网络问题”，这就得靠外部存储。常见的做法是把历史交互摘要写入向量数据库，需要时按相似度召回，再拼进当前上下文。简单理解：短期记忆是手边的工作台，长期记忆是背后的档案柜。我在早期做过一个蠢事：让Agent处理一批文件，每处理一个就往上下文里塞一份完整内容，结果第四五个文件时上下文就爆了，模型开始胡言乱语。后来改成只塞摘要、细节按需查，问题立刻消失。记住：上下文长度再大，也不是让你无限塞的。成本、延迟、注意力分散，三个问题会同时找上门。2.3 工具调用：Agent的“手脚”如何接上工具调用（Function Calling）是Agent能干活的技术基石。它的原理不神秘：你把一堆“工具说明书”以JSON格式塞给模型，模型并不真的执行函数，它只是在回答里告诉你“我要调用get_weather，参数是{city: 北京}”。真正执行代码的是你的程序，执行完再把结果反馈回模型。这里有个关键认知：模型选工具、填参数，靠的是它对工具描述的语义理解。工具描述写得越清楚，参数约束写得越严格，选错工具、填错参数的概率就越低。很多Agent表现不稳定，根源在于工具定义写得太随意。2.4 执行循环：Agent的“心跳”把上面所有东西串起来的，就是一个循环。我写过一个极简版，核心逻辑就三件事：问模型下一步要干什么；如果是工具调用就执行并反馈结果；如果模型说“任务完成”，就退出循环返回最终答案。这个循环看似简单，工程上全是坑。比如模型连续调用同一个工具十几次不结束，你要不要设个最大轮数？比如工具执行报错了，是把错误原样喂给模型还是先清洗？这些问题没有标准答案，但每个做过Agent的人都有一肚子血泪史。后面我会专门开一节讲排查。3. 从一个最小可用Agent开始动手3.1 环境准备与总体设计我不会推荐你装一堆重型框架，先准备一个Python环境、一个能用的API密钥就够了。现在的API接口大多兼容OpenAI的格式，代码可以直接复用。整个项目结构特意做得极简：my_agent/ ├── main.py # Agent循环 ├── tools.py # 自定义工具 └── secrets.env # 存放密钥核心设计就一个原则：工具和主循环解耦。工具是纯函数，输入参数返回结果；主循环只管调度。这样后面加工具、换模型、加记忆，都只改局部。先做一个日历调度Agent，目标是让它根据当前日期，帮我规划未来一周的工作安排。为什么选这个场景？因为它需要工具（查日期、写日程）、需要推理（安排优先级）、结果又容易验证。麻雀虽小五脏俱全。3.2 先定义两个工具# tools.py import datetime def get_current_date() -> str: """返回今天的日期和星期，例如：2026-05-14 星期四""" now = datetime.datetime.now() weekdays = ["一", "二", "三", "四", "五", "六", "日"] return f"{now.strftime('%Y-%m-%d')} 星期{weekdays[now.weekday()]}" def add_schedule(date: str, time: str, event: str) -> str: """向日程表添加一条安排，成功返回确认信息""" # 真实项目里这里会写入数据库或日历API，这里直接打印示意 print(f"[日程写入] {date} {time} -> {event}") return f"已成功在{date} {time}添加安排：{event}"这两个函数本身平平无奇，但它们对应的工具描述才是关键。接着在main.py里定义工具说明书：# main.py import json tools = [ { "type": "function", "function": { "name": "get_current_date", "description": "获取今天的日期和星期。任何涉及时间、日期、星期的任务都必须先调用它。", "parameters": {"type": "object", "properties": {}} } }, { "type": "function", "function": { "name": "add_schedule", "description": "添加一条日程安排。调用前必须从用户输入中提取日期、时间和事件内容。", "parameters": { "type": "object", "properties": { "date": {"type": "string", "description": "日期，格式YYYY-MM-DD"}, "time": {"type": "string", "description": "时间，格式HH:MM"}, "event": {"type": "string", "description": "事件描述"} }, "required": ["date", "time", "event"] } } } ]注意我在描述里写了“任何涉及时间的任务必须先调用它”，这不是废话。模型在不确定时倾向猜，你给了强制条件，它的行为就会收敛。3.3 实现Agent主循环核心调度代码，我把每一步都加了注释：import requests API_URL = "https://你的API网关地址/v1/chat/completions" API_KEY = "你的密钥" def call_llm(messages, tools=None): """通用的大模型调用封装，任何OpenAI兼容接口都适用""" payload = {"model": "你的模型名", "messages": messages} if tools: payload["tools"] = tools resp = requests.post( API_URL, json=payload, headers={"Authorization": f"Bearer {API_KEY}"} ) resp.raise_for_status() return resp.json() TOOL_MAP = { "get_current_date": get_current_date, "add_schedule": add_schedule, } def run_agent(user_input: str, max_steps: int = 5): messages = [ {"role": "system", "content": "你是日程规划助手。严格按用户指令安排日程，拿不准时间时先查今天日期。"}, {"role": "user", "content": user_input} ] for step in range(max_steps): result = call_llm(messages, tools=tools) message = result["choices"][0]["message"] messages.append(message) tool_calls = message.get("tool_calls", []) if not tool_calls: # 没有工具调用，说明任务已完成，直接输出最终答案 return message["content"] for tc in tool_calls: fn_name = tc["function"]["name"] fn_args = json.loads(tc["function"]["arguments"]) print(f"[执行工具] {fn_name}({fn_args})") if fn_name in TOOL_MAP: output = TOOL_MAP[fn_name](**fn_args) else: output = f"错误：未找到工具{fn_name}" messages.append({ "role": "tool", "tool_call_id": tc["id"], "content": json.dumps(output, ensure_ascii=False) }) return "已达最大步数，任务未完成，请简化需求或增加max_steps" if __name__ == "__main__": print(run_agent("今天有什么安排？没有的话，帮我安排下周三早上10点开项目评审会"))这个循环就是整个Agent的骨架了。你喂给它任务，它先查日期，发现今天是周四，然后推断“下周三”具体是哪天，再调用写入工具，最后返回确认。每一次工具结果都会回流到消息列表里，模型能看到自己刚才那一手的后果，这就是Agent能“自主做事”的基本原理。运行一次，你会看到日志里依次出现查日期、写日程两次工具调用，最终模型给出总结。恭喜，你已经有自己的第一个Agent了。3.4 给Agent加一点短期记忆和边界控制上面这个版本有个明显短板：你问完第一句再问第二句，它不记得之前的对话。单轮Agent演示可以，真实场景不够用。最简单的做法是维持一个外部消息列表，每轮对话结束后不清理：messages = [{"role": "system", "content": SYSTEM_PROMPT}] while True: user_input = input("你：") messages.append({"role": "user", "content": user_input}) reply = run_agent_with_messages(messages) print(f"Agent：{reply}")这就是短期记忆的雏形。注意，这种无限追加的方式很快会遇到上下文长度上限。等你发现模型“忘了”最早的内容，或者响应明显变慢，就该上摘要压缩了：把超过一定轮数的历史对话用模型总结成一两句话，替换掉原始内容。这个技巧我几乎在所有项目里都用，简单但极其有效，比一上来就上向量数据库实在得多。4. 工具选型：自己写循环还是用开源框架4.1 手写方案的定位：理解优先、轻量优先我前面让你手写循环，不是为了让你以后所有项目都手写，而是为了让你建立心智模型。手写的优势太明显了：依赖少、无黑盒、调试时你能看到每一步消息流。出问题了，你可以直接打印messages列表，所有状态一目了然。缺点也同样明显。一旦任务复杂，你需要自己处理重试、并发、日志追踪、多Agent通信、人与Agent的审批交互，工作量会迅速失控。这时候你就该引入框架了。判断标准我给一个：如果你的项目只需要单Agent按固定流程调用不超过四五个工具，手写完全够，加框架反而是负担。如果涉及多角色协作、复杂的重试策略、可视化追踪，再考虑框架。4.2 主流框架的选型思路现在市面上的Agent框架不少，我按它们的侧重点给你划个类：框架风格典型特点适合场景全流程编排型设计器拖拽/脚本定义流程，强调工程化业务流程固定、要快速上线的场景自由规划型完全交给模型自主决策步骤，灵活性最高探索类任务、问题没有标准流程多角色协作型支持定义多个Agent角色互相协作需要分工配合的复杂项目轻量工具型只提供工具调用抽象，其他一切自理重度定制项目、已有成熟架构选框架别只看星标数，要看它的抽象方式跟你脑子里的Agent模型对不对得上。有的框架把“Agent”包装得太重，你只是想调个天气工具，它给你初始化一大堆东西，反而不舒服。我自己的建议是：先去读框架的架构文档，看它怎么处理消息循环、怎么管理工具注册。如果它的循环模型跟你手写出来的那个版本长得差不多，那这个框架就是好上手的。反之，如果它发明了一堆你看不懂的名词，先跑一个Demo验证再决定要不要深入。4.3 模型中台选择的三个硬指标聊完框架聊模型。做Agent不比做对话，对模型的要求更特殊，我总结成三个硬指标。第一是指令遵循能力。Agent依赖模型严格按格式输出工具调用。有些模型聊天很溜，一到结构化输出就乱，该给JSON给你来一句“好的我来帮您”。选型时用同一个prompt同时喂给不同模型，比较它们第一次就正确输出工具调用的比例。第二是上下文长度与注意力。长上下文只是敲门砖，关键在于上下文长了之后还能不能准确引用信息。有个笨办法测试：给模型塞一份5000行的日志，问它第3782行写的什么。答对了，说明注意力够强。第三是成本与延迟的平衡。Agent每次任务要调多次模型，成本是普通对话的5-10倍。实时交互强的场景，延迟敏感，你可能要牺牲一点效果换速度。这个没有银弹，只能拿真实负载做压测。5. 实战中的坑：问题排查与避坑清单5.1 死循环：模型反复调用同一个工具这是新手最常撞的墙。模型不知道为什么认准了一个工具来回调用，就像一个人反复开关同一扇门，永远不往里走。我见过最离谱的一次，模型为了查当前时间，连续调了19次日期接口。排查时先看工具结果反馈。最常见的原因是工具返回值太敷衍，模型得不到“足够”的信息。比如查日期只返回一串“2026-05-14”，模型可能不确定该不该继续。解决方法有两个：一是把工具返回值写详细，加上星期、节假日、便于推断的提示语；二是在系统提示里明确要求“每个工具最多调用两次，重复调用前先检查之前的输出”。技术兜底是设max_steps，这个我上面的代码里已经有了。生产环境我还会加一个“卡死检测”：如果连续三轮调用相同参数的工具，就强制终止并上报异常。5.2 工具参数幻觉：模型编造不存在的参数模型会在没拿到信息的时候，煞有介事地编一个。比如让它安排会议，它不知道参会人邮箱，就瞎编一个看起来很像真的地址。这问题在工具场景下很危险，因为写入操作一旦执行，影响是不可逆的。我的应对三板斧：第一，工具描述里明确标注每个参数的来源约束，比如“必须来自用户输入，不得自行推断”；第二，涉及写入、删除、发送类工具，先走“预执行确认”，让Agent输出将要执行的操作，人工或规则确认后再真正执行；第三，在工具函数内部做参数校验，格式不对直接抛错，不做“宽容处理”。第三点看起来最简单，反而最容易被忽略。5.3 Token成本失控：Agent吃钱比你想的快做个简单估算：一次任务平均调6次模型，每次输入3000 token、输出500 token，一个月跑10000次任务，按主流中端模型价格算，成本轻松翻过不少预算线。很多项目都是demo跑得欢，一上线才发现账单吓人。控制手段从粗到细有这么几个：用更小更快的模型处理简单子任务，只有复杂推理才用大模型；给大模型加“输出长度上限”参数，禁止它长篇大论；对工具返回内容做截断，日志文件只取前后各200行而不是全量返回；最后是缓存，完全相同的工具调用结果直接命中缓存，不重复计算。我特别强调一下工具返回的截断。很多人为了省事把完整文本塞回去，模型读起来吃力，token也烧得飞快。工具返回的是“决策所需的摘要”，不是原始数据，这是设计原则。5.4 上下文污染：旧信息干扰新决策当上下文里堆了太多历史工具结果，模型会分不清哪些是当前任务的有效信息。典型表现是：你让它处理第三份文件，它的结论里却引用了第一份文件的数据。缓解办法有几个层次。核心是“隔离”，每份独立文件走独立的子任务上下文，父Agent只接收摘要和结论。其次是“标注”，每条工具结果都强制带上任务ID和时间戳，模型看到来源自然减少混淆。最后是“压缩”，定期把旧消息折叠成结构化摘要，保留关键结论丢掉过程细节。这种问题往往在开发环境测不出来，一上真实数据就爆发。原因很简单，测试数据太少太规整，上下文很干净。建议你在联调阶段故意用脏数据压一遍。5.5 问题排查速查表现象可能原因优先排查动作Agent答非所问系统提示词目标不明确重写prompt，明确任务边界与输出格式反复调用同一工具工具返回信息不足丰富返回值，增加调用次数限制工具参数乱填参数描述不严格强化字段说明，写参数来源约束上下文一长就出错注意力分散或历史堆积启用摘要压缩，隔离子任务上下文成本异常升高循环次数过多/返回太长截断工具结果，限制最大步数和输出长度结果时好时坏模型温度过高把temperature降到0附近，确定性优先6. 进阶方向：Agent之外还需要什么6.1 可观测性：给Agent装上监控仪表盘Agent跑在生产环境里，最大的噩梦是“它到底为什么做出这个决定”。普通程序出bug，断点一打就能定位。Agent的每一步决策是大模型生成的，带有随机性，不可复现。我自己的做法是给所有Agent加日志钩子，记录每一步的完整状态：输入消息、模型原始输出、工具调用的参数、工具返回结果、本轮耗时。这些日志统一推送到一个检索系统，出问题时能按任务ID回放全程。看起来只是工程化的小事，但做过Agent的人都知道，没有回放能力的Agent项目，排查问题就像在黑箱里摸象。6.2 人机协同：把审批权留给人类不是所有操作都该让Agent自主执行。涉及资金、对外发送、删除数据这类高风险动作，成熟的做法是“人机审批模式”：Agent执行到关键节点自动暂停，把待执行操作和理由推给人类确认，确认后才继续。这个设计听着保守，却是我见过的所有生产级Agent项目的标配。它同时解决了两个问题：一是模型可能出错，人工兜底降低风险；二是用户对Agent的信任度，人在关键节点有掌控感，就更愿意放手让它跑其他环节。6.3 评测体系：没有评测的Agent优化都是盲人摸象普通程序有没有bug，跑测试用例就知道。Agent怎么测？总不能每次人工去点。我现在习惯给Agent建一个评测集，里面放三五十个典型任务，每个任务标注了期望的行为路径和最终结果。任何prompt调整、模型切换，都拿评测集跑一遍，看通过率和耗时变化。你可能会问，Agent的输出是开放的，怎么判断对错？我的做法是分两级：硬性规则判断（结果里是否包含关键信息、是否调用了指定工具）和模型评分（让另一个大模型按标准打分）。前者保证稳定，后者覆盖灵活语义。没有这套东西，你对Agent的“感觉好多了”全是错觉。我个人这几年做Agent项目，最大的体会是：Agent的技术壁垒不在模型，不在框架，而在工程化。模型能力会越来越强，框架会越来越顺手，但编排、记忆、观测、评测这些工程问题，永远是你项目能不能落地的分水岭。遇到问题别慌，先看消息循环里发生了什么，绝大多数坑都能从这一步找到根源。最后再分享一个小习惯：每换一个项目，我都会把Agent日志打印格式做得极其完整，甚至牺牲一点美观。因为Agent项目调试，本质上就是“看信”的艺术——你把模型每次收到的和看到的信息都弄清楚，问题就解决了一半。