1. 先把分工理清楚Lagent 管想AgentLego 管做Lagent 和 AgentLego 这套组合用来做智能体应用搭建最容易踩的第一个坎就是把两者当成一个东西。我见过不少人在同一个文件里既写提示词模板又写图像处理逻辑最后几十行代码互相耦合模型一改就全崩。真正把这两个库用顺的分界线只有一句话Lagent 负责想AgentLego 负责做。1.1 一个循环里其实只有三件事抛开所有花哨概念一个能用的智能体核心就是一个循环每一轮做三件事推理把用户问题 历史对话 当前可用的工具清单一起塞给大模型让它输出我下一步要干什么。调度从模型的输出文本里把要调用哪个工具、参数是什么解析成结构化数据然后真的去执行。回填把工具的执行结果转成文本追加回上下文再进入下一轮推理。Lagent 覆盖的是第 1 步和第 2 步的解析部分外加整个循环的控制器Agent 类和模型接入封装各种 LLM Client。它不关心工具内部怎么实现只关心工具有没有暴露名字、描述和参数结构。AgentLego 覆盖的是第 3 步的执行实体它是一堆工具类的集合每个工具自己知道我是干什么的、我要什么参数、我返回什么格式。它也不关心是谁在调用它不管调用方是智能体框架、是一段脚本还是一个人肉命令行。这个切分带来的直接好处是换模型不用改工具换工具不用改提示词。我在一个项目里把底座模型从 7B 换到 32B改的只有一个配置项后来把图像描述工具从轻量版换成精度更高的版本改的也只有一行实例化代码。如果一开始就写成一个巨型函数这两次改动都得重写。1.2 为什么工具层值得单独拆出来有人会问工具不就是几个函数吗直接注册进框架不就完了问题在于工具会膨胀。一开始你可能只有查天气和算数两个函数随手写写无所谓。等到要接图像分割、目标检测、OCR、文本转语音的时候每个工具都带着自己的模型权重、自己的依赖、自己的预处理和后处理逻辑。这时候如果工具代码和智能体逻辑混在一起会产生三个具体麻烦依赖冲突图像工具依赖某个版本的视觉库文本工具依赖另一个版本装在一个环境里互相打架。加载成本智能体启动时把所有工具的模型都加载一遍内存直接爆掉而你这一轮对话可能只需要其中一个。调试困难工具出问题时你分不清是模型没选对工具还是工具本身算错了。AgentLego 的解法是让每个工具都能独立实例化、独立测试、独立部署。它可以跑在进程内也可以起成一个服务让多个智能体共享。拆工具层不是为了架构好看是为了让故障可定位。1.3 两层的接口长什么样理解了定位再看接口就很自然了。两边的核心概念对应关系大致如下层次Lagent 侧AgentLego 侧作用单元AgentTool一次完整的任务 / 一个原子能力描述提示词中的工具段落工具的 name description 参数 schema告诉模型有什么能用调度ActionExecutor / Parser工具类的apply入口决定谁来执行和怎么执行结果观测文本Observation工具返回的字符串或字典回填进上下文中间那个适配层是关键AgentLego 的工具需要被包装成 Lagent 能识别的 Action反之亦然。不同版本的库对包装类的命名和位置有差异我一般不去背类名做法是先pip show看装的是哪个版本然后直接去包里翻actions或integration目录两分钟就能找到当期版本的适配入口。这条经验比记住任何类名都管用因为这类生态库迭代快网上的教程经常对不上你手上的版本。提示包装层存在的意义是翻译结构而不是翻译语义。如果你的工具参数在包装之后语义变了比如原本接受图片路径包装后变成接受 base64那模型一定会调错这是后面排查问题的重点怀疑对象。2. 环境落地依赖安装与模型接入的取舍环境这一步很多人栽在一次装全上。想着一口气把多模态工具全装上结果依赖解析跑了半小时最后卡在某个视觉库的编译错误。我的建议是先装一个最小可跑的组合跑通闭环之后再按需加工具。2.1 目录规划与虚拟环境不要小看目录规划这件事。智能体项目天然会有四类东西框架代码、工具代码、模型权重、临时产物图片、日志、中间结果。混在一个目录里后期根本没法维护。我习惯的结构是这样agent-demo/ ├── envs/ # 虚拟环境一个环境一套依赖 ├── models/ # 本地权重目录单独挂盘 ├── workspace/ # 运行时产物随时可删 │ ├── uploads/ │ └── logs/ ├── tools_custom/ # 自己写的工具类 └── run_agent.py虚拟环境用 conda 还是 venv 都行但有一条硬规矩工具依赖和框架依赖分环境装如果工具必须和框架同进程那就锁定一份 requirements 快照。理由很实际——工具链的依赖往往比框架激进一次不经意的pip install -U就能把框架搞崩而你没有快照的话根本回不去。安装顺序我一般这么走# 1. 先装框架本体确认能 import pip install lagent python -c import lagent; print(lagent.__version__) # 2. 再装工具库不要带 extras pip install agentlego python -c import agentlego; print(agentlego.__version__) # 3. 最后按需装单个工具的依赖 pip install agentlego[image] # 举例具体 extras 名以实际包的描述为准第三步刻意放在最后因为一旦出现编译报错你能立刻确定是哪个工具引入的而不是怀疑整个环境。2.2 模型接入API 和本地权重怎么选Lagent 支持多种模型接入方式粗分两类走远程 API 的 Client和走本地权重的 Client后者通常通过 OpenAI 兼容协议连自建的推理服务。选择依据不是哪个更强而是你的约束条件维度远程 API本地权重 自建服务起步速度几分钟需要下载权重、起服务工具调用稳定性通常较好指令遵循能力强取决于模型规模和微调质量单次成本按量计费主要是显存和时间数据可控性请求出网全部留在本地上下文长度受服务方限制自己可配调试便利性日志难抓全部日志自己掌握我的实际用法是双轨并行日常开发和调提示词用 API 版本因为迭代快、能快速验证提示词到底有没有问题等提示词稳定了切到本地权重做压测和成本核算。这样做的好处是当本地模型表现不好时你能明确区分是提示词写得不行还是模型能力不够而不是两边一起瞎猜。起本地服务时有个细节值得说一下温度参数对工具调用影响很大。智能体场景不是创作场景我一般把 temperature 调到 0.1 以下让模型尽量输出稳定的结构。有人为了让模型灵活一点调到 0.8结果同一句话反复调用同一个工具、参数每次都不一样排查半天才发现是这个参数的问题。2.3 装完先做三段式最小验证环境装好之后千万别直接跑智能体。我固定做三段验证每段单独可跑出问题一眼定位第一段工具能独立跑。绕开模型直接实例化一个 AgentLego 工具喂一个人造输入看返回结构。from agentlego.tools import BaseTool # 具体子类按需替换 # 伪代码思路先拿到工具实例再直接调用 tool SomeTool(devicecpu) print(tool.toolmeta) # 先看清楚它的元信息结构 result tool.apply(测试输入) # 直接调用不经过模型 print(type(result), result)这一步的重点不是结果对不对而是看清楚返回的数据类型。是字符串、字典还是对象后面回填上下文时这个类型决定了你要不要做序列化。第二段模型能独立跑。用 Lagent 的 LLM Client 发一句普通对话确认连通性和返回格式。from lagent.llms import GPTAPI # 走 OpenAI 兼容协议时常用的封装 llm GPTAPI( path你的模型服务地址, model_type你的模型标识, temperature0.1, ) print(llm.chat(你好请回复收到))第三段工具清单能被模型看见。把工具描述拼进提示词只问模型你现在能用哪些工具分别做什么不发真实任务。如果模型能把工具名和用途复述出来说明描述进入上下文成功如果它答非所问那问题在拼装环节不用往下查执行逻辑。这三段验证加起来十分钟但能省掉后面几个小时的方向性误判。3. 把工具注册进 AgentLego从内置工具到自写工具工具层是这个组合里最有价值也最容易被低估的部分。很多人只用了框架自带的几个工具然后就觉得智能体也就那样。实际上把业务里真正重复的操作封装成工具收益远大于换更大的模型。3.1 内置工具清单怎么读拿到工具库之后先别急着写代码花二十分钟把内置工具清单过一遍。看的时候带着三个问题看这个工具的输入输出是什么形态文本进文本出图片路径进字典出它的依赖重不重要不要额外下模型权重能不能跑在 CPU 上它的耗时大概多少毫秒级还是秒级这直接影响你要不要设超时和缓存。我通常写一个脚本把所有工具的名字和描述打出来存成一个清单文件方便后面挑import agentlego.tools as tools names [n for n in dir(tools) if not n.startswith(_)] for n in names: print(n)然后针对感兴趣的那几个单独print(obj.toolmeta)看完整描述。这一步的价值在于让你知道哪些能力不用自己写很多人费劲手写了一个功能后来发现工具库里本来就有只是名字不直观所以没找到。3.2 自己写一个工具的完整步骤内置工具覆盖的是通用能力业务里的具体操作还是得自己封装。写一个自定义工具我一般按这个顺序推进第一步定义元信息。名字用大驼峰、语义明确不要叫Tool1、DoIt。描述要写成能力说明而不是函数说明这一点极其重要下面单独讲。第二步声明参数结构。参数类型尽量用基础类型str、int、float、list不要用自定义对象。原因很朴素模型是通过文本理解参数类型的你给它一个自定义类它不知道该怎么填。第三步实现apply方法。这里面做三件事入参校验、核心逻辑、返回值规范化。返回值我习惯统一成字典包含一个结果字段和一个状态字段这样上层回填上下文时格式稳定。第四步本地单测。不接模型直接调apply覆盖正常输入、边界输入、异常输入三种情况。一个简化后的骨架长这样from agentlego.tools import BaseTool from agentlego.parsers import DefaultParser from agentlego.schema import ToolMeta class FileStatTool(BaseTool): default_desc ( 统计指定文本文件的行数与字符数。 当用户询问某个文件有多大、有多少行时使用本工具。 注意参数必须是工作区内的相对路径不接受绝对路径。 ) def __init__(self, workspace: str ./workspace): super().__init__( ToolMeta(nameFileStat, descriptionself.default_desc), parserDefaultParser, ) self.workspace workspace def apply(self, rel_path: str) - dict: Args: rel_path (str): 相对于工作区的文件路径例如 logs/a.txt Returns: dict: 包含 lines、chars、status 三个字段 import os full os.path.join(self.workspace, rel_path) if not os.path.exists(full): return {status: error, msg: f文件不存在: {rel_path}} with open(full, r, encodingutf-8, errorsignore) as f: text f.read() return { status: ok, lines: text.count(\n) 1, chars: len(text), }这段代码里最值得注意的不是逻辑而是那三行入参约束必须是工作区内的相对路径不接受绝对路径。实测下来模型对这类显式约束的遵循度明显高于隐式假设。不加这句它有一定概率传一个绝对路径进来然后你的工具返回一个文件不存在模型还会一本正经地把这个错误当成事实继续推理。3.3 工具描述写不好模型就调不对这是我在这个组合上踩得最深的坑值得单独展开。工具描述不是给人看的注释它是给模型的唯一信息来源。模型不知道你的代码里写了什么它只知道描述里写了什么。所以描述的质量直接决定调用准确率。我总结出四条写法规则都是在反复调错之后沉淀下来的规则一写什么时候用不只写是什么。只写本工具用于图像描述是不够的要写当用户上传图片并询问图片内容、场景、物体时使用本工具当用户只是询问图片格式、大小等信息时不要使用。后半句的排除条件往往比前半句更有用因为模型的错误大多发生在该不该用这个判断上。规则二参数描述里给出正例和反例。参数date的描述写日期模型可能填2024年3月5日写成日期格式必须为 YYYY-MM-DD例如 2024-03-05准确率立刻上一个台阶。格式类错误九成是描述里没给例子。规则三工具数量控制在个位数。工具越多模型的注意力越分散误选率越高。我做过粗略对比工具数从 4 个涨到 12 个之后同一个测试集上的正确选择率明显下滑。如果确实需要很多能力就做分层一层是粗粒度工具如处理文档工具内部再决定用哪个具体实现。规则四描述长度适中别写小作文。一个工具描述控制在三四句话超过就会挤占上下文而且模型容易抓错重点。真正复杂的信息放在参数描述里而不是堆在总描述里。描述写法例子模型表现过简文本处理工具几乎必选错不知道该什么时候用只说能力统计文件行数大致能选对但参数常错能力 触发条件统计文件行数。用户询问文件大小、行数时使用选择准确参数仍可能错能力 触发条件 排除条件 参数示例上面三条叠加我实测下来最稳的形态注意改工具描述属于低成本高收益的优化。遇到调用不准先改描述别急着换模型。我至少有三四次本来准备升级模型结果只改了描述里的两句话就解决了。4. 在 Lagent 里组装 Agent提示词、解析器与执行循环工具准备好了接下来是把它们接进智能体的循环。这一层看起来是配置实际上是整个系统里最需要动脑的地方。4.1 Action 解析器到底在干什么模型输出的是一段自然语言文本里面夹着我要调用某某工具参数是某某。解析器的任务是把这段文本变成结构化调用。以最常见的 ReAct 风格为例模型被要求按固定格式输出形如Thought: 我需要先确认文件有多少行 Action: FileStat Action Input: {rel_path: logs/a.txt}解析器要做的就是用规则正则或状态机把Action和Action Input抠出来。这里的脆弱点非常明显只要模型少写一个冒号、把 JSON 写成单引号、或者在 JSON 后面多写一句话解析就失败。我的应对办法有三条提示词里给完整示例至少给两个不同工具调用的例子让模型模仿格式。解析器容错对 JSON 部分做宽松解析先尝试标准 JSON失败则尝试补引号、截取第一个花括号到最后一个花括号之间的内容。解析失败要有兜底不要直接抛异常终止而是把格式错误请按示例格式重新输出作为一条观测回填让模型自我纠正一次。实测这一次重试能救回大部分格式问题。import json, re def parse_action(text: str): m_action re.search(rAction\s*[:]\s*(\S), text) m_input re.search(rAction\s*Input\s*[:]\s*(\{.*\}), text, re.S) if not m_action: return None, 未找到 Action 行 name m_action.group(1).strip() if not m_input: return None, 未找到 Action Input 行 raw m_input.group(1) try: args json.loads(raw) except json.JSONDecodeError: # 宽松兜底截取首尾花括号再试一次 s, e raw.find({), raw.rfind(}) try: args json.loads(raw[s:e1]) except Exception: return None, Action Input 不是合法 JSON return (name, args), None这段代码不复杂但每一条分支都是我实际遇到过的问题。特别是中英文冒号混用——模型有时会输出全角冒号正则里不加就会漏匹配而且这个 bug 极难发现因为日志里看起来格式完全正确。4.2 提示词模板的结构拆解智能体的提示词和普通对话的提示词不是一回事。它更像一份操作规程我一般按四段组织角色与目标一句话说清你是谁、要完成什么。别写长写长了模型记不住。可用工具清单由框架自动拼装每个工具一段描述。这一段不要手写一定要从工具的元信息里动态生成否则你改了工具忘了改提示词就会出现提示词里有、实际没有的幽灵工具。输出格式规范明确要求 Thinking / Action / Action Input 的格式并给出完整示例。终止条件告诉模型什么时候该输出最终答案而不是继续调工具。这一条最容易被省略但省略之后模型会一直调工具停不下来。第四点值得多说。终止条件要写成可判断的形式比如当你已经获得足够信息可以直接回答用户问题时输出Action: Finish并把答案放在 Action Input 里。这种显式的终止动作比如果不需要工具就直接回答要可靠得多因为后者需要模型自己做一次隐式判断而它对隐式判断的稳定性远不如对显式指令的遵循。4.3 多轮状态与流式输出的处理智能体天然是多轮的而且轮数不固定。这里有两个具体问题上下文膨胀。每一轮都会追加模型输出 工具结果五轮之后上下文可能已经几千字。我的做法是对工具结果做截断字符串超过一定长度比如 800 字就保留头尾、中间省略并显式标注内容已截断。不截断的话一个返回长文本的工具就能把上下文占满后面的轮次模型基本失忆。状态管理。不要把对话历史存在全局变量里。我习惯用一个会话对象包住历史列表每次请求带上会话 id这样并发请求之间不会串数据。这个坑我在早期版本踩过——两个用户同时提问答案互相串了原因就是历史存在模块级的 list 里。流式输出方面如果要做前端展示一般把模型的思考片段和工具的最终结果分开推。工具结果不建议流式推因为它是结构化的分片传输反而增加前端解析负担。我一般只对流式的文本部分做增量推送工具结果整块返回。5. 联调阶段最容易翻车的五个地方前面都跑通了真正组合起来还是会有各种奇怪现象。这一节我按症状 → 定位链路 → 修复的方式写方便你按图索骥。5.1 反复调用同一个工具死循环怎么定位症状日志里同一个工具被连续调用五六次参数几乎一样最后要么超轮数上限要么答非所问。定位链路先把每一轮的模型原始输出完整打出来不要只看解析后的结果。很多问题在原始输出里一目了然。看模型有没有收到工具结果。如果工具执行成功但模型下一轮还在调同一个工具说明结果没有正确回填或者回填的格式让模型看不出这是结果。检查回填文本有没有明确的前缀比如Observation: ...。没有前缀的话模型可能把自己的输出和工具结果混在一起理解。检查工具返回值是不是空。返回空字符串时模型会认为这次调用没成功于是重试。修复方案一是给工具返回值加显式状态成功/失败 内容二是设置最大轮数我一般设 6 到 8 轮到上限强制要求模型输出当前最优答案。别指望模型自己会停上限是必需品不是可选项。5.2 参数格式不对从日志反推的三步法症状解析成功但工具执行报错说参数类型不对或缺少字段。定位链路第一步看解析器输出的结构化参数而不是模型原文。如果结构化参数已经错了问题在提示词如果结构化参数对但工具报错问题在参数声明。第二步对比参数名。模型填的 key 和工具声明的 key 差一个字符比如file_pathvsfilepath是最常见的情况。这类问题几乎全是描述里没写清楚 key 名导致的。第三步看类型。模型经常把数字写成字符串3而不是3把列表写成逗号分隔的字符串。在工具入口做一次类型归一化比反复调提示词有效得多。我现在的习惯是所有工具入口先做一次参数清洗把字符串数字转数字、把单元素列表展开、把多余字段丢掉。这一步多加十行代码能消掉一大半参数类报错。5.3 多模态结果撑爆上下文症状接上图像类工具后前两轮正常第三轮开始模型答非所问或者直接报上下文超限。原因图像工具的返回里经常带一大段描述或坐标列表一次返回几百上千字多轮累积就爆了。修复工具侧就把结果摘要化只返回模型真正需要的信息比如检测工具只返回检测到 3 个物体人、车、树而不是完整坐标数组。上层再做一次长度保护超过阈值截断并标注。如果确实需要保留细节把详细结果存到文件里上下文里只放结果已保存至 xxx摘要为 xxx让模型在需要时再调工具读文件。第二种做法我用了挺久好处是上下文干净坏处是多一次工具调用。权衡下来对于结果体积大的工具这个代价是值得的。5.4 本地模型不听话三个具体调整用 API 版本调得好好的提示词切到本地小模型后格式全乱这是常态。调整顺序我一般这样先改示例不改规则。小模型对示例的模仿能力强于对抽象规则的理解。把示例从 1 个增加到 3 个覆盖不同工具类型往往比加十行规则说明有效。再缩短上下文。小模型对长上下文的中间部分注意力弱把工具清单里不常用的工具描述压缩把历史轮次做摘要效果比换模型明显。最后才考虑换模型。如果上面两步做完格式遵循率还是上不去那就老老实实换一个指令遵循更好的模型。在工具调用这个场景上模型的指令遵循能力比它的通用知识能力重要得多一个知识面窄但格式老实的模型比一个聪明但爱自由发挥的模型好用。5.5 并发与超时被忽略的稳定性问题单机单请求跑得好一上并发就出问题通常出在这几个地方问题表现处理方式工具实例共享多请求同时用同一个工具结果互相污染每个会话独立实例化或工具内部无状态模型服务排队请求堆积响应时间暴涨设连接超时和读超时超时降级返回文件命名冲突临时文件互相覆盖用会话 id 时间戳命名日志混杂无法区分是哪个请求每条日志带 trace id超时这一项特别重要。工具调用是模型 外部服务的串联任何一环卡住整个请求就挂住。我一般设两级超时工具级比如 20 秒和整体级比如 90 秒工具超时就返回该工具执行超时让模型决定是换个方式还是直接回答。这样至少用户能拿到一个结果而不是一直转圈。6. 从 Demo 到能用一个图文问答场景的完整串联理论说完了走一遍完整链路。选这个场景是因为它天然需要多模态工具能把这套组合的价值体现出来。6.1 场景拆解与工具选型需求很朴素用户上传一张图片问关于图片的问题。问题分几类图里有什么 → 需要图像描述能力图里有几个人 → 需要目标检测能力把图里的文字念出来 → 需要 OCR 能力这张图多大 → 不需要模型纯文件属性对应工具选型描述工具、检测工具、OCR 工具加一个自己写的文件属性工具。前三个用工具库里的现成实现第四个自己写十几行代码。这里的关键判断是不要一开始就把所有工具都挂上。我先挂描述和文件属性两个把闭环跑通再逐个加检测和 OCR。每加一个跑一遍固定的测试问题集确认旧功能没退化。这个增量接入 回归测试的习惯让我避免了很多加了新工具把老功能搞坏的情况。6.2 完整代码骨架下面是我常用的组织方式把配置、工具、Agent 三段分开import os from lagent.agents import ReAct from lagent.actions import ActionExecutor from lagent.llms import GPTAPI # ---------- 1. 模型 ---------- llm GPTAPI( pathos.getenv(LLM_BASE_URL, http://127.0.0.1:8000/v1), model_typeos.getenv(LLM_MODEL, local-chat), temperature0.1, max_new_tokens1024, ) # ---------- 2. 工具 ---------- # 现成工具直接实例化自定义工具用自己写的类 my_tools [ image_caption_tool, # 图像描述 object_detect_tool, # 目标检测 ocr_tool, # 文字识别 FileStatTool(workspace./workspace), ] # 关键把 AgentLego 工具包成 Lagent 能识别的 Action # 包装类的具体位置随版本变化先 import 试报错就去包里找 actions 目录 from lagent.actions import ActionExecutor actions ActionExecutor(build_actions(my_tools)) # ---------- 3. Agent ---------- agent ReAct( llmllm, action_executoractions, max_turn6, ) resp agent.chat(这张图里有什么工作区里的 demo.png) print(resp)其中build_actions是我自己写的一个小适配函数负责把不同形态的工具统一转成 Action 列表。之所以不直接用库里的包装器是因为我需要在转换过程中加一层参数清洗前面提到的类型归一化。这层薄封装看起来多余但它是你后面改任何东西的抓手。调试时我强烈建议打开详细日志把每一轮的 prompt、模型原始输出、解析结果、工具返回值四样都打出来。这四样对齐看几乎所有问题都能在两分钟内定位。6.3 效果评估与迭代节奏跑通之后怎么判断好不好用我不看单次对话看一个固定的小测试集。做法很土但有效准备 20 条左右的问题覆盖四类情况该用工具 A、该用工具 B、该直接回答、该拒绝回答每条标注期望行为。每次改动后跑一遍统计三个指标工具选择正确率、参数正确率、最终答案可用率。这三个指标要分开看因为它们的优化手段完全不同选择错 → 改工具描述参数错 → 改参数描述和加清洗答案不可用 → 大概率是上下文回填或终止条件的问题。我自己的经验是第一版跑下来工具选择正确率往往只有六成左右改完描述能到八成五以上再往下就属于模型能力的边界了。卡在八成五左右时不要再硬调提示词那是在跟模型的能力上限较劲收益极低。这时候要么换更强模型要么把任务拆得更细、让每一步的判断更简单。还有一个常被忽略的点把失败样例存下来。我专门建了一个目录存那些模型做错了的输入和输出每个季度回看一次会发现很多错误是同一模式反复出现然后针对这个模式改一条描述就批量解决了。这比零散地调参有效得多。最后分享一个我个人一直在用的判断标准当你发现自己在反复调提示词、每次只能修好一两个 case 的时候就该停下来想想是不是工具的设计有问题了。我这几次比较大的性能提升没有一次是靠改提示词实现的全是通过把一个大工具拆成两个小工具、或者把工具的返回值改得更模型友好做到的。模型是给定的工具是你可控的把可控的那部分做扎实比跟不可控的部分较劲划算得多。
