企业官网建设流程全解析

做智能体这件事，最容易卡住新人的从来不是模型选得好不好，而是"想"和"做"这两件事被混在了一起。Lagent 和 AgentLego 这一对组合之所以在圈子里被反复提起，本质上是把这两件事拆开了：一个负责让模型学会思考、决策、调度，另一个负责把图像描述、目标检测、文字识别、图像编辑这些具体能力封装成标准零件。你手上如果有一批图片要处理、有一堆工具要串起来、有一个"能自己看图然后给出结论"的需求，这套组合值得花一个下午跑通。下面这些内容是我自己从零搭起来、又在几个小项目里反复改过的记录，适合完全没接触过智能体框架的新手照着做，也适合已经用过其他框架、想看看这套东西差别在哪的人对照着读。

1. 先想清楚：为什么是 Lagent 加 AgentLego 这个组合

1.1 两个框架各管一段，边界比功能更重要

很多人第一次看到这两个名字，会以为它们是竞品，选一个就行。实际不是。Lagent 的定位是"智能体骨架"，它关心的是：模型怎么接收任务、怎么把任务拆成若干步、每一步该调用哪个工具、工具的返回结果怎么塞回上下文、什么时候停下来。它内置的工具有限，主要是搜索、计算、代码执行这类偏文本的通用能力，重点在流程编排和输出解析上。

AgentLego 的定位完全不一样，它是"工具箱"。图像描述、文字识别、目标检测、图像分割、图像编辑、姿态估计这类多模态能力，在 AgentLego 里被统一包装成一个个工具对象，每个对象自带名字、描述、参数结构、调用方法。它不关心你用什么智能体框架，只负责"给我一张图和一个指令，我还你一个结果"。

把这两句话摆在一起，分工就清楚了：Lagent 是脑子，负责决定"下一步干什么"；AgentLego 是手脚，负责"把这一步干出来"。真正让一个智能体能完成复杂任务的关键，从来不是脑子多聪明，而是手脚够不够多、接口够不够统一。这也是我一开始最看重的地方——我需要的是一个能不断往里塞新工具的结构，而不是一个功能已经写死的成品。

1.2 三套方案的横向对比，为什么最后选了这一套

在动手之前我对比过三种常见路线，结论放在下面这张表里，你可以对照自己的场景看。

我选第三条路的原因很实在：智能体的调优过程，九成时间花在"为什么模型没有按我想的调用工具"上。这个问题只有在能看到完整提示词、能看到模型原始输出、能随手改解析逻辑的情况下才查得动。图形化工具把这一层藏起来了，出问题时你只能反复改参数试运气。代码型框架虽然前期麻烦，但每一次失败都能定位到具体一行。

AgentLego 在这里的价值被放大了：它的工具是标准化的，我换一个图像工具不需要改智能体逻辑，只需要在工具清单里换一个名字。这种"零件可替换"的特性，在快速试错的阶段非常省时间。

1.3 三个最常见的认知误区，早点绕开

第一个误区是把工具当成越多越好。我最初一口气注册了十几个工具，结果模型频繁调错，明明要识别文字却去调了目标检测。后来砍到六个，准确率立刻上来了。原因不复杂：工具的名字和描述都会拼进提示词，工具越多，提示词越长，模型要在里面做选择的难度就越大。七个左右的工具是一个比较舒服的区间，超过十个就要考虑分组或者分层调度了。

第二个误区是以为工具描述随便写写就行。工具的description字段，本质上就是写给模型看的接口文档。你写得含糊，模型就用得含糊。我见过一个描述只写了"处理图片"的工具，模型几乎从来没用对过；改成"输入一张本地图片路径，输出图中主要物体的中文描述，适用于风景、人物、商品图"，命中率肉眼可见地提升。这件事没有技术含量，但收益极大。

第三个误区是忽略返回值的大小。AgentLego 的某些工具返回的是结构化的长 JSON，包含每个检测框的坐标、置信度、类别名。如果原样塞回对话上下文，几轮之后上下文就被撑爆了，模型还会被这些数字干扰。正确做法是在工具包装层就做裁剪，只把模型真正需要的那部分返回上去。

2. 从裸机到第一个能跑起来的智能体

2.1 环境准备：版本锁定比装得快更重要

