15天Agent开发入门复盘：从API调用到最小智能体落地

今天是我学习Agent的第15天标题里三个感叹号不是夸张是我终于把第一个完整Agent跑通之后的真实反应。如果你也正在学Agent、准备做agent开发或者刚看到朋友圈有人聊“什么是agent”“agent和skill有什么区别”就开始焦虑这篇15天复盘应该能帮你少走不少弯路。先交代一下我自己的基础不然下面的经验你会很难判断能不能直接抄。我是偏Web开发背景会Python和JavaScript做过几年业务系统对大模型的使用停留在“调API、写提示词、套个聊天框”的层次。15天前我对Agent的理解就是“自动帮你干活的东西”具体怎么实现、框架和纯写代码有什么差别、记忆怎么存全是模糊的。这篇文章不讲transformer底层原理也不复述官方文档里的名词定义我想记录的是从“能调通LLM接口”到“能设计一个带工具调用、有记忆、能自己恢复异常的最小智能体”这15天我实际做了什么、哪些概念直到第14天还在混淆、踩了哪些坑、以及怎么判断自己是“真会了”而不是“看懂了”。1. 前14天到底学了什么一条能照抄的Agent入门时间轴很多人一上来就搜“agent开发学习路线”然后被各种框架、协议、热词淹没反而不知道第一步该干嘛。我前14天最大的收获是把这条路线走成了一个可以复制的阶段模型。整体时间轴大概是这样的时间段学习主题我用来检验“学会了”的标准第1~4天LLM应用层基础上下文、提示词、结构化输出能用API搭一个会调用外部数据的问答程序第5~9天Function Calling / Tool Calling让模型自己决定调用哪个函数并且能处理参数错误第10~12天选一个框架把官方Demo拆掉再装回去能解释Demo里每个节点/边的用途第13~14天设计一个最小Agent工具记忆循环能处理多轮工具调用上下文不爆掉1.1 第1~4天把LLM基础补到“够用”而不是“精通”前4天我并没有直接碰Agent而是先补了三件事上下文窗口到底怎么工作、提示词如何输出稳定的结构化内容、温度/采样参数对结果的影响。这个阶段很多人觉得没必要但实际上后面Agent跑飞、输出乱格式、甚至工具调用失败根源都在这里。我做了两个小实验第一个是让模型从一段合同文本里抽取“甲方、乙方、金额、违约条款”要求必须输出严格JSON。第二个是故意给它一个超出上下文的文档观察它是胡编还是说“不知道”。第二个实验特别重要它让我意识到上下文窗口不是无限的记忆仓库而更像一张白板写满了就会开始丢东西或者胡写。明白这一点后面学Agent记忆设计的时候才不慌。基础阶段不要贪多把function calling之前的提示词工程和结构化输出搞清楚就行。1.2 第5~9天Function Calling是Agent的肌肉记忆如果只让我给Agent初学者一个关键词我会选Function Calling。它是Agent和普通聊天机器人最本质的分水岭普通聊天机器人只会“说”Agent通过Function Calling会“做”。第5天到第9天我几乎没有写任何Agent代码就反复练习一件事怎么让LLM输出一个结构化的函数调用请求然后程序去执行这个函数再把执行结果回传给模型。这里面有个很多人忽略的细节——模型其实不会真的执行函数它只是按你的JSON Schema生成一个“请求”真正执行、捕获异常、把结果塞回对话上下文都是你写的代码干的。到了第9天我已经明白一个道理Agent的核心循环其实就是“模型想调函数 → 程序执行 → 结果回填 → 模型继续想”的重复。这个循环听起来很简单但正是理解后面所有框架的钥匙。1.3 第10~14天选一个框架亲手拆掉再装回去从第10天开始我进入框架学习阶段。当时搜“agent框架”会看到一堆名字。我的经验是第一个框架不要贪多认准一个主流的、文档全的把它拆明白远比把三个框架的Hello World跑一遍有价值。我选了当前生态里资料最多的方向花了三天做一件事把框架自带的Demo拆开。不是看一遍就完事而是回答三个问题这个Agent的状态是怎么流转的工具调用的结果是怎么被保留的如果某一步出错了框架有没有重试机制这三个问题对应的是Agent开发中最核心的“循环、记忆、容错”任何框架都绕不开。拆完Demo后我再把Demo里的节点删掉部分改成自己的业务逻辑比如让它去查询订单、计算运费、再汇总给用户。这个过程过了以后基础算是真正打牢了。2. 第15天终于想明白的概念边界Agent、Skill、Harness、Workflow谁是谁前13天我一直在被各种名词反复折磨。你搜“什么是agent”、看一份文档讲“skill和agent的区别”换一篇文章又讲“harness和agent区别”还有“agent框架与编排”“agent llm embedding 等名词区别”。这些词单独看每个都能懂放一起就开始打架。第15天我尝试把这些概念放在一张图上发现豁然开朗。2.1 Agent不是模型而是一种“使用模型的架构”先解决最根本的问题Agent不是一个大模型也不等于一段写死的代码。它更像一个把大模型当作“大脑”的完整工作系统。拆开来看一个最基本的Agent通常包含四样东西模型负责理解和决策、工具负责让模型能碰外部世界、记忆负责记住已经发生的事、循环负责把以上三者串起来反复运转。如果你做的程序只有“用户提问 → 模型回答”没有工具调用没有多轮循环那它只是一个聊天机器人不是Agent。这也是为什么很多人号称在做Agent实际只是在调API——因为他没有“循环”这个骨架。2.2 Skill是手脚Harness是骨架Workflow是剧本继续拆名词。Skill在Agent语境里通常指一个封装好的能力单元比如“查天气的能力”“算账的能力”。它本质上是一个工具函数加一段说明文档的组合模型看到说明就知道什么时候该用这个能力。Harness这个英文词常被直译为“线束”或“笼头”在Agent里可以理解成整个运行骨架它负责管理模型、调用Skill、维护上下文、处理重试和权限。眼神好的读者会发现我前面说的Agent四要素里Harness就是那个把一切串起来的运行环境。再讲Workflow。Workflow是一条写死的执行路径比如“先查库再调API再汇总”每一步是什么、下一步去哪都是固定死的。而Agent的特点是模型可以自己在每一步决定下一步调哪个工具、问什么问题、要不要终止。Skill是有手有脚的能力Harness是承担这些手脚的骨架Workflow是提前写好的剧本而Agent是那个在台上根据剧本临场发挥还能改台词的话剧演员。这个类比帮我一句话记住了它们的关系。2.3 一句话记忆法遇到新名词先问“它有循环吗”后来我再遇到新的概念比如“route识别节点”“planning模块”“reflect框架”都会先问三个问题它有记忆吗它能根据结果改自己的下一步吗它是不是在驱动一个模型反复思考如果答案是“是”那它多半是一个Agent框架里的组件或模式如果答案是“否”那它只是一个工具或者一次性流程。这套判断法特别适用于看资料的时候。比如你看到“skill和agent的区别”我的理解是Skill是Agent可以调用的能力单元Agent是承载这些能力的整体系统两者不是并列关系而是零件和整机的关系。再比如“agent llm embedding 等名词区别”LLM是大脑Embedding是给记忆和检索用的向量化技术Agent是把大脑和检索能力组织起来的工程架构。分清“层次”而不是“区别”是这些概念不再折磨我的关键。3. 把概念变成能跑的程序第一个最小Agent的选型与落地概念理清了动手才是硬道理。第14到15天我搭了一个到现在还在用的最小Agent。这个项目没有用复杂的多Agent协作也没有上云上K8s核心目标很朴素让Agent能根据用户问题自己决定要不要调工具并在工具返回数据后继续回答。3.1 为什么第一个项目选“客服/资料整理”而不是“全自动写代码”有个很常见的坑是第一个Agent项目就选一个大而全的目标比如“自动写一个完整App”“全自动做数据分析报告”。这种目标对入门者来说会发现错误处理、上下文管理、权限校验一大堆问题同时涌过来最后连bug是自己写的还是模型抽风都分不清。我选的是“内部客服问答”用户问“我的订单什么时候发货”“运费怎么算”“退款到哪了”Agent自己判断要不要查订单库查完再汇总回答。这个场景有两个好处一是工具接口足够简单就两三个查询函数二是业务本身需要多轮对话能自然暴露记忆和上下文管理的问题。选一个边界清晰、工具不超过三个的小场景是第一个Agent项目最理性的选型。3.2 最小闭环观察-思考-行动-反思ReAct范式的落地方案我的Agent循环基于经典的ReAct范式先把用户的提问放进上下文观察让模型判断下一步该做什么思考如果要调工具就输出一个函数调用请求行动把工具返回结果放回上下文反思然后进入下一轮。每一步都被记录在对话历史里这样模型才能在第二轮参考第一轮发生了什么。落地的时候我给自己定了三条硬性规则第一每一轮必须把模型输出原样追加到消息列表不能只保留最终结果第二工具调用必须捕获异常并把错误信息也作为文本回填给模型让它决定要不要换个参数重试第三整个循环必须设最大迭代次数防止模型卡在死循环里烧钱。这三条规则看起来简单却是Agent稳定性的第一步。3.3 完整骨架代码Python 兼容OpenAI接口的最小实现这里放一个去掉业务细节后的骨架代码它已经能体现Agent循环的全部要点。为了不绑定某个具体厂商我用了OpenAI兼容接口的写法你换成任何兼容接口都行import json def call_llm(messages): from openai import OpenAI client OpenAI() # 读环境变量里的API Key和Base URL resp client.chat.completions.create( model你的模型名, messagesmessages, toolsTOOLS, # 工具Schema列表 tool_choiceauto, # 让模型自己决定要不要调工具 ) return resp.choices[0].message def run_agent(question): messages [{role: user, content: question}] max_iterations 5 for step in range(max_iterations): msg call_llm(messages) # 把模型这一轮的回答放进历史模型下一步才能参考 messages.append(msg.model_dump()) if msg.tool_calls: for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) try: result execute_tool(name, args) except Exception as e: result f工具执行出错: {e} messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) continue # 继续下一轮循环让模型基于工具结果作答 return msg.content # 没有tool_calls说明模型已经准备好直接回答 return 已达最大迭代次数提前终止。这段代码虽然短但包含了一个可靠Agent的必备要素模型自主决策、工具结果回填、异常回传、迭代上限。第一次跑通的时候我特别激动因为它是真的在“根据环境反馈决定下一步”而不是我写死流程。那个瞬间我才懂为什么那么多人说Agent是一种架构而非一个模型。4. 记忆是Agent的良心短期上下文、长期存储与记忆压缩的取舍学Agent过程中“agent记忆”是我在热搜里看到反复出现的词也是我自己第12天就被难住的问题。简单说Agent的记忆分两层短期记忆就是对话上下文窗口里的一切信息长期记忆是跨会话、跨重启依然能找回的数据。两者的设计和取舍很不一样。4.1 短期记忆就是上下文窗口你控制不了它的长度就要控制喂养方式很多Agent项目跑着跑着就出现 “agent execution terminated due to error.” 这类报错很大一部分原因是上下文窗口被塞爆了。每一轮工具调用结果、中间思考、用户补充的信息都在往消息列表里塞一旦超过模型的窗口限制服务直接报错。我的解决思路是“控制喂养”不是所有工具返回结果都值得原样保留只要能提取出一个摘要就够了。比如查订单接口返回了一万条记录Agent真正需要的可能只是“共找到3笔待发货订单最早一笔预计明天发出”。在回填给模型前先做一次压缩这样既保留了关键信息又让上下文瘦身。这个技巧投入产出比极高。4.2 长期记忆三步走抽取-向量化-检索Embedding的入门玩法长期记忆是让Agent在下一次会话里还记得你也是网上那些“Agent记忆”教程最爱讲的部分。入门实现可以分三步第一步是抽取把对话里有价值的信息抽出来比如用户的称呼、偏好、历史订单号组成一条条结构化记录。第二步是向量化用Embedding模型把每条记录转成一个向量这个向量代表记录的语义而不是字面关键字。第三步是检索用户新提问时把问题也转成向量然后用向量相似度把最相关的几条记录找出来拼进当前上下文。做这一步时我才真正理解“agent llm embedding 等名词区别”LLM负责生成和理解语言Embedding负责把“语义相近的记录”找回来它更像一个索引系统。没有Embedding的Agent也能做长期记忆比如直接按用户ID查数据库但有了EmbeddingAgent才能记住“模糊但语义相关”的事比如用户上次说“最近在赶项目”下次说“忙”你还能关联上。4.3 我自己用的“记忆三板斧”和升级顺序我踩过几次坑之后给自己定了一个记忆功能的开发顺序也分享给卡在“记忆怎么写”的人第一板斧对话结束前把整段对话做一轮摘要存到数据库。第二板斧新会话开始时把最近五条摘要拼进上下文让Agent“想起来”。第三板斧引入Embedding从历史摘要里做语义检索只拼相关记录。注意顺序很重要。如果你一上来就搞向量数据库、搞分块、搞embedding大概率会被一堆参数淹没而且短期内看不到效果。先用摘要数据库的方式把记忆闭环跑通再逐步升级到向量检索才是稳妥路线。这也是我学第15天最深的体会别在第一天就追求终极架构先把最简单方案跑通。5. 踩坑实录我掉进去又爬出来的五个Agent开发最常见的坑学习过程中光看教程会觉得Agent很顺滑自己动手才会发现处处是坑。我在热搜里看到“agent execution terminated due to error.”和“agent couldnt generate a response. please try again.”这两条报错时特别有共鸣因为它们真实发生在我的调试夜里。下面五个坑是我掉过又爬出来的按杀伤力排序。5.1 坑一“一次性调API”被包装成Agent我最初犯的错是把“写一个很长的Prompt让模型按步骤回答”当成Agent。但后来发现这种程序根本不具备自主决策能力只是把复杂任务拆成了一次性问答。真正的判断标准是如果一次请求之后不需要根据结果做第二次决策那就不是Agent。解决方案在上文提过引入Function Calling和循环让模型有机会在一次任务中多次调用工具。如果你发现自己写了很多if 关键词 in 用户问题的分支判断说明你还在用传统代码思维包裹Prompt而不是在架构Agent。5.2 坑二不设兜底Agent答不上来就panicAgent是概率系统不是确定性程序它一定会遇到不知道该怎么办的情况。但很多人的代码里没有兜底逻辑模型一返回空结果或乱格式整个程序直接崩溃用户看到的就是“agent couldnt generate a response. please try again.”。我的做法是给所有模型输出加一层校验如果是JSON就解析并捕获异常如果结果为空就回填“我没有找到相关信息请换个说法试试”并引导用户重试。对于工具调用一定要把异常信息当作文本喂回给模型让模型自己判断是参数错了还是该换一个工具。这个兜底设计花不了多少代码但能把程序的可用性提升一大截。5.3 坑三工具调用失败没有重试与告警机制有一类坑我排查了一整天才定位工具接口偶发超时Agent第一轮调用失败后直接终止而不是重试或解释。后来我看了完整日志才发现模型其实试图重新调用过但我的代码没有把工具超时异常转成可消化格式回填导致循环直接断了。修复方法是给工具包一层sleep重试的装饰器并把每次失败的详细原因记录到日志中。重试策略不要一上来就搞指数退避先固定重试两次就行。关键是要让模型“感知”到失败原因否则它会基于一个不完整的工具结果继续瞎编那比报错更可怕。5.4 坑四没有任何护栏Agent会“自由发挥”到不可控Agent能力越强越需要围栏。比如我让Agent去查订单库时它居然自己构思了一个“删除订单”的参数虽然权限系统没放行但那瞬间我意识到如果你不告诉模型哪些能做哪些不能做它真的会尝试。这就是“agent安全”的实际意义。我的护栏清单是第一工具Schema里明确写清楚哪些参数被禁用、哪些操作需要二次确认第二在System Prompt里声明权限边界比如“你只能查询订单状态不能修改或删除”第三对高风险动作加人工审批节点Agent只能发起申请不能直接执行。这三层下来即便模型突发奇想也不会造成实际破坏。5.5 坑五过度设计与过早优化最后一个坑不是技术问题而是心态问题。我有一阵子看到多Agent协作、记忆库、流式编排各种概念恨不得全部塞进第一个项目里结果代码写了一千行最后跑不起来。后来我把项目砍到只有“一个循环两个工具一个摘要记忆”反而稳定多了。建议第一个Agent项目尽量“笨拙而完整”一个模型循环、三四个函数、一个简单记忆方案就好。那些先进架构等你真的遇到性能瓶颈再引入不迟。过度设计是这个阶段最常见的隐性坑而且比显性报错更难发现。6. A2A、MCP这类协议到底要不要现在学学Agent的过程中你会频繁碰见“MCP”和“A2A”这两个词以及“a2a协议1.0版本和0.3版本完整agent card说明”这类话题。刚开始我也焦虑过是不是不学协议就落伍了后来我把两个协议的关系彻底搞明白心里就踏实了。6.1 两个协议管的事不一样MCP管“Agent用工具”A2A管“Agent找Agent”很多初学者把MCP和A2A混为一谈其实它们根本不在一层。**MCPModel Context Protocol**解决的是“模型怎么标准化地调用外部工具和数据源”的问题。你可以把它理解成USB接口以前每个设备有专属接口MCP统一了接口标准所以Agent接工具不用为每个工具写一套私有对接代码。**A2AAgent-to-Agent**解决的是“Agent怎么跟其他Agent协作”的问题。它管的是智能体之间的发现、通信、任务交接有点像企业之间的商务协议。如果说MCP是“手和工具之间的标准接口”那A2A就是“人与人之间的合作流程”。6.2 agent card是什么为什么它像一份“自我介绍简历”在A2A协议里经常提到“agent card”这个词一开始把我绕晕了。搞懂后你会发现它特别形象一份Agent对外发布的“自我介绍简历”。这份简历包含Agent的能力描述、支持的任务类型、输入输出格式、联系方式、认证方式等。当Agent A想把一个任务交给Agent BA会先读取B的Agent Card判断“它能不能干这个活、要怎么联系它、要传什么数据”。这个过程很像你在招聘平台看候选人简历先看技能、再看联系方式、然后发面试邀请。了解Agent Card你才能理解为什么协议会规定很多“元数据”字段它们不是纸面功夫而是让两个陌生Agent能快速建立协作的前提。6.3 我的建议看看就行别在第一个项目里硬塞我对协议的学习策略是“了解趋势不急着落地”。具体来说通读一遍MCP和A2A的官方说明知道它们解决什么问题、名词各自指什么即可但不要在第一个项目里硬塞。因为协议本身是生态成熟后才需要的东西你手上就一两个Agent、三五个工具自己写对接代码反而更直观。我判断是否需要学协议的标准是如果我不使用任何框架代码里已经开始出现大量需要兼容不同工具/Agent的适配逻辑那说明我该引入协议如果我只是想跑通一个智能体Demo那先不用在协议上花太多时间。这个判断标准也推荐给你。7. 学满15天能去面试吗Agent面试到底在考什么很多搜“agent面试”“agent面试题”“agent八股”的人其实是和我一样的转行者或在校生大家真正关心的问题是学完多久能证明自己会Agent面试官到底在考察什么。我虽然才学15天但已经搜集和复盘了不少常见的考察套路分享几个我认为最核心的。7.1 真正的八股不是背概念而是被问“上下文满了怎么办”网上流传的Agent八股很多停留在“什么是Agent”“什么是function calling”这类背诵题。但真正能区分“看过”和“做过”的面试题往往是场景题比如如果用户问了一个很长的问题加上工具返回结果后上下文超出了模型限制你会怎么设计这时候面试官想听的是一套完整思路而不是一个点先压缩工具返回、再对历史消息做摘要、然后考虑用Embedding做长期记忆检索、最后还要考虑项目当前阶段值不值得花这个成本。你会发现这些内容我在前几章节里零零散散都提到了。所以学Agent不能只看概念一定要亲手遇到一次上下文爆炸才能答出这种问题。真正有价值的八股是“你踩过什么坑、怎么排查、为什么这么设计”的过程。7.2 最容易被问穿的三类考察点工具调用、记忆、异常恢复我复盘下来Agent面试的高频考察点基本绕不开三件事。第一是工具调用面试官会问你如何定义工具Schema、如何解析模型返回的tool_call、工具参数出错怎么办。第二是记忆会问你短期和长期记忆分别怎么设计、为什么用Embedding、向量检索的相似度阈值怎么定。第三是异常恢复会问模型输出非法JSON怎么办、工具超时怎么办、死循环怎么避免。这三个点其实正好对应我前面讲的Agent四要素里的三个核心环节。你不需要背范文但需要真做一个项目把这些环节都亲手跑一遍。面试官一追问细节你就会知道没实操过的人是很难编出合理的“当时我是这么定位问题”的。7.3 给“前端转Agent开发”同学的一句话忠告我自己是偏前端的背景对“前端转agent开发”这个话题格外有体会。前端工程师转Agent方向有一个天然优势你对交互和产品体验敏感知道Agent怎么呈现给用户才友好但也有一个明显短板对服务端架构、并发、权限边界这些概念相对薄弱而Agent项目必然涉及这些。我给自己的忠告是不要从“重新学后端”开始而是从“做一个端到端Agent产品”切入在实战里补齐后端知识。做一个带前端界面、后端服务、Agent循环、简单记忆的小项目完整跑一次部署和调用链比钻研三个月后端理论有用得多。前端身份不是劣势因为Agent现在最缺的恰恰是把技术包装成普通用户能用的产品体验。最后再分享一个让我这15天效率提高不少的小习惯每天结束学习前我会把当天新学的概念丢给AI助手让它用一个生活化的比喻再讲一遍比如把Harness比作乐高底板上那些连接件、把上下文窗口比作办公桌桌面。如果它讲完我能立刻理解说明这个知识点真正被我吸收了如果听完我还是一头雾水第二天我会再找资料回炉。这个方法不花时间但帮我消灭了很多“眼睛会了脑子没会”的假象。下一步我准备在这个最小Agent基础上引入第二个Agent做任务复核让两个Agent互相对齐答案等这部分跑通我会再来更新。