鼎上平台如何配置智能体API文档自动生成与对外分享

在鼎上平台完成智能体开发并发布后，开发者可以通过平台内置的API管理模块，一键生成标准化的接口文档，并利用安全分享链接或导出功能，将文档高效分享给前端团队或外部调用方。这一流程有效降低了跨团队沟通成本，确保了接口调用的准确性与规范性。

适用情境

• 前后端分离开发：后端完成智能体编排后，需向前端团队交付清晰的接口规范与调用示例。
• 能力对外开放：企业将智能体能力开放给第三方合作伙伴或外部开发者时，需提供标准的接入指南。
• 多团队协作：在复杂业务系统中，多个开发小组需要统一智能体的调用标准与数据结构。

智能体API文档自动生成的配置步骤

1. 进入API管理模块

登录系统后，在控制台左侧导航栏找到“应用管理”或“API网关”模块。选择已发布上线的目标智能体，点击进入其详情页面，切换至“API接口”标签页。

2. 配置接口参数与返回结构

在接口配置界面，系统会自动解析智能体的输入输出节点。开发者需手动补充或校验请求参数的数据类型、是否必填及默认值。同时，定义标准返回结构，包括成功状态码、错误码及对应的数据载荷格式，确保调用方能准确解析响应内容。

3. 生成并预览文档

参数配置完成后，点击“生成文档”按钮。系统会基于配置信息自动生成符合主流规范的接口文档。开发者可在预览区检查文档的排版、示例代码及参数说明是否准确无误，确认无误后即可进入分享环节。

智能体API文档的对外分享与权限控制

1. 生成安全分享链接

在文档预览页面，点击“分享”按钮。系统会生成一个专属的在线文档访问链接。该链接支持调用方直接通过浏览器查阅，无需登录系统即可获取接口详情，极大提升了外部接入效率。

2. 设置访问权限与有效期

为保障接口信息的安全性，在生成分享链接时，需配置访问控制策略。可设置链接的有效期限，或开启访问密码验证。对于高安全要求的场景，建议限制特定IP白名单访问，防止接口文档被未授权人员获取。

接口文档管理与维护注意事项

• 版本同步更新：当智能体的输入输出节点发生变更时，务必及时在API管理模块更新参数配置并重新生成文档，避免调用方使用过期接口导致业务异常。
• 密钥安全脱敏：对外分享的文档中若包含调用示例，切勿在文档中明文暴露真实的API密钥，应使用占位符代替，并指引调用方通过安全渠道获取密钥。
• 完善错误码字典：详细的错误码说明是API文档的重要组成部分，需在文档中列出各类异常状态码及其排查建议，帮助调用方快速定位并解决问题。