智能体项目实战：从架构设计到工具调用的LLM Agent开发全记录

我最早做AI相关项目，是从一个很朴素的聊天机器人项目开始的。它做得不算差，能回答常见问题，能闲聊，也接了一些办公系统里的工单查询。但是当我尝试把它往真正的业务场景推的时候，问题就暴露了：用户提出一个"帮我查一下上个月的报销，然后根据报销单把预算调整一下，顺便提醒相关人"的需求，我的机器人直接卡住了。因为它只能"对话"，无法真正去"做事"。也是在那之后，我才意识到我需要的不是一个更聪明的问答机器，而是一个能够自主拆解任务、调用工具、执行步骤的智能体项目。这篇文章就围绕我做智能体项目的整个开发过程，把从架构设计、技术选型、核心代码，到调试踩坑、性能优化的经验完整梳理一遍。适合正在接触Agent方向、想把AI从"会聊天"推向"能干活"的开发者和产品同学参考。

1. 先搞清楚智能体到底是什么：它不是ChatGPT套壳

在我开始写代码之前，最耽误时间的其实是认知问题。很多人觉得智能体就是"更聪明的对话模型"，这个误解会让后续的架构设计全盘跑偏。

1.1 从"对话系统"到"行动系统"的本质切换

传统的对话系统核心是理解与生成，输入一句话，模型输出一句话。但智能体的核心是规划与执行。它不是回答用户"应该怎么调整预算"，而是直接调用预算系统的接口，完成校验、计算、生成调整记录，然后告诉用户"已经调整完了，差异是XX，下一步建议这样做"。

这个切换带来三个关键变化：

• 对话不再是终点，而是"用户下达指令"的入口。
• 模型需要自主决定调用哪些工具、按什么顺序调用。
• 一旦模型能够操作真实系统，错误成本就从"说错一句话"变成"执行了一个错误操作"。

我在项目里把智能体定义为"一个具备目标拆解、工具调用、自我修正能力的LLM应用系统"。它由模型提供推理能力，由代码提供行动能力，两者耦合在一起，才构成Agent闭环。

1.2 大模型在智能体里的真实边界

第二个需要认清的点，是大模型并不是万能的推理引擎。实测中，通用模型在短链条任务上表现不错，但一旦任务步骤超过5步，或者依赖的上下文信息超过其有效窗口，模型就会开始"丢步骤"。更常见的现象是幻觉工具调用——模型会凭空编造一个并不存在的函数名或者参数值。

因此，智能体架构的核心其实是"用工程手段去弥补模型的不可靠"。你需要在代码层做严格的工具校验、参数校验、执行状态校验，而不是把信任完全交给模型。我在项目里经常说的一句话是：模型负责出主意，代码负责兜底。

2. 一个可靠的智能体骨架由五个模块构成，缺一不可

智能体的实现方式有很多种，从简单的ReAct循环，到复杂一些的多智能体协作框架，底层逻辑其实都逃不开五个核心模块。我这边的项目就是按这五个部分拆分的，后面的所有代码和排错，都围绕这套骨架展开。

2.1 规划器：把大目标拆成可执行小步骤

规划器负责把用户需求解析成一组有序的子任务。最简单的实现是"提示词+结构化输出"，让模型输出一个步骤列表。例如用户说"帮我整理本周的运营数据并生成周报"，规划器会得到：

[ {"step": "读取本周运营数据", "tool": "query_metrics", "params": {"period": "this_week"}}, {"step": "生成周报摘要", "tool": "generate_summary", "params": {}}, {"step": "发送周报", "tool": "send_email", "params": {"to": "manager_list"}} ]

规划质量直接决定Agent的上限。我试过两种规划策略：一次性规划（先把所有步骤输出，再逐步执行）和动态规划（每执行完一步，根据结果再规划下一步）。实测下来，动态规划更稳，因为真实系统里经常出现"查询无数据""接口报错""权限不足"等意外情况，一次性规划好的步骤链会直接断裂。

2.2 工具集：Agent和真实系统之间的手和脚

工具是智能体执行动作的载体。我项目的工具集分了三类：

• 内建工具：Agent自己内部的计算、文本处理能力，比如正则提取、日期换算。
• 业务接口：对接公司内部系统，比如查询订单、创建审批单、更新数据库记录。
• 外部服务：调用第三方API，比如天气、地图、OCR等。

每个工具在注册时都必须附带一份"机器可读"的说明书：函数名、参数列表、参数类型、是否必填、返回值结构、调用副作用。这里的副作用的描述极其重要，比如"发送邮件"这个工具，必须标注"该操作会真实发出邮件，不可撤销"。模型在规划时会参考这些信息，从而避免在测试阶段真的发送骚扰邮件。

