从零搭建AI Agent：核心架构与工程实践指南

1. 从零搭建一个AI Agent：我踩过的坑和最终跑通的架构方案

最开始接触AI Agent这个概念的时候，我以为它就是个"会调用工具的聊天机器人"。真正动手搭了一套之后才发现，事情远没有那么简单。一个能稳定完成任务的Agent，背后涉及任务规划、工具调度、记忆管理、异常恢复等一整套工程问题，任何一个环节没处理好，整个系统就会表现得像个"智商忽高忽低的实习生"。

这篇文章面向的是已经了解大模型基本调用方式、想进一步搭建Agent系统的开发者。我会从架构设计的角度出发，拆解一个可落地的AI Agent需要哪些核心模块，每个模块为什么这样设计，以及我在实际搭建过程中遇到的那些"文档里不会写"的问题。整套方案基于常见的开源工具链，不依赖特定平台，你可以根据自己的技术栈灵活替换。

2. 为什么需要Agent架构：从单次调用到自主执行

2.1 单次大模型调用的能力边界

大部分人最开始用大模型的方式很简单：写一个提示词，发一个请求，拿一个回复。这种方式在处理"翻译一段话""总结一篇文章"这类单步任务时完全够用。但一旦任务变成"帮我查一下最近三天的天气，然后根据天气决定要不要提醒我带伞，如果下雨就帮我写一条提醒消息"，单次调用就力不从心了。

原因在于，大模型本身只能做"文本进、文本出"的映射。它没有记忆，不会主动去查数据，也没法在执行过程中根据中间结果调整策略。你当然可以把所有信息塞进一个超长提示词里，但这样做有两个致命问题：一是上下文窗口有限，信息一多就会丢失关键细节；二是模型在长上下文中容易"迷失"，该用工具的时候忘了用，该输出结果的时候开始胡言乱语。

2.2 Agent的核心价值：把"一次思考"变成"持续决策"

Agent的本质，是把大模型从"一次性问答机"变成"持续决策器"。它通过一个循环结构，让模型不断观察当前状态、决定下一步动作、执行动作、获取反馈，然后再次决策，直到任务完成。这个循环就是所谓的Agent Loop。

我习惯用一个类比来解释：单次调用像是你问一个路人"附近有没有好吃的火锅店"，他凭记忆给你一个答案；而Agent像是你打开手机导航，它会先定位你的位置，然后搜索附近火锅店，再根据距离和评分排序，最后给你规划路线——每一步都依赖上一步的结果，而且中途你可以随时改变目的地。

这个循环结构带来的好处是显而易见的：模型可以在执行过程中获取新信息、修正错误、处理意外情况。但代价也很明显——延迟增加、成本上升、系统复杂度指数级增长。所以并不是所有任务都值得用Agent来做，这一点后面我会详细展开。

2.3 哪些场景真正适合上Agent

我的经验判断标准很简单：如果一个任务需要多步推理、外部信息获取、动态决策中的任意两项，就值得考虑Agent架构。比如：

• 需要调用多个API完成一个复合任务（查数据库、发邮件、生成报告）
• 需要根据中间结果决定下一步做什么（如果库存不足就触发补货流程）
• 需要维护跨轮次的上下文状态（多轮对话中记住用户偏好）

反过来，如果任务逻辑是固定的、线性的，用传统的工作流引擎或者简单的函数编排就够了，硬上Agent只会增加不确定性和调试难度。我见过不少团队为了"追热点"把简单的if-else逻辑改成Agent，结果系统变得又慢又不稳定，这是典型的过度设计。

3. 核心模块拆解：一个Agent需要哪些零件

3.1 规划模块：让模型学会"分步骤做事"

规划模块是Agent的大脑。它的职责是把一个模糊的用户目标拆解成可执行的步骤序列。比如用户说"帮我准备下周的团队周报"，规划模块需要把它拆成：获取本周工作记录、汇总项目进展、提取关键数据、生成周报草稿、发送给相关人员。

