能力与连接器管理

连接器

连接器描述 AgentOS 如何连接一套业务系统，包括服务地址、鉴权方式、身份映射、健康检查和能力同步。

推荐每个环境单独配置连接器，不在开发、演示和生产之间共用密钥。

能力

能力是智能体可以调用的最小业务动作，例如：

• 查询本人可用账套。
• 查询费用类型。
• 查询本人待办。
• 检查发票重复。
• 创建费用报销草稿。

能力元数据

配置	说明
名称和说明	面向管理员和模型都能理解的业务语义
请求结构	字段类型、必填项、枚举和示例
响应结构	标准结果、业务错误和详情链接
权限码	使用能力前的 AgentOS 权限校验
风险等级	只读、写入或高风险
确认策略	是否必须展示 HITL 确认卡
超时与重试	仅对安全、幂等的错误重试

维护接口变化

业务接口字段调整时，应按以下顺序处理：

1. 业务系统以新版本接口保持兼容或明确版本号。
2. 更新连接器中的请求、响应和字段映射。
3. 更新能力说明、示例和错误码。
4. 检查依赖该能力的技能与确认卡。
5. 完成自动验证后再发布。

不要只修改模型提示词来掩盖接口变化，也不要在通用执行器中硬编码某个业务域逻辑。

发布前检查

• 接口健康检查通过。
• 请求响应不包含未授权敏感字段。
• 写能力支持幂等和事务回滚。
• 普通员工越权测试失败。
• 错误提示可被业务人员理解。