开发者文档中心

OpenAPI进入控制台

服务端密钥 · 先用 GET /v1/capabilities 核对授权 · POST 必带 Idempotency-Key

读取智能体

GET /v1/operations/agents.read

读取当前企业的草稿/发布状态及共享 revision;创建智能体前先取最新 revision。

使用服务端 Bearer 密钥,须授权此操作。

请求示例cURL
# cURL 7.76+;请先在服务端设置环境变量。
: "${YUNFU_BASE_URL:?请设置服务端 HTTPS 地址}"
: "${YUNFU_API_KEY:?请设置已获授权的 API 密钥}"
curl --fail-with-body --show-error "$YUNFU_BASE_URL/v1/operations/agents.read" \
  -H "Authorization: Bearer $YUNFU_API_KEY"

参数与响应

权限范围
智能体配置与对话

查询参数

字段定义待补充,请结合示例核对。

响应字段

字段类型返回约定说明
revisionnumber固定返回企业目录当前版本;POST createAgent 必须携带。
agents[]{id,name,description,modelId,archived,publishedVersion,dirty,updated,channels}固定返回智能体目录,包括草稿及已归档项目;不是仅返回已发布智能体。
workflows[]{id,name,versions:[{version,name}]}固定返回含 conversation 版本的工作流目录。
channels / publicKnowledgeLibrariesarray固定返回具备 channels 权限时返回,否则为空数组。
响应示例JSON
{
  "revision": 7,
  "agents": [
    {
      "id": "default",
      "name": "售后助手",
      "description": "",
      "modelId": "text-model",
      "archived": false,
      "publishedVersion": 0,
      "dirty": true,
      "updated": 1789603200000,
      "channels": []
    }
  ],
  "workflows": [],
  "channels": [],
  "publicKnowledgeLibraries": []
}
调用说明

只读查询可有界重试;429 按 Retry-After 等待。

  • 请求示例未实际执行。请先替换示例资源 ID、修订号和占位值,并核对当前业务条件。
  • 权限由当前登录账号、企业及支持访问范围决定,不能通过传 tenant、actor 或 owner 扩大访问范围。
  • 只读查询可有界重试;429 按 Retry-After 等待。
错误与重试

以下为常见状态,具体接口可能只返回其中部分。

状态含义处理
400参数错误按当前操作检查字段、格式和固定参数;修正后再提交。
401凭据失效检查密钥是否过期、撤销或轮换,以及站点是否匹配。
402余额或额度不足核对余额、套餐和接待额度;恢复可用后再确认是否提交。
403权限或来源不符核对操作授权、账号权限和请求来源;不要关闭认证绕过。
404资源不存在或不可见核对路径、资源编号和所属企业。
405请求方法不符按该操作文档和 Allow 响应头使用 GET 或 POST。
408读取请求超时检查网络和正文上传;写入重试前核对原结果并保留原幂等键。
409版本、幂等或状态冲突先读回业务结果;有 Retry-After 时等待。修改配置先合并最新版本,结果未知不换键重做。
413请求过大按接口限制缩小请求或使用该业务提供的分批导入入口。
415正文格式不支持开放网关 POST 使用 Content-Type: application/json 和有效 JSON 正文。
422业务条件不满足按错误提示补齐配置或业务状态;不要重复提交相同无效请求。
429调用限流按 Retry-After 等待,降低调用频率;写入重试仍使用原幂等键。
503依赖不可用稍后核对服务状态;只读可有界重试,写入先确认原结果。

有 X-Request-Id 时,由有权的管理员在请求日志核对;提前拒绝的请求可能没有编号,此时记录时间、操作路径和状态。/v1/capabilities 的编号不进入业务日志。错误正文按接口解析,不依赖错误文案自动重试。

网关自身的拒绝(认证、授权、限流、幂等、格式)在 JSON 正文中返回稳定的 code,按 code 分支处理,不要解析 error 文案。没有 code 的错误由业务接口返回,按该接口说明处理。每次响应都带 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset,可在收到 429 前主动降速。

