智能体开发:提示词决定下限,配置决定上限
在 Nexent 上从零做一个能用的智能体,中间有 7 个坎:创建方式、提示词结构、参数、导入导出、多智能体、发布顺序、效果评测。
本文按实际操作顺序记录每个坎的踩法和解法,含 5 张真实截图与命令输出。
一、先说结论
| 环节 | 结论 |
|---|---|
| 创建方式 | 界面创建,别用接口从零建(接口缺少运行所需字段,会报 Agent run error) |
| 提示词 | 拆成"职责 / 约束 / 示例"三段,比写一段长文稳定得多 |
| 参数 | max_steps 给 8–10;输出 token 上限要显式配,否则页面告警"容量字段缺失" |
| 导入导出 | agent.json 只有 3 个顶层键;模型 id、MCP 地址、子智能体关系都是环境相关的,换环境必须重配 |
| 多智能体 | 用 related_agent_ids 绑定;先发布子智能体,再发布主智能体 |
| 效果评测 | 平台自带评测能建能跑,但裁判模型在本版本有缺陷,建议自建评测脚本兜底 |
二、环境与版本
| 项 | 版本 |
|---|---|
| Nexent | v2.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 界面创建的关键几步
- 工作台 → 智能体创建 → 填名称、描述;
- 选模型(DeepSeek-Chat);
- 执行模式选"智能体",否则默认走通用对话,不会用你配的提示词;
- 保存后先自己发一句话验一遍,再往下做。

这张截图是一次成功的分类调用:问"小区电梯坏了半个月没人修",智能体调了 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_steps | 8–10 | 低于 5 时,多工具链路会中途停;高于 12 容易来回空转 |
| 输出 token 上限 | 显式配置 | 不配会在模型页看到"容量字段缺失"告警 |
| 温度 | 0–0.3 | 分类、质检这类任务不需要发散 |
那个"容量字段缺失"告警长这样(模型列表页):
1 个 LLM/VLM 模型中 1 个缺少容量字段。这些模型的输出 Token 限额未启用。
不影响对话,但生成类任务(比如摘要)可能被截断。建议在添加模型时就把输出上限填上,别等出问题再找。
六、agent.json:只有三个键,但处处是环境依赖
导出的文件结构很简单:

{ "agent_id": 6, "agent_info": { "6": { ...26 个字段... } }, "mcp_info": [ ... ] }
拿到别的环境直接用,会踩三个坑:
model_id是租户内自增 id。我这套环境 DeepSeek 是 1,换个环境可能是 7,导进去就是"模型不存在";mcp_url是内网地址。写成http://172.17.0.1:8001/sse,别人拿去必然连不上;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 实战。
更多推荐

所有评论(0)