实现规划有两种主流思路。一种是显式规划：让模型先输出一个完整的步骤列表，然后按顺序执行。这种方式的优点是结构清晰、容易调试，缺点是如果中间某一步的结果和预期不符，后续步骤可能全部失效。另一种是隐式规划：不预先列出所有步骤，而是每一步都根据当前状态决定下一步动作。这种方式更灵活，但调试起来更困难，因为每次执行的路径可能都不一样。

我实际用下来，比较稳妥的方案是"粗粒度显式规划+细粒度隐式调整"。先让模型给出3到5个大步骤，每个步骤内部再根据实际情况动态决定具体动作。这样既保证了整体方向不跑偏，又保留了应对意外的灵活性。

注意：规划模块的提示词里一定要明确约束步骤数量。我试过不限制步骤数，模型有时候会拆出十几步，其中一半是重复或无关的，白白消耗token和时间。

3.2 工具调用模块：Agent的手和脚

工具调用是Agent和外部世界交互的通道。没有工具，Agent就只是个会说话的模型；有了工具，它才能查数据、写文件、发请求、操作数据库。

工具调用的技术实现，目前主流的方式是通过函数调用接口。你需要在请求中定义好每个工具的名称、描述、参数结构，模型会根据当前任务决定调用哪个工具、传什么参数。这里有几个关键细节：

工具描述要写得像"给新员工的说明书"。很多人写工具描述就一句话"查询用户信息"，模型根本不知道什么时候该用、参数该怎么填。好的描述应该包含：这个工具做什么、什么时候用、每个参数的含义和格式、返回什么结果。比如"根据用户ID查询用户的基本信息，包括姓名、邮箱、注册时间。当需要获取用户联系方式时使用此工具。参数userId为字符串格式，例如'U12345'。"

参数校验不能省。模型生成的参数不一定符合预期，可能少传、多传、类型错误。在工具执行前加一层校验，能避免很多莫名其妙的报错。我的做法是在工具函数入口处做严格的类型检查和边界检查，不合法就直接返回错误信息让模型重新生成。

工具数量要控制。我建议单个Agent的工具数量控制在10到15个以内。工具太多会导致两个问题：一是模型选择困难，容易选错工具；二是工具描述本身占用大量上下文，挤压了真正有用的信息。如果确实需要很多工具，可以考虑分层设计——先让一个"路由Agent"决定用哪类工具，再交给对应的"专业Agent"执行。

3.3 记忆模块：短期上下文与长期知识的分层管理

记忆模块解决的是"Agent怎么记住东西"的问题。这里要区分两种记忆：短期记忆和长期记忆。

短期记忆就是当前对话的上下文，包括用户说了什么、Agent做了什么、工具返回了什么。这部分通常直接放在提示词里，受限于模型的上下文窗口。我的经验是，短期记忆不要试图保留全部历史，而是要做滚动摘要——当对话轮次超过一定数量时，把早期的内容压缩成一段摘要，只保留关键信息。

长期记忆则是跨会话的知识，比如用户的偏好、历史任务的执行结果、常见问题的解决方案。这部分需要外部存储，通常用向量数据库来实现。当Agent需要回忆相关信息时，通过语义搜索从向量库中检索出最相关的几条记录，注入到当前上下文中。

这里有个容易踩的坑：不要把什么东西都往长期记忆里塞。我一开始把每轮对话都存进向量库，结果检索出来的内容噪音极大，反而干扰了模型判断。后来改成只存储"经过验证的事实"和"用户明确表达的偏好"，检索质量明显提升。

3.4 执行循环与异常恢复：让Agent能"自己爬起来"

执行循环是Agent的骨架，它把规划、工具调用、记忆管理串在一起。一个典型的循环是这样的：

