Agent Builder

AI 同事 — 已配置 Agent 列表

Agent Builder 是 AuraBoot Agent 的配置入口。一个 Agent 就是一条 metadata 记录。它将一个 name 与 role 绑定到一段系统 Prompt、一份 Memory 策略、一份 Tool 列表、一个模型 Provider 与一组 Guardrail。Agent 运行时在回合时加载该记录，并用它决定 LLM 可见什么以及可做什么。

概念

一个 Agent 由六个可配置部分构成：

部分	用途
Identity	`code`、`displayName`、所有者、版本
Prompt	系统 Prompt 和角色指令
Memory	短期窗口、长期摘要策略
Tool	Agent 可调用的 Command 与命名查询白名单
Guardrail	风险阈值、审批路由、禁止话题
模型绑定	Provider、模型名、temperature、token 上限

Agent 是有版本的。修改 Prompt 或 Tool 列表会创建新版本；旧版本仍可审计。

何时使用

从通用助手中切分出专项 Agent（"合同审查员"、"运维分诊"）。
将部门专用助手限制到一份窄 Tool 列表。
在不影响默认 Agent 的前提下试验新 Prompt 或新模型。
包装需要固定 Tool 集合与受守护审批策略的外部工作流。

架构

+----------------+        +---------------------+
| Agent record   | -----> |  Agent Runtime      |
| (DB / DSL)     |        |  loads on each turn |
+----------------+        +----------+----------+
                                     |
                  +------------------+------------------+
                  |                  |                  |
            +-----v-----+      +-----v-----+      +-----v-----+
            |  Prompt   |      |  Tools    |      | Guardrails|
            |  resolver |      |  resolver |      |  resolver |
            +-----------+      +-----+-----+      +-----+-----+
                                     |                  |
                                     v                  v
                            +--------+---------+   +----+-----+
                            | Command pipeline |   | Approval |
                            | (permission +    |   |  gate    |
                            |  validation +    |   +----------+
                            |  audit)          |
                            +------------------+

Tool 解析器并不会暴露每个 Command。它将 Agent 的白名单与调用用户的 Permission 求交。结果即本回合 LLM 实际看到的 Tool 集合。

编写一个 Tool

一个 Tool 是 Command 加上 agent_hint（一段字符串，模型选择调用哪个 Tool 时读它）和 cmd_risk_level（L0–L4，等级越高越会路由到 Approval Gate）。Hint 应说明这条命令做什么、何时用、何时不该用。

{
  "code": "task:transition",
  "cmd_risk_level": "L2",
  "agent_hint": "Move a task from one workflow state to another. Use when the user asks to start, finish, approve, or close a specific task; do not use to read or summarize tasks (use task:query instead).",
  "inputFields": ["task_id", "to_state"],
  "permissions": ["task.task.manage"]
}

含糊的 hint 导致的错误 Tool 选择比弱模型造成的还要多。

配置一个 Agent

code: operations-helper
displayName: $i18n:agent.operations.name
version: 4
model:
  provider: deepseek
  name: deepseek-chat
  temperature: 0.2
  maxTokens: 4096
prompt:
  system: |
    You are the AuraBoot operations helper. Use only the tools you are
    given. Never fabricate IDs or field values. If you do not know a
    record's ID, query first.
memory:
  window: 12
  summarizeAfter: 24
tools:
  allow:
    - task:query
    - task:create
    - task:transition
    - customer:query
  deny:
    - "*:delete"
guardrails:
  destructiveRequiresApproval: true
  forbiddenTopics: ["payroll", "compensation"]

带 Permission 的 Tool 暴露

Tool 不会只凭名称就暴露出去。在解析时：

Agent 的 tools.allow 列表过滤全局注册表。
tools.deny 移除匹配模式（例如所有删除命令）。
当前用户的 Permission 进一步过滤列表。
风险等级与审批策略装饰每个剩余 Tool。

求交后的集合即模型所见。用户无法运行的 Tool 永远不会被提供。

验证清单

每个 Tool 都有精确的 agent_hint，说明它做什么、何时用、何时不该用。
Permission code 遵循 <module>.<resource>.<action>。
破坏性 Tool 经过 Approval Gate。
Agent Prompt 中不嵌入密钥、API Key 或 PII。
新版本取代旧版本；旧版本保留在审计中。