OpenAPI 操作
OpenAPI 操作
OpenAPI 操作将已批准的 API 规范转化为智能体可使用的工具。管理员可以管理全部操作；内容管理员可以创建操作，但只能维护自己创建的操作。最终用户只授权向其展示的提示，运行时只为已配置操作发送请求。
适合接入的 API
优先接入边界清晰、响应稳定、认证方式明确且可被最小权限约束的 API。不要把含有大量高危写操作的完整业务系统 API 直接交给通用 Agent。
OpenAPI 操作的工作方式
OpenAPI 规范描述可变成工具的 API 操作、输入和响应。艾维斯使用该规范创建 Action，之后由 Admin 或拥有该 Action 的 Curator 维护预期操作。任何有权编辑 Agent 的用户，都可以附加当前可供选择的 Action。
准备规范
Admin 或拥有该 Action 的 Curator 应使用 API 所有者提供且经过检查的最新 OpenAPI 规范。确保它只描述 Agent 应使用的操作，输入和响应清晰，并标明认证要求而不嵌入密钥值。
Admin 可以在整个部署范围内导入并验证规范。Curator 可以创建 Action 并为其导入规范，但只能更新自己创建的 Action；Global Curator 身份不会扩大 Action 所有权。导入前，请验证 API 端点和支持的操作符合部署的数据与访问边界。
添加并验证 Action
- 以管理员或内容管理员身份登录并打开“OpenAPI 操作”。
- 添加已检查的规范，选择目标 Agent 工作流所需的操作。
- 完成受保护的 Action 配置，保存后将 Action 附加到 Agent。
- 运行一个已批准的测试请求，并在发布 Agent 前检查返回结果。
Admin 可以在整个部署范围内上传或变更任意规范、选择操作并完成受保护配置。Curator 只能对自己创建的 Action 执行这些维护操作。该所有权规则对 Curator 和 Global Curator 完全相同；Action 不属于其负责群组或所属群组。
Curator 可以把当前可供选择的 Action 附加到自己有权编辑的任意 Agent。
Action 所有者应在 API 合同变更时更新已导入定义。该维护边界涵盖修改、删除和受保护凭据。
部署级模型、集成、安全、Index Settings、Usage 和组织配置仍由 Admin 负责。最终用户无法通过 Agent 对话添加操作或更改 Action 配置。
配置认证
只能通过 Admin 或 Action 所有者可访问的受保护 Action 设置填写 API 认证信息。绝不要在 OpenAPI 文档、Agent 指令、最终用户消息、源代码管理或共享文档中包含密钥。
API 所有者和 Action 所有者负责连接访问范围与凭据生命周期；Admin 也可以维护这些配置。最终用户授权提示（如有）只授权该用户的交互；它不会公开或转移 Action 已存储的认证资料。
排查问题
如果无法添加 Action，请与 API 所有者确认规范格式、API 端点和所选操作。如果操作已添加但在运行时失败，请检查报告的响应以及已配置的输入、API 端权限和受保护连接设置。
如果最终用户无法使用原本正常的 Action，请验证 Agent 的共享范围以及是否有必需的授权提示。每次配置变更后均重新运行有代表性且已获批准的请求。