第8章 Agent 工具与权限
第8章 Agent 工具与权限
工具决定了你的 Agent 能读取或修改哪些数据,以及它能触发哪些操作。 有效的工具设计是确保 Agent 行为安全且可预测的主要手段。
原则:最小权限 仅启用 Agent 完成工作所必需的工具。 支持分诊 Agent 示例:
- 必需:列出工单、获取工单、更新工单 - 非必需:删除工单、管理用户、发布应用
为操作配置工具 工具在操作(Operation)级别进行配置。虽然 Budibase 会自动从数据源和自动化中发现可用工具,但你必须为每个操作显式启用并配置它们。
添加工具 你可以通过两种方式将工具添加到操作中:
- Rail Actions:点击操作面板中“工具”部分的“添加工具”按钮。选择工具后,会弹出配置窗口,允许你在添加前设置其执行身份和审批规则。 - 编辑器自动补全:在编写指令时输入 `{{`,然后从自动补全菜单中选择“添加工具”。这将打开配置窗口,并在一步中插入工具绑定。
执行身份 启用工具后,你可以在工具配置窗口中设置其“以…运行”(Run as,执行身份)。这决定了用于访问数据并执行操作的角色。
- 请求者(Requester):工具使用与 Agent 交互的用户的权限运行。对于大多数面向用户的工具,这是最安全的默认选项。 - 管理员(Admin,提升权限):工具以完整的管理员权限运行。仅对后台任务或严格受控的操作谨慎使用此选项。
🚀 自动化 通过自动化步骤触发的 Agent 默认以管理员身份执行。如果工具需要权限提升,Agent 将暂停,并在获批后使用原始自动化请求者的角色恢复执行。
审批规则与策略 审批规则确保高影响操作在执行前由人工审查。你可以配置规则,使其始终生效,或仅在满足特定条件时生效。
审批策略 审批策略定义了谁负责接收通知并审查受限操作。策略是可复用的,在操作的“审批”选项卡中管理。
- 策略名称:策略的可识别名称,显示在审批规则中。 - 审批类型:确定解决请求所需的响应数量。 - 任意审批人:任何一位审批人批准即可继续。 - 全体一致:每位审批人都必须批准才能继续。任何一次否决都会导致请求被拒。 - 多数批准:超过半数的审批人批准即可继续。 - 审批人:负责审查并响应升级请求的 Budibase 用户列表。 - 通知:审批请求出现的信息渠道和目的地(用户或频道)。如果已定义至少一名审批人,此项为可选。 - 审批过期时间:审批人在审批过期前响应的时长。默认为 1 天。可用预设包括 1 天、3 天、1 周、30 天 和 90 天,具体取决于你的 Budibase 计划限制。企业版计划还可以使用自定义时长或选择“永不过期”。 - 过期后的结果:选择如果在人工响应前审批过期,系统将自动产生的结果。 - 过期:请求在未运行工具的情况下过期,Agent 会告知用户请求已超时。 - 批准请求:请求自动获批并运行工具。 - 拒绝请求:请求自动被拒且工具不运行。
审批规则 审批规则确定何时应将对策略应用于特定工具。规则在工具配置窗口中设置。
- 无条件规则:每次调用工具时都要求审批。 - 条件规则:仅当工具的输入数据符合特定条件时才要求审批(例如,仅当 `Total` 字段大于 1000 时,才对 `create_row` 工具进行升级审批)。
与审查者共享参数 为了帮助审查者在不离开消息应用的情况下做出知情决策,你可以选择在通知卡片中包含哪些工具参数。
- 默认行为:默认不共享任何参数。 - 选择:使用规则配置中的“与审查者共享”多选框来选取相关字段。 - 限制:每条规则最多可共享 40 个参数。 - 上下文:通知还包含请求者的身份(用户姓名和邮箱,或自动化的 Agent 名称)以及所使用的特定工具。
⚠️ 隐私与安全 参数以明文形式在 Slack 或 MS Teams 中共享。除非消息渠道是安全的,否则避免共享包含密码或 API 密钥等敏感信息的参数。 配置了规则的工具会在操作面板中显示状态指示器(例如,“1 条规则”)。
表格列变更
- 重命名列:如果你重命名了表格列,Budibase 会自动更新引用该列的任何审批规则条件和共享审查参数。 - 删除列:如果审批规则条件中使用的列被删除,工具将拒绝调用,直到规则被更新。在规则配置窗口中,缺失的条件字段会被标记为(不可用),在保存规则前必须将其移除。
处理已批准操作的失败 如果审查者批准了操作,但工具执行失败(例如由于验证错误或数据库问题),Agent 会通知用户。响应将包含类似以下消息:“你的请求已获批,但我无法完成它。请重试。” 如果请求写入的数据在请求后发生了变化(例如在审批待定期间列被重命名或删除),工具不会执行,Agent 会告知用户:“你的请求已获批,但它写入的数据在请求后发生了变化,因此未执行。请重新询问。” 详细的失败信息会记录在活动时间线中,以便协助故障排除。
Agent 数据范围 为确保数据安全并优化 Token 使用,Budibase 会自动限制暴露给 AI Agent 的数据。
字段排除 当 Agent 与表格交互时,它只能看到纯文本和原始数据字段。以下字段类型会自动从 Agent 视图中排除:
- 链接字段:与其他表格的关系(连接的数据)不予暴露,以防止意外数据泄露。 - 公式字段:计算值和基于关系导出的值对 Agent 隐藏。
这些排除项同时适用于表格架构(元数据)和工具返回的实际行数据。
受限资源访问 为防止数据泄露,当 Agent 作为请求者运行且对资源(如表格)权限不足时,Budibase 会自动隐去工具元数据和结果数据。
- 隐去的元数据:Agent 无法看到资源的架构、字段名称或具体配置。相反,它收到一个通用的工具描述,以防止其推断出数据结构。 - 隐去的结果:对于受限资源的写操作(如创建或更新行),工具返回通用的成功消息,而非完整的对象数据,以防止未授权读取记录。 - 发现工具:诸如 `list_tables` 和 `get_table` 的旧版发现工具默认禁用。应通过操作配置为 Agent 提供其任务所需的特定工具。
权威验证 在运行创建或更新行、触发动作或执行 REST 查询的工具之前,Budibase 会执行服务器端验证。输入必须匹配表格、自动化触发器或 REST 查询的当前架构。验证发生在创建审批请求或运行工具之前。如果请求稍后获批,Budibase 在执行前会再次验证输入是否匹配当前架构。 如果工具因请求者无权查看其资源而被隐去,Budibase 会用通用的“工具输入无效”消息替换验证细节。这可以防止错误响应泄露资源架构。
读与写工具 在工具和指令中分离读取和写入功能。
读工具:
- 安全的默认选项 - 适用于问答、查找和摘要
写工具:
- 风险较高 - 需要明确的用户意图 - 应包含额外的规则和测试
权限模式 使用以下模式之一:
只读 Agent
Agent 可以检索和分析数据,但不能修改任何内容。这是默认的起点,也是最安全的选项,适合验证、报告、审计和洞察生成。
读 + 受控更新
Agent 可以读取数据并执行有限的、显式限定范围的写操作。写入应受约束(例如,特定字段、特定对象,或位于审批工作流之后),并在启用到生产环境前通过测试进行验证。
读 + 更新 + 自动化触发
Agent 可以读取数据、执行已批准的更新,并触发下游工作流或自动化。此模式适用于更成熟的、生产级用例,其中 Agent 被信任执行可能产生连锁影响的操作。
从只读开始,仅在通过测试验证后添加写权限。
升级与审批 审批确保高影响操作由人工审查。这在 Agent 操作的工具级别进行配置。
配置收件人 要选择当操作需要审批时谁接收通知,你必须先在 Agent 的“部署”选项卡中启用至少一个消息渠道。
要求:在配置好具有有效端点 URL 的部署(例如,Slack、MS Teams)之前,无法选择审批收件人。但是,如果你已指定至少一名审批人,仍然可以保存没有通知的审批策略。
写操作的保护栏 启用更新工具时,包含如下规则:
- 仅更新允许的字段。 - 除非明确要求,否则绝不覆盖非空的关键字段。 - 写入前确认目标行。 - 拒绝破坏性请求。
工具命名与清晰度 优先使用直接映射到真实实体的清晰工具名称(如 `Tickets.Get Row`、`Tickets.Update Row`)。 模糊的名称会增加错误工具调用和提示复杂性。
重命名与稳定性 Budibase 会自动维护 Agent 与其工具之间的连接。如果你重命名数据源、REST API 或查询,Budibase 会自动更新:
- Agent 提示指令中对该工具的任何引用。 - 所有受影响 Agent 的已启用工具列表。
重命名表格列也会自动更新引用该列的任何审批规则条件和共享审查参数。 这确保了重新组织数据或 API 不会破坏现有的 Agent 配置。
命名约束 为确保与 AI 提供商(如 OpenAI)的兼容性,工具名称受 64 字符限制。 Budibase 使用稳定的唯一标识符进行工具绑定,以确保即使标签较长或名称更改,它们仍保持一致。如果从实体名称(如表格或查询)派生的工具名称异常长,Budibase 可能会使用带唯一后缀的缩写版本,以防止冲突并保持在提供商限制之内。 保持表格和查询名称简洁,以确保工具名称对 Agent 和活动日志仍具有可读性。
启用工具前的清单
- 此工具对 Agent 的任务是否至关重要? - 如果被误用,最坏的结果是什么? - 指令是否定义了它何时可以使用? - 该工具是否覆盖了测试?
相关指南
- Agent 指令指南 - Agent 测试指南 - Agent 故障排除指南
更新于 13 小时前 本页是否有帮助?