在 Nexent 上从零做一个能用的智能体,中间有 7 个坎:创建方式、提示词结构、参数、导入导出、多智能体、发布顺序、效果评测。
本文按实际操作顺序记录每个坎的踩法和解法,含 5 张真实截图与命令输出。


一、先说结论

环节结论
创建方式界面创建,别用接口从零建(接口缺少运行所需字段,会报 Agent run error)
提示词拆成"职责 / 约束 / 示例"三段,比写一段长文稳定得多
参数max_steps 给 8–10;输出 token 上限要显式配,否则页面告警"容量字段缺失"
导入导出agent.json 只有 3 个顶层键;模型 id、MCP 地址、子智能体关系都是环境相关的,换环境必须重配
多智能体用 related_agent_ids 绑定;先发布子智能体,再发布主智能体
效果评测平台自带评测能建能跑,但裁判模型在本版本有缺陷,建议自建评测脚本兜底

二、环境与版本

项版本
Nexentv2.8.2(Docker 部署)
组件infrastructure,application,supabase
模型DeepSeek-Chat(对话)、BGE-M3(向量)
租户12345热线(超级管理员只建租户,实际开发用租户管理员账号)
操作系统Ubuntu 24.04.5 / 4 核 10 GB

提前说明:所有智能体创建、绑定、发布操作都在租户管理员账号下完成。超级管理员没有租户上下文,很多接口会返回空结果。


三、创建智能体:界面建,接口别从零建

3.1 一次失败的尝试

第一次我用接口直接建:

curl -X POST .../agent/update -d '{
  "agent_id": null, "name": "gov_12345_ticket_analysis",
  "display_name": "【政务】12345 政务热线工单分析助手",
  "model_ids": [1], "max_steps": 10, "prompt": "……"
}'

返回 {"agent_id": 6},看起来成功了。但在界面里发消息直接报错:

{"message":"Agent run error."}

看运行日志才看到真因:

Agent run error: 'NoneType' object is not iterable

查数据库对比线上能正常跑的智能体,发现接口创建的这条记录里 model_id 是空的(只有 model_ids 数组),而运行时读的是单值字段。补上之后仍然报错——说明还缺别的字段(is_new、版本快照等),这些只有界面创建流程才会写全。

结论:智能体一律在界面创建,接口只用来做批量查询、导出、发布这类"对已有对象操作"的事。

3.2 界面创建的关键几步

  1. 工作台 → 智能体创建 → 填名称、描述;
  2. 选模型(DeepSeek-Chat);
  3. 执行模式选"智能体",否则默认走通用对话,不会用你配的提示词;
  4. 保存后先自己发一句话验一遍,再往下做。

在这里插入图片描述

这张截图是一次成功的分类调用:问"小区电梯坏了半个月没人修",智能体调了 classify_ticket,返回类型、部门、置信度 0.96、命中词,耗时 0.91 秒。看到工具真的被调用,才算智能体跑通,只看它回了一段话不算。


四、提示词:拆成三段,别写一篇小作文

平台把提示词拆成几个字段,我一开始不理解,后来发现拆开是有道理的:

字段作用我写的内容
系统提示词 / prompt定义角色、能力、输出格式五项能力各自对应哪个工具、输出长什么样
约束 constraint_prompt划边界不输出最终处理结论、政策须标出处、超长摘要重写
少样本 few_shots_prompt给样例分类、话术、低置信转人工各一条

4.1 系统提示词:先讲工具,再讲格式

关键是把"什么时候调哪个工具"写死,否则模型喜欢自己编:

你负责五件事,每件事都有对应的工具,必须先调用工具,再组织语言:
1. 自动分类:调用 classify_ticket,给出类型、责任部门、置信度和依据。
2. 诉求摘要:输出不超过 100 字,保留「谁、在哪里、要解决什么」,禁止添加原文没有的信息。
3. 高频问题聚类:调用 cluster_hotspots,按簇列出问题、数量、代表工单。
4. 工单质检:调用 qc_one,逐条给出问题类型、规则编号和具体依据。
5. 回访话术:调用 make_script 生成草稿,用户修改后再用 save_script_version 入库。

4.2 约束:写"不许做什么",比写"要注意"有用

1. 不得输出最终处理结论(例如"该工单应判定为无效"),只能给分析建议。
2. 政策依据、法规条款、办理时限必须来自工具返回或知识库;没有依据就写"未检索到依据"。
3. 姓名、手机号、身份证号展示时保留首尾,中间用 * 代替。
4. 超期与否只能引用 deadline_check 返回的 workdays 与 over_by,不得自行按自然日推算。
5. 摘要超过 100 字视为不合格,需重新生成。

第 4 条是我加了之后效果最明显的一条。不加之前,模型会自己拿"9 月 1 日到 9 月 20 日"算 19 天然后判超期,而业务口径是工作日,实际只有 13 个工作日。

4.3 少样本:给"思考动作",不是给答案

少样本里我写的是带工具调用的完整链路:

任务:「小区电梯坏了半个月没人修,物业一直推脱」
动作:调用 classify_ticket(content="小区电梯坏了半个月没人修,物业一直推脱")
结果:物业管理 / 住房和城乡建设局 / 0.96
回答:诉求类型为物业管理,建议转住建局。依据:命中"物业""电梯""小区"。

只给"结果"不给"动作",模型会学成直接答;给了动作,它会照着先调工具。


五、参数:三个要注意的地方

参数建议值说明
max_steps8–10低于 5 时,多工具链路会中途停;高于 12 容易来回空转
输出 token 上限显式配置不配会在模型页看到"容量字段缺失"告警
温度0–0.3分类、质检这类任务不需要发散