2.3 记忆体：短期任务上下文与长期用户偏好

我的项目里把记忆拆成两层。短期记忆就是当前任务运行过程中的上下文切片，包括用户的原始输入、每一步的工具返回结果、模型的中间推理。长期记忆则用来沉淀用户的偏好、习惯，以及任务执行过的历史经验。

记忆管理的坑比想象中多。最大的坑是上下文污染——如果把所有历史记录全部塞给模型，模型反而抓不住重点。我的做法是做了摘要式记忆：每完成一个子任务，就把完整记录压缩成一两句摘要，模型只看到摘要进入下一轮规划。这样既保留关键信息，又不会让上下文无限膨胀。

2.4 执行循环：控制Agent推进节奏的发动机

执行循环是Agent的main loop，负责从规划器拿到步骤，调用工具，拿到结果，再送回模型继续推理。简单版本大概二三十行代码，但真正生产化之后会加入很多东西：最大迭代次数限制、单步骤超时、幂等控制、执行日志追踪。

我在项目里把循环设计成"有限状态机"：待执行、执行中、等待确认、成功、失败、终止。为什么需要等待确认这个状态？因为Agent操作真实系统时，凡是带有不可逆副作用的动作，都要先停下征求用户确认。这个设计在后面救了我好多次，后面会专门说。

2.5 观测与反馈：让Agent知道自己做得怎么样

最后一层是观测。Agent执行完一个动作之后，需要观察返回值并判断"达到目标没有"；没达到，则需要调整策略。这个环节看起来简单，实际上非常依赖工具返回结果的设计。如果工具只返回"成功"或"失败"两个字段，Agent基本无法纠错。我的做法是让每个工具返回结构化结果，包含执行状态、数据摘要、错误原因、可重试提示。例如：

{ "status": "failed", "error_code": "AUTH_EXPIRED", "message": "登录态已过期，请重新授权", "retryable": false }

有了这些信息，Agent才知道是需要重新授权、换一种方式查询，还是放弃任务求助人工。

3. 技术选型实录：框架、模型与底层API的取舍

这一节是我花了最多时间做横向对比的部分。网上关于框架选择的文章很多，但真正落到自己项目里，考虑维度其实很朴素。

3.1 主流框架对比：为什么我最后选择了轻量自研

主流智能体框架我当时都试了一圈，各有各的取舍，我把对照表放在下面。

我最终选择了框架基础上做二次封装，也就是用框架做底层的模型调用和工具调用解析，但把规划器、记忆管理、执行循环、权限控制全部换成自己的实现。这样既省了从零写的成本，又保住了对核心逻辑的控制权。因为生产项目里，框架帮我处理的那部分（比如函数调用解析）已经足够稳定，而真正容易出问题的部分（规划策略、记忆策略）我需要完全掌握。

3.2 模型选择的实测心路

模型选择上我没有盲目追求最大参数。项目里测试了多个模型，一个很有意思的发现：在规划能力上，参数更大的模型表现确实更好，但如果加上"可靠性"维度——比如严格遵循工具调用格式、不擅自添加参数——反而差距不大，甚至某些针对工具调用做过优化的中型模型表现更稳。

我的选择策略有两条：

• 复杂规划任务用能力更强的模型，简单任务用便宜快的小模型，做一个模型路由。
• 模型切换要封装在统一接口后面，避免后续换模型时把业务代码全部重写。

当然，模型这块迭代很快，我的经验是每隔一两个月就做一次回归对比，以免被旧模型的惯性带着走。

3.3 底层API调用里的"隐形工程"

选完模型和框架，还有一层很容易被忽略：底层API调用链路。我在项目中做了三件看似繁琐但收益很大的事。

第一是完整的日志追踪。每一次模型请求，我都记录下完整的Prompt输入、模型输出、Token消耗、延迟时间。没有这套日志，后面排错基本靠猜。

第二是重试与降级策略。模型接口偶尔会超时或限流，我实现了指数退避重试，并在连续失败N次后自动降级到小模型。对于生产环境，这个兜底机制比任何优化都重要。

第三是结构化输出校验。从模型拿到的不一定是合法JSON，更不一定是符合工具调用的格式，我会做一层校验和数据清洗，不合法就重新请求或者直接抛出错误。这层校验能从源头过滤掉大量幻觉问题。

4. 从零搭一个可以跑起来的智能体：核心代码实操

架构讲清楚了，自然是看代码。我这边不贴完整生产代码，因为涉及内部逻辑，但把最核心的Agent循环骨架写出来，这个版本可以直接在本地模拟跑通。