这类框架最容易翻车的地方不是代码，是依赖。Lagent 本身很轻，主要依赖大模型调用库和少量解析工具；AgentLego 因为要跑各种视觉模型，会拖进来一大串深度学习相关的包。两边对版本的要求未必一致，尤其是深度学习框架和模型加载库的版本，稍不注意就是一堆导入报错。

我的做法是给智能体主流程单独建一个环境，然后按需装工具。具体顺序是这样：

# 建议 Python 3.9 到 3.11，太新或太旧都容易踩坑 conda create -n agent-demo python=3.10 -y conda activate agent-demo # 先装深度学习基础件，注意和你的显卡驱动匹配 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 再装两个框架 pip install lagent pip install agentlego # 工具依赖按需安装，AgentLego 支持分模块装 pip install agentlego[image]

最后那行是关键。AgentLego 把工具按领域做了分组，全量安装会拉进来一堆你可能永远用不上的模型依赖，装完几个 G 就没了。只装image分组，够你跑通大部分视觉类工具。等你确定要用某个具体工具时，再针对性补装。

提示：装完之后先别急着写业务代码，跑一遍python -c "import lagent, agentlego; print(lagent.__version__, agentlego.__version__)"，确认两个包都能正常导入。很多后续的诡异报错，源头都是这一步没验证。

2.2 模型接入的三种姿势，按预算和隐私要求选

智能体的"脑子"来自大模型，接法有三种，各有各的适用场景。

第一种是调用云端接口，最省事。你只需要一个模型服务的地址和密钥，配好之后就当黑盒用。优点是零显存压力、模型能力强、响应稳定；缺点是每轮对话都在花钱，而且数据要出本地。做原型验证阶段我一般选这个，因为能快速把流程跑通，把不确定性集中在框架本身而不是模型质量上。

第二种是本地部署开源模型，适合数据不能外传的场景。七 B 量级的模型在单张消费级显卡上跑推理是可行的，但要注意量化。我用的是四比特量化版本，显存占用从十几个 G 压到六七个 G，回答质量的下降在工具调用任务上几乎感知不到——因为工具调用更需要的是格式遵循能力，而不是知识广度。

第三种是混合模式：主流程用本地小模型，遇到确实答不好的环节再临时调云端。这种模式听着复杂，实现起来其实就是两套配置切换，但要在代码里做好降级逻辑，否则出错时很难判断是哪一层的锅。

配置写成字典传进去最直观：