那个"容量字段缺失"告警长这样(模型列表页):

1 个 LLM/VLM 模型中 1 个缺少容量字段。这些模型的输出 Token 限额未启用。

不影响对话,但生成类任务(比如摘要)可能被截断。建议在添加模型时就把输出上限填上,别等出问题再找。


六、agent.json:只有三个键,但处处是环境依赖

导出的文件结构很简单:

在这里插入图片描述

{ "agent_id": 6, "agent_info": { "6": { ...26 个字段... } }, "mcp_info": [ ... ] }

拿到别的环境直接用,会踩三个坑:

  1. model_id 是租户内自增 id。我这套环境 DeepSeek 是 1,换个环境可能是 7,导进去就是"模型不存在";
  2. mcp_url 是内网地址。写成 http://172.17.0.1:8001/sse,别人拿去必然连不上;
  3. related_agents 导出为 null。多智能体关系不在导出文件里(这是我这篇文章最想提醒的一点)。

所以我在交付目录里把 mcp_url 写成占位符 http://<MCP_HOST>:8001/sse,并在 README 里写清导入前要改什么。


七、多智能体:能配,但要按顺序发布

7.1 绑定

主智能体(id 6)下挂两个子智能体:

智能体id职责工具数
分拨分类专家9只做分类与责任部门判定3
工单质检专家10只做四类质检3

绑定时给 related_agent_ids 和 related_agents:

curl -X POST .../agent/update -d '{
  "agent_id": 6,
  "related_agent_ids": [9, 10],
  "related_agents": [{"agent_id": 9}, {"agent_id": 10}],
  "is_main_agent": true
}'

查关系链能看到层级:

在这里插入图片描述

7.2 发布顺序:先子后主

这里卡了我一次。直接发布主智能体:

{"message":"Sub-agent 9 has no published version; publish the sub-agent first."}

也就是说子智能体必须先有已发布版本,主智能体才能发布。按顺序来:

在这里插入图片描述

子智能体各自发 v1,主智能体再发,最后版本号推到 v3。

7.3 一个没解决的问题

接口 /agent/run 对这个主智能体仍然报 Agent run error,但界面里能正常对话(侧边栏能看到会话记录)。我判断是接口调用缺少会话上下文,不是配置问题——但交付前必须用界面把「委派是否真的发生」验一遍,不能只看配置。


八、效果评测:能跑,但裁判模型有问题

8.1 平台自带评测

流程是:建评测集 → 加用例 → 建评测任务 → 分析。用例格式有个坑:label 必须是对象,不是字符串。

{"inputs": {"query": "小区电梯坏了没人修"}, "label": {"expected": "物业管理"}}

传字符串会直接报 Input should be a valid dictionary,文档没写。

三条用例跑完的结果:

在这里插入图片描述

status: COMPLETED  progress: 3/3  score: 0.0  pass: 0  fail: 3

看起来是"我的智能体全错",但点开 error_message 才看到真因:

评估系统在调用"裁判模型"时出错了。原因是程序内部已经在一个"运行中的事件循环"里,却又尝试启动一个新的,两者冲突导致调用失败。

predict 字段全是 null,说明根本没跑到打分环节。这是平台 v2.8.2 评测模块的 asyncio 嵌套问题,不是配置错误。

8.2 我的兜底方案

既然平台评测不可用,就用自己写的评测脚本跑指标。做法很简单:把金标数据和预测结果对齐,逐条比:

correct = sum(pred[i]["type"] == gold[i]["type"] for i in range(n))
print(f"分类准确率: {correct/n:.1%}")

我这套数据上的结果:

指标门槛实测
分类(200 条标注)≥85%100%
分类(手写工单,换说法)—规则 75% → 加 LLM 兜底 100%
质检检出 / 误报≥85% / ≤15%100% / 0%
聚类≥80%10/10 组
2000 条批量≤10 分钟0.05 秒

注意:200 条上 100% 是虚高的——规则词表就是从这批数据里提的。手写那组才接近真实水平,所以架构上保留了规则打底 + 模型兜底。


九、常见问题速查

现象原因处理
Agent run error / NoneType not iterable接口创建的智能体缺字段界面重建,或补齐 model_id 等字段
导入 agent.json 报 Agent import error文件里的 model_id 在本环境不存在换成目标环境的模型 id
发布主智能体报 Sub-agent has no published version子智能体未发布先发布子智能体
导出再导入后子智能体没了related_agents 不写进导出文件导入后重新绑定
评测全 fail 且 predict 为 null裁判模型 asyncio 冲突自建评测脚本,或等平台修复
智能体答得很"飘"提示词没写工具调用规则把"必须先调哪个工具"写进系统提示词

十、小结

做智能体和写代码有点像:提示词决定下限,配置决定上限。

  • 提示词写清楚"什么时候调什么工具",模型就不会瞎编;
  • 配置(模型、MCP、子智能体、发布顺序)错一个,功能就跑不起来,而且报错信息往往指向别处。

最消耗时间的不是写提示词,是排查这四件事:接口创建缺字段、模型 id 环境相关、子智能体发布顺序、评测裁判报错。这四件事我都写在上面了,希望读到的人能省下这几个小时。


十一、参考链接

内容地址
Nexent 官方文档https://modelengine-group.github.io/nexent
Nexent 源码https://atomgit.com/ModelEngine/nexent
DeepSeek 开放平台https://platform.deepseek.com
MCP 协议规范https://modelcontextprotocol.io

本文为「Nexent 智能体实战」专栏第 3 篇。上一篇:MCP 与 Skills 实战。

Logo

更多推荐