codeHTTP含义处理
INVALID_REQUEST400请求参数、查询或正文不符合网关要求按错误说明修正后再提交;不要原样重试。
ACTION_MISMATCH400正文 action 与所调用操作固定的 action 不一致省略 action,或使用操作文档中的固定值。
QUERY_MISMATCH400查询参数试图覆盖操作的固定查询删除该查询参数;需要其他分支时改用对应操作。
IDEMPOTENCY_KEY_INVALID400写请求缺少 Idempotency-Key 或格式无效提供 8–100 位字母、数字、下划线、连字符、点或冒号。
API_KEY_INVALID401缺少 Bearer 密钥,或密钥不存在、已到期、已撤销核对 Authorization 请求头与密钥有效期;必要时由管理员创建新密钥。
API_KEY_OWNER_INACTIVE401创建密钥的管理员账号已停用、移出企业或变更身份由当前企业管理员重新创建密钥。
API_KEY_ROTATED401请求执行期间密钥被轮换用新密钥读回业务结果后再决定是否重试。
API_KEY_SITE_MISMATCH403密钥不属于当前站点域名使用创建密钥时的站点地址作为 YUNFU_BASE_URL。
ORIGIN_NOT_ALLOWED403请求携带了与站点不同源的 Origin从服务端调用并去掉浏览器 Origin;密钥不得在浏览器中使用。
ACCOUNT_PERMISSION_DENIED403密钥所属账号已不具备该操作所需权限由企业管理员恢复账号权限,或改用其权限范围内的操作。
TENANT_DISABLED403密钥所属企业已停用联系平台方恢复企业后再调用。
OPERATION_NOT_GRANTED403密钥未勾选该操作调用 GET /v1/capabilities 核对 allowedOperations;需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。
OPERATION_NOT_FOUND404操作 ID 不存在按接口参考核对操作 ID 的拼写与大小写。
METHOD_NOT_ALLOWED405HTTP 方法与操作不符按 Allow 响应头使用 GET 或 POST。
REQUEST_TIMEOUT408读取请求正文超时或被取消检查网络后用原幂等键重试。
IDEMPOTENCY_KEY_REUSED409同一幂等键被用于不同的操作、查询或正文重试保持原请求完全一致;新的业务提交使用新键。
REQUEST_IN_PROGRESS409同一幂等键的原请求仍在执行按 Retry-After 等待后用原键重试,或在调用记录中按 requestId 核对。
REQUEST_OUTCOME_UNKNOWN409原请求中断,执行结果未知先读取业务数据确认是否生效;确认未生效后才用新键重新提交。
REPLAY_UNAVAILABLE409原请求已完成,但响应超过缓存上限或已过 24 小时原请求不会再次执行;通过业务读取操作获取结果。
ORIGINAL_KEY_ROTATED409原请求由轮换前的密钥发起,不重放旧回执用当前密钥读回业务结果,不换键强行重做。
PAYLOAD_TOO_LARGE413请求正文超过该操作的大小上限缩小正文,或使用该业务的分批导入操作。
UNSUPPORTED_MEDIA_TYPE415POST 未使用 application/json设置 Content-Type: application/json 并发送 JSON 正文。
RATE_LIMITED429超过密钥的每分钟调用限额按 Retry-After 等待到下一分钟窗口;可用 X-RateLimit-Remaining 提前降速。
API_BUSY429超过短时突发或并发上限(也可能以 503 返回)降低并发,按 Retry-After 退避;写入用原幂等键重试。
REQUEST_BLOCKED429账号因高频、重复越权或连续协议错误被临时封禁停止调用直到 blockedUntil;修正调用方后再恢复,换密钥不能解除。
MFA_REQUIRED403企业强制 MFA,当前不允许 API Key 机器接入联系企业管理员确认接入方案;重新登录或轮换密钥无效。
SERVICE_UNAVAILABLE503操作处理器暂不可用稍后重试;写入用原幂等键。
INTERNAL_ERROR503服务内部异常,正文含排查编号 reference只读可有界重试;写入先核对业务结果,并向支持提供 reference。