from lagent.llms import GPTAPI llm = GPTAPI( model_type="gpt-3.5-turbo", # 换成你实际可用的模型名 key="YOUR_KEY", api_base="YOUR_ENDPOINT", max_tokens=2048, temperature=0.01, # 工具调用场景必须压低随机性 )

temperature这个参数我要单独说一句。做闲聊的时候调到零点七、零点九很自然，但做工具调用，一定要压到零点一以下，最好是零。原因很直白：工具调用依赖固定的输出格式，模型一旦开始"发挥"，输出里多一个换行、少一个括号，解析器就直接崩了。我早期为了省钱用默认温度，十次里有三次解析失败，改成零点零一之后基本稳定。

2.3 跑通第一个 Demo：先让它学会看图说话

不要一上来就搭复杂流程，先用最小的例子验证链路。我选的第一个任务是：给一张图片路径，让智能体调用图像描述工具，返回一段文字。

import agentlego from agentlego import load_tool agentlego.list_tools('image') # 先看看有哪些工具可用 tool = load_tool('ImageDescription', device='cuda') print(tool.description) # 这一步非常关键，看清楚描述 result = tool.apply('test.jpg') print(result)

第一次跑这段代码时大概率会卡住几分钟，别慌，那是在下载模型权重。下载完之后第二次就秒开了。这一步的产出不是"跑通了"，而是你拿到了两样东西：工具的准确描述文本，和工具的实际输入输出格式。这两样东西你后面写智能体的时候要反复用到。

验证完工具，再验证智能体能不能自己决定调用它：

from lagent.actions import ActionExecutor from lagent.agents.react import ReAct from lagent.actions import BaseAction # 用一个最简包装把工具塞进动作执行器 class ImageDescAction(BaseAction): def run(self, image_path: str): return load_tool('ImageDescription', device='cuda').apply(image_path) executor = ActionExecutor(actions=[ImageDescAction()]) agent = ReAct(llm=llm, action_executor=executor) print(agent.chat("帮我看看 test.jpg 里有什么"))

不同版本的类路径会有差异，我这里写的是示意结构，你按自己装的那个版本调整导入路径。重点在结构本身：动作执行器负责"能做什么"，智能体负责"决定做什么"，这两层是分开的，这一点在所有版本的 API 里都一样。

2.4 显存和延迟的粗算，别等爆了才想

视觉工具吃显存这件事，我吃过一次亏。跑了三个工具之后显存直接爆掉，报错信息还很含糊。后来算了一下才明白：每个工具在被load_tool的时候会把模型加载到指定设备上，而且默认常驻。三个中等规模的视觉模型同时待在显存里，十几 G 就没了。

粗略的估算方法是：单个视觉类工具模型，中等规模大概占两到四个 G，大一点的六到八个 G。你要同时用几个，就把它们加起来，再加上大模型本身的占用。如果超了，有两条路：一是把非核心工具放到 CPU 上跑，速度慢一点但能活；二是改成懒加载，用到的时候才加载，用完就释放。

延迟方面，单个工具的调用耗时通常由三部分组成：模型首次加载、预处理、推理。首次加载最慢，几秒到几十秒不等；预处理一般几十毫秒；推理本身在 GPU 上通常不到一秒。所以真正影响体验的是首次加载。我的处理办法是在服务启动时做一次"预热"，拿一张空白图跑一遍，把模型权重拉进内存，后面的请求就快了。

3. 拆开 Lagent：智能体的"脑子"到底是怎么转的

3.1 一个 Agent 的三个核心部件

Lagent 里的 Agent 抽象，剥掉各种封装之后其实就是三样东西：给模型的系统提示词、可用的工具清单、输出解析器。系统提示词告诉模型"你是谁、你要按什么格式回答、你有几步可以走"；工具清单提供"你能调什么"；解析器负责从模型返回的大段文本里，把"思考过程"和"动作指令"分别抠出来。

ReAct 这个范式之所以被广泛采用，就是因为它的思路足够朴素：让模型交替输出"思考"和"动作"，动作执行完拿到"观察结果"，再继续思考。这个循环天然适合工具调用，因为每一步都有明确的落脚点，出问题时你能看到它停在哪一步、想了什么、做了什么。

理解了这个结构，调优的思路就清楚了：输出格式不稳定，改提示词里的格式说明；工具选错，改工具描述；某一步结果没被利用，改解析器。所有的调整都对应到具体部件，而不是笼统地"换个模型试试"。

3.2 工具注册：名字取得好，成功率高一截

工具的注册方式很机械，但命名这件事很讲究。模型的工具选择能力，很大程度上依赖名字的语义匹配度。我试过两组命名，同样的功能，效果差挺多：

原因不难理解：模型在做选择时，本质是在把用户的话和自己手上的工具名做语义比对。你叫tool2，它根本不知道该什么时候用；你叫ImageDescription，用户说"看看这张图里是什么"，语义天然就贴上去了。

除了名字，还有个细节：不要让两个工具的描述高度重叠。我曾经有两个工具，一个叫"图像描述"，一个叫"图像问答"，描述里都写了"回答关于图片的问题"，结果模型在这两个之间反复横跳。后来把前者改成"不针对具体问题，输出整图的中文描述"，后者改成"必须提供具体问题，例如'图里有几个人'"，混淆立刻消失。

3.3 提示词里的格式示例，比你想的重要得多

所有智能体框架都要求模型按固定格式输出，Lagent 也不例外。但只写"请按 Thought/Action 格式输出"是不够的，模型对格式的理解千差万别，尤其是一些对指令遵循能力一般的小模型。

我现在的做法是在系统提示词里塞一个完整的样例，包括一次失败后的重试：

你可以使用以下工具： {tool_descriptions} 回答必须严格遵循以下格式，不要输出多余内容： Thought: 你需要思考的内容 Action: 工具名 Action Input: 工具参数（JSON 格式） 示例： Thought: 用户想知道图里的文字，我应该用文字识别工具 Action: TextOCR Action Input: {"image_path": "/data/a.jpg"} 如果工具返回结果为空或报错，最多重试一次，仍失败则直接给出结论。

注意最后那句"最多重试一次"。这句话省了我无数次死循环。模型在没有明确终止条件时，会孜孜不倦地重复同一个动作，因为它觉得"上一次没成功，再试一次说不定就好了"。给个上限，它就会老老实实放弃。

3.4 记忆和多轮：别让上下文变成垃圾桶

智能体跑多轮任务时，上下文会迅速膨胀：每一轮的思考、动作、观察结果全部堆进去。到第五六轮的时候，前面的无关内容已经占了大量位置，模型开始"忘事"。

我的处理比较土但有效：每一轮结束后，把"观察结果"做一次压缩，只保留关键结论，原始的长输出丢掉。比如目标检测返回了二十个框，我在塞回上下文之前只保留"检测到 5 个人、1 辆车、置信度均高于 0.8"这一句。这样上下文增长是线性的，不是爆炸的。

另外，工具清单不需要每轮都全量塞进去。如果任务能明确分成几个阶段，每个阶段只给相关的工具，模型的选择压力小很多。这属于进阶优化，一开始不用做，但当你发现工具超过十个的时候，这就是必经之路。

4. 拆开 AgentLego：工具是怎么变成"乐高积木"的

4.1 统一的工具契约：四个字段说清楚一切

AgentLego 里每个工具都遵循同一套契约，核心是四个部分：名字、描述、输入参数结构、调用方法。这套契约的价值在于，任何一个工具被包装成这个形态之后，智能体那边就不需要关心它的内部实现。

调用方式统一成两步：先load_tool拿到对象，再apply传参数。参数可以是位置参数，也可以是关键字参数，具体看工具定义。这种一致性看起来平平无奇，但当你需要在一套流程里混合调用图像工具、文本工具、外部接口时，一致性带来的可维护性提升非常明显。

还有一个容易被忽略的点：工具对象上挂着description属性，这个描述是已经写好的、专门给模型看的。很多人自己重新写一遍描述，反而写得更差。我的建议是先打印出来读一遍，觉得不够具体再补，但不要推倒重写。

4.2 视觉类工具的实际使用感受

我在几个小项目里用过的工具大致分几类，体感如下：

用下来最深刻的体会是：这些工具的能力边界，比它们的宣传语窄。图像描述对复杂场景的细节把握有限，文字识别对版式复杂的图基本无能为力。如果你的任务强依赖这些能力，要么在预处理上下功夫，要么在流程里加一步"人工确认"。

4.3 自定义工具：把自己写的函数变成积木

真正让这套东西有价值的，是你能把自己写的任何函数包装成工具。我有个需求是"把分析结果写成 markdown 文件"，这个能力 AgentLego 里没有，但包装起来只要几十行：

from agentlego.apis import BaseTool class WriteReport(BaseTool): default_desc = ( "把一段文本写入本地 markdown 文件。" "输入 file_path（字符串，以 .md 结尾）和 content（字符串，markdown 正文）。" "返回写入是否成功。" ) def apply(self, file_path: str, content: str) -> str: with open(file_path, 'w', encoding='utf-8') as f: f.write(content) return f"已写入 {file_path}，共 {len(content)} 字"

default_desc就是给模型看的说明书，写法上要遵循三个原则：说清楚输入是什么类型、有没有格式约束、输出是什么。这三条写全了，模型调用的准确率会高很多。

包装完之后，这个工具就和其他工具一样可以被智能体调用，完全不需要改智能体那边任何代码。这就是"可插拔"的实际含义——不是概念上的漂亮，是真的换一个类就能用。

4.4 工具依赖隔离：一个容易忽略的工程问题

AgentLego 的工具背后是不同的模型，不同的模型依赖不同版本的库。我遇到过一次：文字识别工具要求某个版本的图像处理库，图像编辑工具要求另一个版本，两个装在一起就冲突。

解决办法有两个。轻量的做法是不要在同一个进程里加载冲突的工具，把工具拆成独立的服务，智能体那边用 HTTP 调。重一点的做法是每个工具一个容器，用统一的网关暴露。前者适合个人项目，后者适合有部署需求的场景。

我现在的习惯是：核心流程里的工具控制在三个以内，保证它们依赖兼容；边缘工具做成独立服务，失败了也不影响主流程。这个取舍在项目初期就要想清楚，等代码写完了再拆，成本会高很多。

5. 组合实操：搭一个"看图、识别、出报告"的完整流程

5.1 需求拆解与工具清单确定

我给自己定的任务是：给一个文件夹的图片，逐张分析，输出一份 markdown 报告，内容包括每张图的内容描述、图中识别到的文字、以及一句综合判断。

拆解成智能体视角的步骤：先拿到图片列表，然后对每张图调用图像描述，再调用文字识别，最后汇总写入文件。这里面有一个关键判断——这个任务其实不需要智能体。因为步骤是完全确定的，用普通脚本串起来更快更稳。

但我还是用智能体实现了一遍，原因是想验证：当步骤不确定时，这套结构能不能撑住。所以我把任务改成了"给我一个文件夹，你自己看看里面是什么，挑出有文字的那些图，把文字提取出来做成一份清单"。这一改，步骤就变成动态的了，脚本写不了，必须靠模型判断。

工具清单最终确定为四个：文件夹列举、图像描述、文字识别、文件写入。四个工具，模型选择压力小，描述之间也没有重叠。

5.2 代码骨架：三层结构分开写

我把代码分成三层，这样改起来互不影响。

# 第一层：工具定义 from agentlego.apis import BaseTool import os class ListImages(BaseTool): default_desc = "列出指定文件夹下的所有图片文件，返回文件路径列表。输入 folder_path 字符串。" def apply(self, folder_path: str): exts = ('.jpg', '.jpeg', '.png', '.bmp') return [os.path.join(folder_path, f) for f in os.listdir(folder_path) if f.lower().endswith(exts)] class WriteReport(BaseTool): default_desc = "把 markdown 文本写入文件。输入 file_path 和 content 两个字符串。" def apply(self, file_path: str, content: str): with open(file_path, 'w', encoding='utf-8') as f: f.write(content) return "写入成功"

# 第二层：把 AgentLego 工具包成 Lagent 能用的动作 from lagent.actions import BaseAction from agentlego import load_tool class VisionAction(BaseAction): def __init__(self, tool_name, device='cuda'): super().__init__() self._tool = load_tool(tool_name, device=device) def run(self, **kwargs): # 关键：对返回值做裁剪，只把结论送回上下文 raw = self._tool.apply(**kwargs) text = str(raw) return text[:800] + ('...(已截断)' if len(text) > 800 else '')

# 第三层：组装智能体 from lagent.actions import ActionExecutor from lagent.agents.react import ReAct executor = ActionExecutor(actions=[ ListImages(), VisionAction('ImageDescription'), VisionAction('TextOCR'), WriteReport(), ]) agent = ReAct( llm=llm, action_executor=executor, max_turn=8, # 硬性上限，防止死循环 ) answer = agent.chat("看看 /data/pics 这个文件夹，把有文字的图片挑出来，文字提取成一份 md 报告存到 /data/report.md")

三层结构的价值在调试时体现得最明显：模型选错工具，去看第一层的描述；工具执行报错，去看第二层；流程跑不通，去看第三层的参数。

5.3 实际运行记录和两处关键调整

第一版跑出来的结果是：智能体先调了文件夹列举，拿到二十个路径，然后一次性把二十个路径全塞进图像描述工具的参数里。工具当然报错了，因为它一次只能处理一张。

问题出在工具描述上。我写的是"列出图片文件"，没写清楚"每次只能处理一张"。补上这句之后，模型改成了一张一张处理。这就是前面说的：工具描述模糊，模型就用得模糊，而且它不会主动去猜你的限制条件。

第二个调整是返回值裁剪。文字识别第一次返回了完整的结构化数据，包含每个文字块的位置坐标和置信度，长度好几千字符。塞进上下文之后，模型在第二轮就开始胡说，把坐标数字当成了图片内容。加了裁剪逻辑之后，一切正常。

最终一次完整运行，八轮之内完成了任务，报告的格式也符合预期。这个结果谈不上惊艳，但足以证明这条链路是通的，后面接什么工具都可以。

5.4 成本和延迟：跑之前先算一笔账

本地跑的话，主要成本是显存和时间。四个工具里有两个是视觉模型，加上大模型，一张卡跑下来大概十 G 上下。处理二十张图，每张图两轮工具调用，整体耗时在两到三分钟。

云端跑的话，主要成本是 token。一次完整的工具调用循环，大概消耗两到四千 token。二十张图就是几万 token。这个量级对于原型验证完全可接受，但如果要做成日常工具，就得考虑缓存——同一张图重复调用的结果可以存下来，避免重复付费。

我现在的做法是给工具层加一层简单的缓存：以图片路径加上文件修改时间做键，结果存在本地。改图才会重算，不改就直接读。这一个小改动，把重复运行的耗时砍掉了七成以上。

6. 排障实录：我踩过的坑和对应解法

6.1 模型不调用工具，只在原地"思考"

这个现象我遇到最多次。表现是模型一直输出 Thought，就是不输出 Action，最后自己给自己一个结论就结束了。

排查顺序是这样的：先看工具清单有没有真的传进提示词（有时候是模板变量没渲染出来）；再看工具描述是不是太空泛；最后看格式示例有没有给。我经历过的一次是提示词模板里工具描述的位置写成了空字符串，模型手上根本没有工具，那它当然只能干想。

还有一种情况是模型本身能力不够，七 B 以下的模型在工具调用任务上经常表现不稳定。这时候换模型比调提示词有效得多。

6.2 动作名对不上，报"未知工具"

模型输出的动作名和注册的工具名不完全一致，多一个空格、大小写不对、或者干脆自己改了个更顺口的名字。解析器严格匹配就会失败。

我的处理是加一层容错：匹配前统一转小写、去空格，再做一次模糊匹配，比如去掉下划线后比对。如果还是匹配不上，就返回一条明确的错误信息到上下文里，让模型自己纠正——"没有名为 xxx 的工具，可用工具是：a、b、c"。这句话很管用，模型看到清单之后一般下一轮就改对了。

6.3 返回内容解析失败

典型报错是 JSON 解析异常。原因基本是模型在 JSON 前后加了多余的话，比如"以下是参数：{...}希望有帮助"。严格解析必崩。

解法是不要用严格的 JSON 解析器，先用正则把最外层的一对花括号抠出来，再解析。这个改动很小，但把解析成功率从七八成拉到了九成五以上。剩下的失败案例，加一次重试基本能兜住。

6.4 完整排查速查表

6.5 几条只在实际动手后才会明白的经验

第一条：先让流程跑通，再谈效果。我一开始就纠结图像描述准不准，结果花了两天调工具，最后发现流程本身有 bug，白费功夫。正确的顺序是先用最简单的工具跑通全链路，确认每一环都通，再逐个替换成更好的工具。

第二条：日志要打得足够细。智能体出问题时，你需要看到完整的提示词、模型的原始输出、解析后的动作、工具的实际返回。这四样东西缺一样，排查时间就要翻倍。我现在的习惯是在开发阶段把这四样全部打到文件里，出问题直接翻日志，比反复加 print 快得多。

第三条：不要迷信大而全的工具集。工具数量增长带来的复杂度是指数级的，每加一个工具，模型的选择难度、你的调试成本、依赖冲突的概率都在上升。克制地加工具，比堆工具更能做出能用的东西。

7. 最后说几句我自己的取舍

这套组合我用下来的感受是：它的价值不在"开箱即用"，而在"改得动"。框架本身不复杂，代码量不大，你能看懂每一层在干什么，出问题能定位到具体位置。这对于需要长期迭代的项目来说，比功能多重要得多。

如果让我给刚上手的人一条建议，那就是先把一个工具玩透。拿图像描述这一个工具，从直接调用、到包装成动作、到塞进智能体、到处理它的各种失败情况，完整走一遍。这一遍走完，剩下的工具都是同一个套路，换个名字而已。反过来，如果一开始就想着把十个工具全接上，大概率会在依赖冲突和描述调优里迷路。

还有一个我坚持的习惯：任何新工具接入之前，先单独跑一次，把它在不同输入下的表现记下来。哪些图它处理得好，哪些图它会翻车，心里有个底，后面设计流程的时候才知道该在哪里加兜底。这件事花不了多少时间，但能省掉大量"为什么智能体给出的结论是错的"这类难查的问题。