1. 接收用户输入，加载相关记忆
2. 模型根据当前状态决定下一步动作
3. 如果是工具调用，执行工具并获取结果
4. 如果是最终输出，返回给用户
5. 否则把结果加入上下文，回到第2步

这个循环看起来简单，但实际运行时会遇到各种意外：工具超时、返回格式错误、模型陷入死循环、任务无法完成。异常恢复机制就是用来处理这些情况的。

我的做法是设置三层保护：最大循环次数限制（比如15次，超过就强制终止并返回当前进展）、重复动作检测（如果连续三次调用同一个工具且参数相同，判定为死循环，强制中断）、降级策略（如果某个工具连续失败，尝试替代方案或告知用户当前无法完成）。

实操心得：异常恢复的提示词要写得具体。不要只说"如果出错就重试"，而要告诉模型"如果工具返回超时错误，等待2秒后重试一次；如果仍然失败，尝试使用备用工具；如果备用工具也不可用，向用户说明情况并建议替代方案"。模型需要明确的指令才能做出合理的恢复决策。

4. 动手搭建：一个可运行的Agent最小系统

4.1 技术选型与依赖准备

搭建Agent不需要太重的框架，核心依赖就几个：一个大模型的API接口、一个用于工具调用的函数注册机制、一个向量数据库用于长期记忆、一个简单的Web框架用于接收请求。

我自己的技术栈是这样的：Python作为开发语言，FastAPI做接口层，Chroma作为向量数据库（轻量、易部署），大模型接口用通用的HTTP调用方式（方便切换不同模型）。如果你不想自己搭，也可以用现成的Agent框架，但我的建议是至少自己手写一遍核心循环，这样你才能真正理解每个环节在做什么，出了问题也知道去哪里排查。

环境准备方面，Python 3.10以上版本，安装几个核心包就行：

pip install fastapi uvicorn httpx chromadb pydantic

不需要装太多花哨的东西，Agent的核心逻辑用标准库就能写。

4.2 定义工具集与参数规范

工具定义是整个系统的基础。我以"日程管理Agent"为例，定义三个核心工具：查询日程、创建日程、发送提醒。

每个工具用JSON Schema描述参数结构：

tools = [ { "name": "query_schedule", "description": "查询指定日期范围内的日程安排。当用户询问某天有什么安排时使用此工具。", "parameters": { "type": "object", "properties": { "start_date": { "type": "string", "description": "开始日期，格式YYYY-MM-DD" }, "end_date": { "type": "string", "description": "结束日期，格式YYYY-MM-DD" } }, "required": ["start_date", "end_date"] } }, { "name": "create_event", "description": "创建一个新的日程事件。当用户要求添加会议、提醒或其他安排时使用。", "parameters": { "type": "object", "properties": { "title": {"type": "string", "description": "事件标题"}, "date": {"type": "string", "description": "事件日期，格式YYYY-MM-DD"}, "time": {"type": "string", "description": "事件时间，格式HH:MM"}, "duration_minutes": {"type": "integer", "description": "持续时长（分钟）"} }, "required": ["title", "date", "time"] } } ]

工具描述里的每一句话都是有作用的。"当用户询问某天有什么安排时使用此工具"这句话，就是告诉模型在什么场景下触发这个工具。我试过省略这类场景说明，模型经常在该调用工具的时候直接编造答案。

4.3 实现核心Agent循环

核心循环的代码不复杂，关键是把每一步的状态管理清楚：

async def agent_loop(user_input: str, max_iterations: int = 15): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_input} ] for i in range(max_iterations): response = await call_llm(messages, tools=tools) if response.type == "final_answer": return response.content if response.type == "tool_call": tool_name = response.tool_name tool_args = response.tool_args # 参数校验 if not validate_tool_args(tool_name, tool_args): messages.append({ "role": "tool", "content": f"参数错误：{validation_error}" }) continue # 执行工具 try: result = await execute_tool(tool_name, tool_args) messages.append({ "role": "tool", "content": str(result) }) except Exception as e: messages.append({ "role": "tool", "content": f"工具执行失败：{str(e)}" }) return "任务执行超时，请尝试简化您的请求。"

