Appearance
Agent SDK 凭证
给接入方 Agent 服务发放的长期凭证。接入方 Agent 服务用这把凭证换取短时访问令牌（默认 60 分钟），再去反向读取知办AI 的知识库 / 云盘 / 组织与人员读取等数据，为对话或工作流提供上下文。
跟 API Key 的核心区别：API Key 是给「外部业务系统」长期使用，路径走对外接口；SDK 凭证是给「接入方 Agent 服务实时取数」用，先换短时令牌，按过期时间缓存复用，安全级别更高。
进入路径
左侧菜单 凭证与接入 → Agent SDK 凭证
概念速览
| 概念 | 一句话 |
|---|---|
| 客户端编号 (Client ID) | 凭证的公开标识，类似账号，长期可见。 |
| 客户端密钥 (Client Secret) | 凭证的私密部分，类似密码。仅在新建时显示一次，关闭后不可恢复。 |
| 可借能力 | 这把凭证最多可以调用的接口范围，例如知识库读取 / 云盘读取 / 组织与人员读取。 |
| 短时访问令牌 | 接入方 Agent 服务用客户端编号 + 密钥 + 当前租户/数字员工换来的 60 分钟令牌，每次实际调接口要带它。过期就再换一份。 |
| 状态 | 生效中（绿色，可用）/ 已撤销（灰色，永久不可用）。 |
| 最近换证时间 | 接入方 Agent 服务上次成功用本凭证换短时令牌的时间，没换过显示 —。 |
页面一览
截图占位:Agent SDK 凭证 —
> 主表 7 列：名称 / 客户端编号 / 可借能力（彩色标签）/ 状态 / 最近换证 / 创建 / 操作（撤销按钮）。右上 **+ 接入新 Agent**。 tenant-agent-sdk-credentials.png操作步骤
1. 接入新 Agent（创建凭证）
- 右上 + 接入新 Agent → 弹出对话框。
- 填两个字段：
- 名称：用途备注，如「销售助理 Runtime API Client」「招聘助理 Runtime API Client」。
- 可借能力：勾这把凭证最多能调用的接口范围（至少 1 个）。这是上限——接入方 Agent 服务每次换短时令牌时还能进一步缩小（如某次会话只用知识库）。
- 点 创建 → 弹「凭证创建成功」对话框，显示：
- 客户端编号：长期可见，可以多次复制；
- 客户端密钥：仅本次显示，提供复制按钮。关闭后系统不再保留明文。
- 立即把两者交给接入方 Agent 服务维护方，让他们配置到服务端环境变量或密钥库里。
2. 接入方 Agent 服务怎么用
接入方 Agent 服务收到凭证后，两步流程：
第一步：用 客户端编号 + 客户端密钥 + 当前 tenant_id + agent_id 换 60 分钟的短时访问令牌
第二步：用 短时访问令牌 调用 知识库 / 云盘 / 组织读取 接口拿数据具体接口签名、请求格式、返回结构见 租户服务端 API 和 租户自定义 Agent Runtime 接入。
接入方 Agent 服务维护方需要自己处理「令牌到期自动换证」的逻辑——SDK 通常封装好了，会按
tenant_id + agent_id [+ account_uuid]隔离缓存，并在expires_in到期前刷新；收到鉴权失败时自动再换一份重试。
3. 撤销凭证
- 在凭证所在行右侧 撤销（垃圾桶图标） → 弹确认框：
「撤销后该凭证立即不可用，已颁发的短时访问令牌全部失效——正在跑的接入方 Agent 服务调用会失败。」
- 确认后立即生效。
撤销的常见触发：
- 接入方 Agent 服务下线 或被替换；
- 怀疑密钥泄漏；
- 凭证轮换（同样建议每 90 天一轮）。
字段约束
- 名称：1-64 字符，非空。
- 可借能力：至少 1 项。建议按最小权限——只用知识库就别勾云盘；不需要查成员/部门就别勾组织与人员读取。
- 状态：撤销不可恢复，需要重新走「接入新 Agent」生成新凭证。
安全注意事项
- 客户端密钥仅创建时显示一次，系统只存加密密文。
- 客户端密钥要放到接入方 Agent 服务的环境变量 或 密钥管理服务，不要写在代码里、提交到 Git。
- 给每个接入方 Agent 服务一把独立凭证。多服务共用凭证：审计混乱，撤销一把全部断。
- 凭证可借能力只能缩小不能扩大：要给接入方 Agent 服务更多权限，新建一把新凭证，不要试图改老的。
相关菜单
- 完整接入流程示例：租户自定义 Agent Runtime 接入 · 端到端流程
- 给外部系统（非接入方 Agent 服务）的凭证：API Key 管理
- 当前账号会话列表：我的会话
- 开发者参考（换证接口 / 错误码 / SDK 示例）：开发者文档
常见问题
Q：客户端密钥真的找不回吗？ A：找不回。系统只存加密密文，明文从创建那一刻起只剩在你和接入方 Agent 服务维护方手里。错过这一次只能撤销旧凭证 + 新建一把。
Q：撤销凭证后，正在跑的 Agent 会话会立刻挂吗？ A：会。撤销不仅让凭证不能再换证，还会让已颁发的所有短时访问令牌立即失效。接入方 Agent 服务收到鉴权失败后尝试自动重新换证——发现凭证已撤销，最终失败。
Q：短时令牌默认 60 分钟，怎么这么短？ A：安全考虑——即便令牌泄漏，最多 60 分钟就会失效。Agent SDK 通常封装了「自动换证」逻辑，对业务无感。
Q：一个接入方 Agent 服务能挂多把凭证吗？ A：技术上可以，但不建议。一个服务一把凭证最方便审计和轮换。如果同一个产品需要分多个运行入口（如客服、销售各一个），给每个入口或服务单独发凭证。
Q：能加新的「可借能力」吗（如让接入方 Agent 服务写知识库）？ A：当前只开放读取。写入能力涉及更复杂的权限隔离，按平台路线图分批开放。需要时关注 开发者文档 更新。
Q：「最近换证时间」一直显示 — 说明什么？ A：Agent 从来没成功换过证。先让 Agent 维护方检查：客户端编号 / 密钥是否正确、网络是否能访问平台、对接接口路径是否对。