读取智能体
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"参数与响应
- 权限范围
- 智能体配置与对话
查询参数
字段定义待补充,请结合示例核对。
响应字段
| 字段 | 类型 | 返回约定 | 说明 |
|---|---|---|---|
revision | number | 固定返回 | 企业目录当前版本;POST createAgent 必须携带。 |
agents[] | {id,name,description,modelId,archived,publishedVersion,dirty,updated,channels} | 固定返回 | 智能体目录,包括草稿及已归档项目;不是仅返回已发布智能体。 |
workflows[] | {id,name,versions:[{version,name}]} | 固定返回 | 含 conversation 版本的工作流目录。 |
channels / publicKnowledgeLibraries | array | 固定返回 | 具备 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 前主动降速。
| code | HTTP | 含义 | 处理 |
|---|---|---|---|
INVALID_REQUEST | 400 | 请求参数、查询或正文不符合网关要求 | 按错误说明修正后再提交;不要原样重试。 |
ACTION_MISMATCH | 400 | 正文 action 与所调用操作固定的 action 不一致 | 省略 action,或使用操作文档中的固定值。 |
QUERY_MISMATCH | 400 | 查询参数试图覆盖操作的固定查询 | 删除该查询参数;需要其他分支时改用对应操作。 |
IDEMPOTENCY_KEY_INVALID | 400 | 写请求缺少 Idempotency-Key 或格式无效 | 提供 8–100 位字母、数字、下划线、连字符、点或冒号。 |
API_KEY_INVALID | 401 | 缺少 Bearer 密钥,或密钥不存在、已到期、已撤销 | 核对 Authorization 请求头与密钥有效期;必要时由管理员创建新密钥。 |
API_KEY_OWNER_INACTIVE | 401 | 创建密钥的管理员账号已停用、移出企业或变更身份 | 由当前企业管理员重新创建密钥。 |
API_KEY_ROTATED | 401 | 请求执行期间密钥被轮换 | 用新密钥读回业务结果后再决定是否重试。 |
API_KEY_SITE_MISMATCH | 403 | 密钥不属于当前站点域名 | 使用创建密钥时的站点地址作为 YUNFU_BASE_URL。 |
ORIGIN_NOT_ALLOWED | 403 | 请求携带了与站点不同源的 Origin | 从服务端调用并去掉浏览器 Origin;密钥不得在浏览器中使用。 |
ACCOUNT_PERMISSION_DENIED | 403 | 密钥所属账号已不具备该操作所需权限 | 由企业管理员恢复账号权限,或改用其权限范围内的操作。 |
TENANT_DISABLED | 403 | 密钥所属企业已停用 | 联系平台方恢复企业后再调用。 |
OPERATION_NOT_GRANTED | 403 | 密钥未勾选该操作 | 调用 GET /v1/capabilities 核对 allowedOperations;需要时创建包含该操作的新密钥。反复调用未授权操作会触发请求防护。 |
OPERATION_NOT_FOUND | 404 | 操作 ID 不存在 | 按接口参考核对操作 ID 的拼写与大小写。 |
METHOD_NOT_ALLOWED | 405 | HTTP 方法与操作不符 | 按 Allow 响应头使用 GET 或 POST。 |
REQUEST_TIMEOUT | 408 | 读取请求正文超时或被取消 | 检查网络后用原幂等键重试。 |
IDEMPOTENCY_KEY_REUSED | 409 | 同一幂等键被用于不同的操作、查询或正文 | 重试保持原请求完全一致;新的业务提交使用新键。 |
REQUEST_IN_PROGRESS | 409 | 同一幂等键的原请求仍在执行 | 按 Retry-After 等待后用原键重试,或在调用记录中按 requestId 核对。 |
REQUEST_OUTCOME_UNKNOWN | 409 | 原请求中断,执行结果未知 | 先读取业务数据确认是否生效;确认未生效后才用新键重新提交。 |
REPLAY_UNAVAILABLE | 409 | 原请求已完成,但响应超过缓存上限或已过 24 小时 | 原请求不会再次执行;通过业务读取操作获取结果。 |
ORIGINAL_KEY_ROTATED | 409 | 原请求由轮换前的密钥发起,不重放旧回执 | 用当前密钥读回业务结果,不换键强行重做。 |
PAYLOAD_TOO_LARGE | 413 | 请求正文超过该操作的大小上限 | 缩小正文,或使用该业务的分批导入操作。 |
UNSUPPORTED_MEDIA_TYPE | 415 | POST 未使用 application/json | 设置 Content-Type: application/json 并发送 JSON 正文。 |
RATE_LIMITED | 429 | 超过密钥的每分钟调用限额 | 按 Retry-After 等待到下一分钟窗口;可用 X-RateLimit-Remaining 提前降速。 |
API_BUSY | 429 | 超过短时突发或并发上限(也可能以 503 返回) | 降低并发,按 Retry-After 退避;写入用原幂等键重试。 |
REQUEST_BLOCKED | 429 | 账号因高频、重复越权或连续协议错误被临时封禁 | 停止调用直到 blockedUntil;修正调用方后再恢复,换密钥不能解除。 |
MFA_REQUIRED | 403 | 企业强制 MFA,当前不允许 API Key 机器接入 | 联系企业管理员确认接入方案;重新登录或轮换密钥无效。 |
SERVICE_UNAVAILABLE | 503 | 操作处理器暂不可用 | 稍后重试;写入用原幂等键。 |
INTERNAL_ERROR | 503 | 服务内部异常,正文含排查编号 reference | 只读可有界重试;写入先核对业务结果,并向支持提供 reference。 |