建置 Agent 操作指南¶
读者对象：Agent 开发者
预计阅读时间：3 小时
版本：v0.1 | 2026-08-13
1. Agent 是什么？¶
Agent 是一个由多个节点组成的工作流，每个节点调用大语言模型（LLM）完成特定步骤。多个 Agent 可由 Butler 编排，协作完成复杂工程任务。
典型结构：
2. Agent 列表管理¶
2.1 进入 Agent 管理¶
点击左侧导航 「Agent」。
2.2 个人 / 公开¶
| 标签 | 说明 |
|---|---|
| 个人 | 您创建的 Agent，仅自己可见 |
| 公开 | 全员可用的 Agent |
支持按名称搜索，列表滚动加载更多。
2.3 创建 Agent¶
- 点击 「+ 创建」
- 填写 名称（必填，最多 20 字）
- 填写 智能体介绍（必填，最多 500 字，展示给其他用户）
- 点击 「创建」 → 进入可视化编辑器
2.4 导入 Agent¶
- 点击 「+ 导入」
- 选择 Agent 配置文件（JSON）
- 选择 默认模型（导入后可单独修改各节点模型）
- 确认导入
2.5 其他操作¶
在 Agent 卡片上可：
- 编辑：进入编辑器
- 导出：下载 Agent 配置
- 删除：不可恢复，需确认
3. 可视化编辑器¶
3.1 界面布局¶
| 区域 | 功能 |
|---|---|
| 左侧画布 | 节点拓扑图，拖拽、连线 |
| 右侧配置面板 | 当前选中节点的详细配置 |
| 底部按钮 | 删除节点、新增节点、复制节点、调试 |
右侧面板宽度可拖拽调整。
3.2 画布操作¶
- 选中节点：点击节点，右侧显示配置
- 新增节点：点击 「新增节点」，选择节点类型
- 删除节点：选中后点击 「删除节点」
- 复制节点：选中后点击 「复制节点」
- 连线：节点间自动按工作流顺序连接（条件分支在高级配置中设置）
3.3 保存¶
编辑后系统自动保存；也可通过返回列表确认变更已生效。
4. 节点类型¶
4.1 Head（开始节点）¶
工作流入口，配置 Agent 基本信息：
| 字段 | 说明 |
|---|---|
| Agent 名称 | 与列表中名称同步 |
| Agent 描述 | 功能说明 |
| 引用项目历史对话 | 是否带入同一项目下先前任务的对话 |
4.2 Normal（普通节点）¶
核心执行节点，配置 LLM 调用逻辑。
基本信息¶
| 字段 | 说明 |
|---|---|
| 节点名称 | 可编辑，用于步骤展示与变量引用 |
| 节点描述 | 内部说明，可选 |
输入（上下文范围）¶
| 选项 | 说明 |
|---|---|
| 全部上下文 | 引用任务中所有历史对话 |
| 不引用上下文 | 仅使用本节点 Prompt |
| 上一个节点上下文 | 仅引用前一节点的输出 |
| 当前节点所有对话 | 本节点多轮对话的上下文 |
模型设置¶
从下拉列表选择 LLM 模型。不同节点可使用不同模型。
工具¶
为节点绑定外部能力：
| 类型 | 说明 |
|---|---|
| 插件 | 平台内注册的 Python 等工具函数 |
| 知识库 | 绑定 GraphRAG 知识库进行 RAG 检索 |
点击 「+」 添加工具，选择类型和具体工具名称。可点击 「新增」 跳转创建新插件。
引导词（guiding_word）¶
节点开始执行时展示给用户的说明文字，例如：
系统提示词（Prompt）★¶
最核心的配置，定义 LLM 在本节点的行为。支持：
- 多行文本，建议结构清晰（角色、任务、输出格式）
- 「{x}引用内容」：插入其他节点的输出变量
- 上传附件作为参考
- 嵌入 咒语 触发平台能力
Prompt 编写建议：
你是一位电力电子设计专家。
## 任务
根据用户提供的输入条件，计算 Buck 电路 CCM 模式参数。
## 输入
{引用上一节点输出}
## 输出要求
1. 占空比 D
2. 电感电流纹波 ΔIL
3. 以 Markdown 表格呈现
执行控制¶
| 开关 | 说明 |
|---|---|
| 自动执行 | 到达本节点时自动运行，无需用户触发 |
| 自动下一步 | 本节点完成后自动进入下一节点 |
| 内容自定义 | 启用后可自定义输出模板 |
4.3 End（结束节点）¶
工作流终点，定义最终输出：
| 字段 | 说明 |
|---|---|
| 自定义输出 | 汇总各节点结果的模板，支持 {x}引用内容 |
| 自动下一步 | 通常开启 |
| 文档下载格式 | 不需要 / Pdf 等 |
5. 变量引用¶
在 Prompt 或输出模板中，点击 「{x}引用内容」 可插入：
- 其他节点的 输出
- 其他节点的 输出.code（代码块）
- 当前节点名称相关变量
引用格式示例：{节点名.输出}
还可使用咒语引用任务变量，见 咒语文档 中的 <get:task.*> 等。
6. 在线调试¶
6.1 启动调试¶
- 在编辑器中点击 「调试」
- 右侧出现调试对话面板
- 输入测试消息，观察各节点执行
6.2 调试技巧¶
- 先测单节点：关闭自动执行，逐步确认
- 检查 Prompt 是否清晰、引用变量是否正确
- 查看原始输出是否含预期咒语
- 工具绑定失败时，确认插件/MCP 权限与可用性
6.3 常见问题¶
| 现象 | 排查 |
|---|---|
| 节点无输出 | 检查 Prompt、模型是否选中 |
| 工具未调用 | 确认工具类型与名称正确绑定 |
| 上下文丢失 | 检查「输入」上下文范围设置 |
| 咒语未生效 | 见咒语文档注意事项 |
7. 发布与共享¶
7.1 隐私级别¶
创建时默认为 Personal。若要团队共用：
- 在 Agent 配置或列表中设置为 Public
- 公开后所有用户可在 Butler 规划中被匹配使用
7.2 发布检查清单¶
- [ ] 名称与描述准确反映功能
- [ ] 各节点 Prompt 已测试
- [ ] 工具依赖已公开或说明权限要求
- [ ] 结束节点输出格式符合预期
- [ ] 无硬编码个人路径或敏感信息
8. 完整案例：Buck 参数计算 Agent¶
8.1 工作流设计¶
8.2 节点配置要点¶
节点 1 - 收集输入
- 引导词：请提供 Vin、Vout、Iout、Fsw
- Prompt：解析用户输入，提取参数，缺失则列出需补充项
- 自动执行：关（等待用户补充）
节点 2 - 参数计算
- 输入：上一个节点上下文
- Prompt：按 CCM 公式计算 D、L、ΔIL
- 工具：可选绑定「Python 计算」插件
节点 3 - 格式化输出
- 输入：上一个节点上下文
- Prompt：将计算结果整理为 Markdown 表格
结束节点
- 自定义输出：引用「格式化输出.输出」
- 下载格式：Pdf（可选）
8.3 测试与发布¶
调试通过后，设为 Public 供团队使用。