这段代码里有几个关键点。参数校验在工具执行之前，避免无效调用；工具执行失败不中断循环，而是把错误信息返回给模型，让它决定下一步；最大迭代次数是硬限制，防止无限循环消耗资源。

4.4 记忆存储与检索的落地实现

长期记忆用Chroma来实现，核心就两个操作：存储和检索。

存储的时候，我会把信息整理成结构化的文本再存入，而不是直接存原始对话。比如用户说"我每周三下午都有团队会议"，我会存成"用户偏好：每周三下午有团队会议，不可安排其他事项"。这样检索出来的信息更干净，模型也更容易理解。

检索的时候，用当前用户输入作为查询，取最相关的3到5条记录注入上下文。这里有个细节：检索结果要标注来源和时间，比如"[2024-01-15记录] 用户偏好：..."，这样模型能判断信息的时效性。

def retrieve_memories(query: str, top_k: int = 5): results = collection.query(query_texts=[query], n_results=top_k) memories = [] for doc, metadata in zip(results['documents'][0], results['metadatas'][0]): memories.append(f"[{metadata['date']}记录] {doc}") return memories

4.5 系统提示词的设计要点

系统提示词是Agent的"操作手册"，写得好不好直接决定Agent的表现。我的提示词模板包含这几个部分：

角色定义：明确Agent的身份和能力边界。"你是一个日程管理助手，帮助用户查询、创建和管理日程安排。你只能通过提供的工具来操作用户的日程数据，不要编造任何日程信息。"

工作流程：告诉Agent应该按什么顺序做事。"首先理解用户意图，然后选择合适的工具，获取结果后判断任务是否完成。如果信息不足，向用户询问缺失的细节。"

约束条件：明确什么能做、什么不能做。"不要在没有调用工具的情况下声称已经完成了日程操作。如果工具返回错误，如实告知用户，不要试图掩盖。"

输出格式：规定最终回复的格式。"最终回复使用简洁的中文，包含操作结果和必要的后续建议。"

注意：系统提示词不是越长越好。我试过写了两千多字的提示词，结果模型反而抓不住重点。后来精简到八百字左右，只保留最关键的约束，效果反而更好。

5. 调试与优化：那些只有跑起来才会遇到的问题

5.1 模型不调用工具怎么办

这是最常见的问题。模型明明应该调用工具，却直接编了一个答案。原因通常有三个：工具描述不够清晰、系统提示词没有强调必须使用工具、或者模型本身的能力不足。

我的解决顺序是：先检查工具描述，确保每个工具都有明确的"使用场景"说明；然后在系统提示词里加一句"所有涉及日程数据的操作必须通过工具完成，禁止凭记忆回答"；如果还不行，考虑换一个工具调用能力更强的模型。实测下来，不同模型在工具调用上的表现差异很大，有些模型天生就更"听话"。

5.2 工具返回结果太长导致上下文爆炸

有些工具返回的数据量很大，比如查询一个月的日程可能返回几十条记录。全部塞进上下文会迅速消耗token，而且模型在大量信息中反而找不到重点。

我的处理方式是在工具层面做结果裁剪。查询类工具默认只返回最相关的若干条，或者返回摘要统计而不是原始数据。如果模型需要更详细的信息，让它再次调用工具并指定更精确的参数。这样既控制了上下文长度，又迫使模型进行更精确的推理。

5.3 多轮对话中的状态丢失

用户说"帮我查一下明天的日程"，Agent查完返回结果。用户接着说"把第二个会议改到下午三点"，这时候Agent需要知道"第二个会议"指的是什么。如果上下文管理没做好，Agent就会一脸茫然。