4.1 工具注册：让模型知道它能调用什么

工具注册是Agent能力的"声明"。我用Python装饰器把每个函数暴露给模型，同时带上参数定义和描述。

tools_registry = {} def register_tool(name, description, parameters, side_effect=False): def decorator(func): tools_registry[name] = { "name": name, "description": description, "parameters": parameters, "side_effect": side_effect, "func": func } return func return decorator @register_tool( "query_sales_data", "查询指定日期范围的销售数据，返回汇总金额与订单数", {"start_date": {"type": "string", "required": True}, "end_date": {"type": "string", "required": True}}, side_effect=False ) def query_sales_data(start_date, end_date): # 实际项目中这里会请求业务系统 return {"status": "success", "total_amount": 128000, "order_count": 364}

register_tool里有一个side_effect字段，它表示这个工具是否会对外部产生持久影响。引擎在执行工具前会检查这个字段，如果为True且用户没有显式授权，就进入等待确认状态。

4.2 记忆存储：两个轻量实现

短期记忆我直接用列表存储，长期记忆用简单的JSON文件或者向量库。为了演示，我用一个字典做内存版记忆。

class SimpleMemory: def __init__(self): self.short_term = [] # 当前任务的上下文切片 self.long_term = {} # 长期偏好，key可以设为用户ID def add_short(self, role, content): self.short_term.append({"role": role, "content": content}) if len(self.short_term) > 20: # 超长后压缩：保留最近5条，前面全部摘要化 tail = self.short_term[-5:] summary = "此前对话已概括为：用户查询了销售数据并计划生成周报。" self.short_term = [{"role": "system", "content": summary}] + tail def get_short(self): return self.short_term def save_preference(self, user_id, key, value): self.long_term.setdefault(user_id, {})[key] = value def get_preference(self, user_id, key, default=None): return self.long_term.get(user_id, {}).get(key, default)

这里的压缩策略很重要，如果不做压缩，十几轮对话之后模型会淹没在历史里，几乎必然会忽略关键指令。

4.3 核心Agent循环：有限步骤的自主推理-行动

下面是Agent运行的主循环，我做了截断保护，避免模型无限循环消耗Token。

class SimpleAgent: def __init__(self, llm, memory, max_steps=8): self.llm = llm self.memory = memory self.max_steps = max_steps def build_prompt(self, user_input): short = self.memory.get_short() tools_desc = build_tools_description(tools_registry) system_prompt = f""" 你是一个智能体，你需要根据用户的目标拆解步骤，并调用可用工具。 可用工具：{tools_desc} 请始终输出JSON格式，包含字段： - thought: 你的推理过程 - tool: 工具名称（如果不需调用则填 "finish"） - params: 工具参数 - side_effect_confirm: 如果在调用可能产生副作用的工具前需要用户确认，将此字段设为 true """ return system_prompt, short def run(self, user_input, user_confirmed=False): self.memory.add_short("user", user_input) for step in range(self.max_steps): system_prompt, messages = self.build_prompt(user_input) response = self.llm.chat(system_prompt, messages) decision = parse_json_response(response) if decision.get("tool") == "finish" or decision.get("tool") is None: return {"status": "finished", "final_answer": decision.get("answer", "")} tool_info = tools_registry.get(decision["tool"]) if not tool_info: self.memory.add_short("system", f"工具 {decision['tool']} 不存在，请检查工具名") continue # 副作用护栏 if tool_info["side_effect"] and not user_confirmed and decision.get("side_effect_confirm"): return {"status": "need_confirm", "tool": decision["tool"], "params": decision.get("params", {})} try: result = tool_info["func"](**decision.get("params", {})) self.memory.add_short("system", f"工具 {decision['tool']} 返回：{result}") except Exception as e: self.memory.add_short("system", f"工具 {decision['tool']} 执行失败：{str(e)}") return {"status": "max_steps_exceeded", "message": "已达最大执行步数"}

这段代码非常精简，但它承载了Agent闭环的核心：理解用户意图、遍历工具清单、调用工具、观察返回、继续推理。生产环境中，我把它扩展成了异步执行、任务队列、断点续跑，但核心思想完全一致。

4.4 跑一个真实示例

我用查询销售数据的例子跑了一遍，用户输入是"帮我查本月销售额，高于10万就提醒我"。Agent的行为链大致是：调用query_sales_data -> 拿到总金额128000 -> 判断高于10万 -> 输出结论"本月的销售额为128000元，超过10万阈值，达成目标"。

