租户自定义 Agent Runtime 接入

把你自己租户维护的 Agent 服务接进知办AI，作为本租户的数字员工运行环境。适合企业内部已经有 HR、客服、销售、审批等 Agent 服务，希望员工在知办AI客户端里直接对话使用。

和平台模板的区别

租户自定义 Agent Runtime：由本租户自己部署、自己保存凭证、只服务本租户。
平台提供的 Agent 模板：由知办AI平台侧维护，租户只启用或复制模板。

本页只讲租户自建 Runtime；它只处理自己租户的数据，不涉及跨租户接入。

接入流程

text

准备租户自己的 Agent Runtime 服务
        │
        ▼
租户后台创建 Agent SDK 凭证
  └─ Agent 服务调用知办AI服务器的知识库 / 云盘 / 组织读取接口时使用
        │
        ▼
租户后台创建智能体托管环境
  └─ 填 Runtime 地址和 Runtime API Key
        │
        ▼
测试 /zap/v1/runtime_card
        │
        ▼
创建数字员工并绑定该 runtime
        │
        ▼
员工在客户端发起对话
  └─ 知办AI服务器调 Agent 服务 /zap/v1/sessions/messages

需要准备什么

准备项	说明
Runtime 服务地址	例如 `https://agent.example.com`，填写根地址，不带 `/zap/v1` 后缀。
Runtime API Key	知办AI 调你的 `/zap/v1/*` 时带在 `Authorization: Bearer <runtime_api_key>`。
Agent SDK 凭证	你的 Agent 服务调用知办AI服务器的知识库 / 云盘 / 组织读取等服务端 API 时使用。
Agent key	Runtime 内部的业务入口标识。单入口可用 `main`，多入口可用 `hr`、`finance` 等。

后台怎么配

1. 创建 Agent SDK 凭证

进入：

text

左侧菜单 → 凭证与接入 → Agent SDK 凭证 → + 接入新 Agent

勾选 Agent 服务需要的可借能力。保存后得到 client_id 和 client_secret，只显示一次。Agent 服务用它和当前 tenant_id 换 tenant/runtime-scoped 短时 st_，再在知识库等业务请求中传当前数字员工 UUID。A2A 场景沿用既有可选 agent_id 绑定。

st_ 不需要每次调用都换。普通业务按 tenant_id 缓存，到期前刷新；只有 A2A 显式绑定 agent_id 或个人知识显式绑定 user_id 时，才把对应维度加入缓存键。如果业务接口返回 401 invalid_session_token，重新换发后重试一次。

2. 创建智能体托管环境

进入：

text

左侧菜单 → 数字员工 → 智能体托管环境 → + 新增托管

填写：

字段	填什么
显示名称	给管理员看的名字，例如 `招聘助手 Runtime`。
平台类型	选择 `自定义智能体平台 (ZAP 协议)`。
部署方式	选择 `外部服务接入`。
服务地址	你的 Runtime 根地址。
访问凭证	Runtime API Key。

点击“测试连通性”。系统会带 Runtime API Key 请求：

text

GET <服务地址>/zap/v1/runtime_card

测试通过后保存。

3. 创建数字员工

进入：

text

左侧菜单 → 数字员工 → 数字员工列表 → + 新建数字员工

选择刚才创建的运行环境，填写名称、头像、简介和能力装配。发布后，员工就能在客户端看到这个数字员工并发起对话。

Runtime 要实现哪些接口

Endpoint	谁调用	用途
`GET /zap/v1/runtime_card`	知办AI	声明 Runtime 能力，用于连通性测试。
`POST /zap/v1/sessions`	知办AI	创建会话。
`POST /zap/v1/sessions/{id}/messages`	知办AI	推送用户消息，Runtime 用 SSE 返回结果。
`POST /zap/v1/sessions/{id}/cancel`	知办AI	取消生成，推荐实现。
`DELETE /zap/v1/sessions/{id}`	知办AI	删除会话，推荐实现。
`POST /zap/v1/instances`	知办AI	初始化租户 / 用户 / 数字员工实例，推荐实现。

完整协议见 ZAP 消息协议，结构化组件见 EMP 组件清单。

服务端 API 怎么用

租户自建 Agent 服务如果需要在对话中查知识库：

用 Agent SDK 凭证和当前 ZAP session 的 ctx.tenant_id 调 grant_type=runtime_access 换 tenant/runtime-scoped st_；需要检索个人私有知识时同时绑定 ctx.user_id。
缓存 st_ 到过期前。
用 Authorization: Bearer st_... 调 POST /api/external/v1/knowledge/retrieve，body 传 ctx.agent_id + query。服务端校验 Agent 与 token 的租户/Runtime 后检索后台关联知识库；调用方不用自己维护 KB UUID 列表。

python

client = ZhibanClient.for_runtime_access(
    base_url,
    client_id,
    client_secret,
    tenant_id=ctx.tenant_id,
    user_id=ctx.user_id,
)
result = client.kb.retrieve_associated(agent_id=ctx.agent_id, query="差旅报销标准")

外部 CRM / BI / Webhook 这类非 Agent 服务，则使用 API Key 调租户服务端 API。

租户自定义 Agent Runtime 接入 ​

接入流程 ​

需要准备什么 ​

后台怎么配 ​

1. 创建 Agent SDK 凭证 ​

2. 创建智能体托管环境 ​

3. 创建数字员工 ​

Runtime 要实现哪些接口 ​

服务端 API 怎么用 ​

相关链接 ​

租户自定义 Agent Runtime 接入

接入流程

需要准备什么

后台怎么配

1. 创建 Agent SDK 凭证

2. 创建智能体托管环境

3. 创建数字员工

Runtime 要实现哪些接口

服务端 API 怎么用

相关链接