Agent Workflows
本指南介绍如何将 AuraBoot 元数据转化为可用的 Agent Workflow。目标不是让模型自由发挥,而是为其提供描述清晰的工具、严格的 schema 以及受护栏约束的业务操作路径。
前置条件
启用 Agent Workflow 之前,请确保平台基础元数据健康:
| 要求 | 重要性 |
|---|---|
| Model 具备可读的名称和 Field 描述 | 模型需要业务上下文 |
| Command 已发布并配置 Permission | Agent 通过 Command 执行操作 |
| Command 的输入 schema 足够严格 | Tool 调用需要可靠的参数 |
| 已分配风险等级 | 确认策略取决于风险 |
| 已启用审计日志 | Agent 行为必须可追踪 |
如果元数据薄弱,Agent 仍可运行,但会询问更多澄清问题,并且工具选择的可靠性下降。
配置 LLM 提供方
AuraBoot 从平台云配置服务读取 LLM 配置。一条 Provider 记录应当定义:
- Provider code,例如
openai、anthropic、deepseek,或自定义的 OpenAI 兼容 Provider - API 格式,通常为
chat_completions或messages - 使用兼容网关时的 Base URL
- 默认 Model
- API key
- Token 限制与超时策略
先使用一个 Provider。仅当存在明确的路由需求(例如用快速模型做摘要、用更强模型做规划)时,才接入多个 Provider。
定义 Agent
Agent 定义应当小而具体。
| 字段 | 指南 |
|---|---|
| Code | 稳定标识符,例如 sales-assistant |
| Name | 面向用户的名称 |
| System instruction | 角色、范围与边界 |
| Default model | 未覆盖时使用的 Model |
| Allowed tools | 收敛后的 Tool code 或能力组列表 |
| Guardrails | 确认、预算、最大步数、Provider 策略 |
避免泛化指令,例如"管理整个业务"。优先使用范围明确的 Agent,例如"协助销售用户检查 Lead、起草跟进内容、创建任务记录"。
暴露 Tool
最好的 Tool 通常是已有的 Command 和命名查询。
| Tool 来源 | 最适合 | 备注 |
|---|---|---|
| DSL command | 创建、更新、删除、状态流转 | 复用 Permission、校验、审计 |
| Named query | 分析与读多类型问题 | 保持参数显式 |
| Native tool | 集成专属操作 | 添加严格契约 |
| Workflow action | 长流程业务 | 风险步骤优先使用审批 |
每个 Tool 都需要清晰的用途、输入 schema、输出 schema 与风险策略。除非内部维护类 API 已经可以安全地委托执行,否则不要将其暴露为 Agent Tool。
添加 Agent Hint
Agent Hint 是附加在能力上的简短使用描述,帮助模型选择正确的 Tool。
良好的 Hint:
Use this command when a sales user wants to qualify a lead after confirming budget, decision maker, and expected close date. Do not use it for leads still missing required discovery fields.较弱的 Hint:
Update lead.更强的 Hint 告诉模型何时使用该 Command、何时不使用,以及哪些业务前置条件需要关注。
设置确认策略
将 Tool 风险映射为用户确认。
| 操作 | 建议策略 |
|---|---|
| 只读查询 | 不需要确认 |
| 草稿创建 | 不需要确认或仅一次确认 |
| 状态流转 | 一次确认 |
| 删除或不可逆操作 | 始终确认 |
| 财务、法律或外部副作用 | 需要审批 |
确认不仅是 UI 细节,它是 Agent 契约的一部分,应当与 Command Permission 同等严格地审查。
运行测试会话
从一个简单场景开始:
- 在已知 Model 上下文的页面打开 Aura Bot
- 针对当前列表询问一个只读问题
- 让 Agent 创建一条草稿记录
- 出现提示时确认操作
- 打开新建的记录并验证字段值
- 检查 Trace 与审计条目
Trace 应当展示模型调用、所选 Tool、参数、Command 结果与最终回复。如果选错了 Tool,应改进 Tool 契约,而不是改提示词。
排错
| 现象 | 可能原因 | 修复 |
|---|---|---|
| Agent 提示未配置 Provider | 缺失或被禁用的 LLM Provider | 添加云配置 Provider 记录 |
| Agent 无法运行 Command | 用户缺少 Permission 或 Command 未发布 | 修复 Permission 或发布 Command |
| Agent 问题过多 | Tool schema 或 Field 描述含糊 | 完善 Model 与 Command 元数据 |
| Agent 选错 Tool | Tool 用途与其他 Tool 重叠 | 补充 whenToUse 与 whenNotToUse 说明 |
| Tool 调用校验失败 | 输入 schema 与 Command 要求不一致 | 对齐 Command schema 与示例 |
生产环境清单
- Provider key 存储在平台配置中,而非前端代码
- 高风险 Command 需要确认或审批
- Agent Tool 的契约保持最新
- 能力变更后重新生成 Tool 契约
- Trace 留存与审计留存满足合规要求
- 已端到端测试一组小而真实的工作流
后续步骤
- Agent System — 架构与运行时模型
- AI Copilot — 面向用户的助手行为
- Commands — 定义 Agent 可调用的操作