这里面没有复杂的魔法，模型只是把"需要查询数据"这个动作转成了工具调用，然后把返回结果转成了自然语言回答。真正的智能感来自两点：一是模型知道在什么时候该调用工具而不是自己编，二是系统知道在拿到工具的返回之后该如何往下走。

5. 实测中的深坑：三条完整的排查链路

这个项目里我踩的坑非常多，挨个列出来能写一本书。这里重点讲三个最有代表性的，每一道坑都完整走完了从现象到根因再到修复的过程。这些排错思路比具体的修复代码更重要，你后面遇到类似的问题可以考虑往同样的方向排查。

5.1 工具参数幻觉：模型把不存在的参数当参数传

现象很离谱：模型调用查数工具的时候，传了一个"period=M"这样的参数，但工具定义里根本没有这个参数。结果就是工具执行失败，Agent连续重试三次，全部失败，最后直接放弃任务。

排查链路是这样的。我先看日志，发现工具返回的错误是"unexpected keyword argument"。这个错误说明模型传入了未定义的参数。我不急着修代码，又跑了几组不同的用户请求，专门统计模型传的参数分布，结果发现同一个工具，模型在两成请求里都会额外生成"filters""grouping""sort_by"这类未定义参数，甚至有一次把上一个工具的旧参数直接带了过来。

根因其实是两层的：第一，工具定义里的参数描述写得不够严格，模型不确定哪些参数可用，就会"自由发挥"；第二，模型在处理长上下文时存在状态残留，容易把已经用过的其他工具的参数片段拼接到新工具上。

修复方案也是两层的。在工具定义侧，我把参数描述改成了穷举式说明，明确列出所有合法参数，并加了一句"不允许额外传入未列出的参数"。在引擎侧，我加了一层参数白名单校验，凡是传入未定义参数的调用，直接拦截并反馈错误"参数不在白名单内，请重新构造调用"。

这个修复之后，参数幻觉发生的概率大幅下降，但因为模型本身的不确定性，它不会降到零。所以我在生产环境里始终保留这层校验，把它当成一道必要的安全闸门。

5.2 记忆污染：一次失败的操作污染了后面所有任务

那次问题出现在记忆压缩策略上。之前的实现是超过20条之后，把早期对话简单压缩成一句摘要。但摘要里包含了失败操作的信息，比如"用户试图查询销售数据失败，原因是权限不足，提示联系管理员"。结果后续任务一进来，模型就误以为当前用户也无权限，直接拒绝了任务。

排查时我看日志发现，用户的提问是"帮我查一下库存数据"，模型却回复"抱歉，由于权限不足需要联系管理员"。我一开始怀疑是权限模块的问题，折腾了很久，后来把完整Prompt打印出来，才发现是记忆里那一句失败摘要被模型当成了"当前系统状态"。

根因就是记忆污染，我把短期记忆里混杂了不同任务的历史失败信息，没有做隔离。修复方案有两个关键点：一是任务级记忆隔离，每个新任务开启新的短期记忆上下文，不继承上一个任务的执行细节；二是失败信息只传递给当前任务的规划器，在任务结束时全部清理，不进长期记忆，除非它代表了某种用户偏好（比如用户明确说"以后都按季度汇总"）。

从那以后，我设计记忆时都坚持一个原则：短期记忆负责当前任务的"操作上下文"，长期记忆负责跨任务的"用户偏好"，两者严格分开，不做任何形式的混读。

5.3 死循环与成本失控：一次测试跑了四万个Token

这个坑是跟成本直接挂钩的。某一次测试，Agent在处理一个模糊需求时，不停地调用查询工具，每轮返回的数据都不太一样，模型判断"还没达到目标"，于是继续查。因为Agent循环里没有设置步数上限，最终跑了四十轮，消耗了四万多Token，产生的查询结果其实都是同一类数据。

排查时我打开日志，发现每一轮模型的thought都在说"The data is not enough, query again with a slight adjustment"。很明显，模型卡在了一个"数据不够就要更多数据"的死循环里，而且它每次调整参数幅度极其微小，几乎是在原地打转。

修复上我做了两件事。一是给执行循环加硬性上限：max_steps=8，超过直接进入人工兜底流程。二是把"何时算完成任务"的判据写进提示词：要求模型在拿到工具结果后，先判断"这个结果是否足以回答用户问题"，如果足够，立即进入总结环节，不再继续查询。这个"收敛判据"极大提升了Agent的完成效率，也顺带优化了Token消耗。

另外，我也给每次任务设置了Token预算，在请求层的拦截器里实时统计，超预算就强制终止任务并返回中间结论。不要觉得这些限制是"束缚模型"，在生产环境里，它们才是保护钱包和业务安全的底线。