解决这个问题的关键是在每轮工具调用后，把关键信息显式地记录到上下文中。比如查询日程后，不仅返回原始结果，还附加一句"当前查询到3个日程：1. 上午十点项目评审 2. 下午两点技术分享 3. 下午四点一对一沟通"。这样后续对话中模型就能准确引用。

5.4 常见问题速查表

6. 进阶方向：从能用走向好用

6.1 多Agent协作的适用场景

单个Agent的能力有上限，当任务涉及多个专业领域时，可以考虑多Agent架构。比如一个"项目管理系统"，可以拆成"需求分析Agent""进度跟踪Agent""风险预警Agent"，各司其职，通过消息传递协作。

但我要泼一盆冷水：多Agent系统的复杂度远高于单Agent。Agent之间的通信协议、任务分配、结果汇总，每一个环节都可能出问题。我的建议是，先把单Agent跑稳，确认单Agent确实无法满足需求时，再考虑拆分。大部分场景下，一个设计良好的单Agent加上足够丰富的工具集，已经能解决90%的问题。

6.2 人工介入机制的设计

完全自主的Agent在生产环境中是有风险的。我的做法是在关键节点设置人工确认。比如Agent准备执行"删除日程"或"发送通知"这类不可逆操作时，先输出一个确认请求，等用户确认后再执行。

这个机制实现起来很简单：在工具定义中加一个requires_confirmation标记，执行前检查这个标记，如果需要确认就暂停循环，把待确认的操作返回给用户。用户确认后，带着确认信息重新进入循环。

6.3 性能与成本的平衡策略

Agent的token消耗通常是单次调用的5到10倍，因为每一轮循环都要把完整上下文发给模型。控制成本有几个实用技巧：

上下文压缩：定期把历史消息做摘要，只保留关键信息。我通常保留最近5轮完整对话，更早的压缩成一段200字以内的摘要。

工具结果精简：工具返回的数据只保留模型决策所需的最小信息集，不要返回原始数据。

模型分级：简单决策用轻量模型，复杂推理用重量级模型。比如判断"是否需要调用工具"可以用小模型，实际的任务规划和结果生成用大模型。

缓存复用：对于频繁查询且变化不频繁的数据，加一层缓存，避免重复调用工具。

6.4 可观测性建设：日志、追踪与评估

Agent系统最让人头疼的就是"出了问题不知道哪里出的"。我的经验是，从第一天就要把日志和追踪做好。

每一轮循环记录：输入是什么、模型输出了什么、调用了哪个工具、参数是什么、返回结果是什么、耗时多少。这些日志在排查问题时是无价之宝。我习惯用一个简单的JSON格式记录每轮的状态，出问题时直接看日志就能定位到具体环节。

评估方面，我会维护一个"测试用例集"，包含常见的用户请求和预期的执行路径。每次修改提示词或工具定义后，跑一遍测试集，看看有没有回归。这个习惯帮我避免了很多"改了一个地方，坏了三个地方"的情况。

7. 我个人在实际搭建中的几点体会

踩了这么多坑之后，我最大的体会是：Agent的瓶颈往往不在模型能力，而在工程细节。工具描述多写一句话、参数校验多一层检查、异常处理多一个分支，这些看起来不起眼的地方，才是决定Agent能不能稳定跑起来的关键。

另一个体会是，不要追求一步到位。我一开始就想做一个"什么都能干"的通用Agent，结果什么都干不好。后来改成针对具体场景做专用Agent，每个Agent只解决一类问题，反而效果好得多。先把一个场景做深做透，再考虑扩展，这个顺序不能反。

最后分享一个实用技巧：给Agent加一个"思考过程"的输出。让模型在决定调用工具之前，先用一句话说明"我现在要做什么、为什么这么做"。这个输出不返回给用户，只记录在日志里。调试的时候，你能清楚地看到模型的决策逻辑，定位问题会快很多。这个习惯是我从一位资深开发者那里学来的，用了之后调试效率至少提升了一倍。