6. 让智能体从"能跑"到"好用"的调优手段

代码能跑通只是第一步，真正让用户愿意用，还需要大量调优。我调优的方向集中在三个地方：提示工程、输出校验、评估闭环。

6.1 提示词工程：把"万能说教"变成"结构化指令"

初版提示词我写得非常自由，比如"你是智能助手，请帮助用户完成任务"，效果就是模型发挥极不稳定。后来我把提示词升级为严格的结构化版本：先定义角色边界，再列出工具清单和每个工具的能力边界，然后给出明确的执行步骤要求，最后附加失败兜底策略。

一个很具体的优化是给模型"负面清单"。我会明确告诉模型：不要编造工具不存在；不要假设工具执行成功；不要在用户未确认时调用有副作用的操作。这种"禁止性指令"对模型行为的约束效果，远好于"请谨慎处理"这类空话。

另一个技巧是给模型提供"少样本示例"。我在提示词里内置了一条完整的工具调用示例，包括用户输入、thought、tool、params、观察结果、最终回答。模型会照着这个模式走，输出格式的稳定性明显提升。

6.2 结构化输出与二次校验：拿回的JSON必须先过安检

模型输出的JSON我用两层校验。第一层是语法解析，用Python的json.loads，解析失败就要求模型重新输出。第二层是语义校验，解析出的tool名称必须在工具注册表里，params里的参数必须符合注册时的参数结构，side_effect字段必须是bool类型。两道校验都通过，才允许这个决策进入执行器。

这一层看起来很简单，但很多Agent项目都会偷懒，直接把模型输出用来执行。我在项目里坚持了这层校验，理由很朴素：模型输出的解析错误，绝大多数是因为它产生了幻觉，而幻觉一旦流到执行层，轻则报错重则误操作。与其在运行期出问题，不如在入口处拦下来。

6.3 建立评估集：你改了一行代码，怎么知道Agent变好了还是变坏了

这是我认为整个项目里最有价值的一步。我建立了一个包含50条任务样本的评估集，每条样本都有确定性的预期结果，比如"用户问上季度销售额，Agent必须调用查询工具且参数日期范围正确，最后回答里必须包含金额数字"。每次我调整提示词、换模型、改记忆策略，都会先跑一遍这个评估集，计算工具调用正确率和任务完成率。

没有这层评估，我根本不敢放心改代码。曾经有一段时间，我为了提升回答的多轮一致性，给提示词加了一段复杂的"记忆规则"，结果上线后任务完成率反而从82%掉到了61%，多轮一致性上去了，简单任务的准确率反而下来了。如果不是用评估集兜住，这种退化很可能直接流到线上。

做评估集的时候还有一个心得：测试用例宁滥勿缺，特别是边界用例、失败用例和需要用户确认的用例，要占一定比例。因为我发现很多Agent系统在"顺风局"里表现极好，一旦遇到权限不足、数据为空、参数错误这些意外情况，就会彻底乱套。评估集里这类"逆境用例"才是检验Agent真实可靠性的试金石。

7. 下一步计划：多智能体协作与门槛内化

项目到了这个阶段，单智能体的能力基本稳住之后，我开始把精力放到多智能体协作上。这个方向相当于多个Agent各司其职，比如一个Agent负责数据查询，一个Agent负责文本分析，还有一个Agent负责审批提醒，它们之间通过消息队列协作，由编排层分配任务和汇总结果。多智能体带来的最大好处是每个Agent的上下文更干净，不会被跨域任务污染，但坏处是调试复杂度指数级上升。我的建议是，单Agent能力不够扎实之前，不要急着上多Agent，否则你排错的时候会在多个Agent的日志之间来回横跳，效率极低。

实际操作中还有一个门槛内化的方向。业务方并不关心你的Agent用了什么框架、什么模型，他们只关心需求能落地。所以我在项目后期把Agent能力封装成了"技能包"式的服务接口，业务人员通过配置化方式来定义新任务，比如填一个任务描述、选一堆工具、设一个审批流，就能生成一个新Agent应用。这个封装大幅降低了业务侧的接入门槛，也让整个智能体项目从"技术玩具"真正走向了"业务基建"。

如果你也在做智能体项目，我最想强调的其实不是那些炫酷的框架，而是对边界的敬畏。要给Agent设计清晰的目标，给它严格的工具边界和参数校验，给它执行步数的天花板和成本预算，给它记录每一步行为的日志。模型负责聪明，系统负责可靠，这两句话合在一起，才是一个Agent项目真正能落地的保障。