自定义 Agent Runtime 接入

把你自己开发的 LLM 服务接进知办AI，作为“接入方 Agent Runtime”承接推理、工具执行和本地用户映射；知办AI侧则把它配置成“知办AI 数字员工”，供员工在客户端聊天、拉群协作和使用平台能力。

这页怎么读

要先跑通接入：按端到端接入流程做。
要看知办AI服务器怎么把消息推给你的 Agent 服务：看 ZAP 消息协议。
要看聊天里可渲染哪些卡片、表单、图表：看 EMP 组件清单。
要让一个数字员工在运行时调用另一个数字员工：看 Agent 间协作 A2A。
要看知识库等平台开放能力：看服务端 API 总览。
要直接调接口验证：打开 API 在线调试。

文档分层

自定义 Agent Runtime 接入不再只是一组 KB API。当前对外文档按 4 层组织：

分类	解决的问题	当前页面
接入指南	怎么申请凭证、注册 runtime、启动接入方 Agent 服务	本页、鉴权与凭证
服务端 API	接入方 Agent 服务或外部系统主动调用知办AI的数据与能力	服务端 API 总览、知识库 API 指南、记忆 API 指南、API 列表
Runtime 协作	接入方 Agent Runtime 如何在处理当前用户消息时调用另一个数字员工	Agent 间协作 A2A
协议与组件	知办AI服务器如何把用户消息推给接入方 Agent Runtime，接入方如何流式返回文本、工具过程、表单、图表等	ZAP 消息协议、EMP 组件清单
API Reference	全字段 schema、在线调试、OpenAPI 源	在线调试、OpenAPI 规范

术语先统一

后文固定用这几个名字，避免把双方都叫成 Agent：

名称	指谁	负责什么
接入方 Agent Runtime	接入方部署的 ZAP Runtime 服务	暴露 `/zap/v1/*`，承接知办AI推来的实例初始化、会话和消息请求。
接入方 Agent 服务	接入方 Agent Runtime 背后的业务实现	做 LLM 推理、工具调用、审批流、本地数据库和本地用户映射。
知办AI 数字员工	知办AI 管理后台里创建/发布的数字员工配置	给终端用户展示，并决定绑定哪个 runtime、使用哪个 `agent_key`。
知办AI服务器	知办AI 后端调用方	根据数字员工配置调用接入方 Agent Runtime。

端到端接入流程

先记住一句话：后台负责把接入方 Agent Runtime 注册成一个 runtime，SDK 负责把 /zap/v1/* 协议端点暴露出来，终端用户登录后知办AI服务器会初始化相关知办AI 数字员工的外部实例，真正聊天时再创建 session 并把用户消息推给接入方 Agent Runtime。

准备一个可公网/内网访问的接入方 Agent Runtime
        │
        ▼
后台创建凭证和托管环境
  ├─ Agent SDK 凭证: 接入方 Agent 服务调用知办AI服务器时使用
  └─ Runtime API Key: 知办AI服务器调你的 /zap/v1/* 时使用
        │
        ▼
后台测试连通,读取 /zap/v1/runtime_card
        │
        ▼
租户注册或后台启用托管环境
  └─ 知办AI服务器调 /zap/v1/tenants/{tenant_id} 同步租户资料
        │
        ▼
创建、发布或修改知办AI 数字员工并绑定这个 runtime
  └─ 知办AI服务器调 /zap/v1/agents 同步数字员工入口和配置
        │
        ▼
用户登录并进入客户端
  ├─ 知办AI服务器为相关外部 ZAP 数字员工调 /zap/v1/instances
  ├─ 接入方 Agent Runtime 返回 runtime_identity,可包含 agent_instance_id
        │
        ▼
用户开始聊天
  ├─ 知办AI服务器调 /zap/v1/sessions 创建会话
  └─ 知办AI服务器调 /zap/v1/sessions/{id}/messages 推消息，接入方 Agent Runtime 用 SSE 返回

Step 0 接入前准备

接入方需要先准备好 4 件事:

准备项	说明
Runtime 服务地址	例如 `https://agent.example.com`;后台填写接入方 Agent Runtime 根地址,不要带 `/zap/v1` 后缀。
Runtime API Key	由接入双方约定的一段密钥;知办AI调用你的 `/zap/v1/*` 时会放在 `Authorization: Bearer <runtime_api_key>`。
Agent key	接入方 Agent Runtime 内部的业务入口标识。单入口 runtime 通常用 `main`;多入口 runtime 可用 `finance`、`hr` 等。
Agent SDK 凭证	如果接入方 Agent 服务需要调用知办AI知识库、云盘等服务端 API，需要在后台申请 `client_id/client_secret`，并按当前 `tenant_id` 换取 tenant/runtime-scoped `st_`。A2A 固定调用方场景可选用 `agent_id` 绑定。

生产环境建议使用 Vault、KMS 或云厂商 Secret Manager 注入密钥,不要把 client_secret、runtime_api_key 写进代码或 Git。

Step 1 后台页面怎么配

1.1 创建 Agent SDK 凭证

用途:接入方 Agent 服务在处理用户问题时,如果要主动调用知办AI服务端 API,比如检索知识库,就用这组凭证换短期 Session Token。

text

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

页面里通常填写:

字段	填什么	保存后得到什么
显示名称	例如 `行政协同 Runtime API Client`	后台列表里展示给管理员看。
备注/用途	说明接入方 Agent 服务会调用哪些平台能力	便于审计和后续排障。
授权能力	勾选接入方 Agent 服务需要访问的知识库、云盘或后续能力域	生成的 Session Token 只拥有这些能力。

保存后得到:

值	什么时候用
`client_id`	接入方 Agent 服务调 `/api/external/v1/oauth/token` 换 Session Token 时使用。
`client_secret`	只显示一次;接入方 Agent 服务后端保存,不能放前端。

1.2 创建智能体托管环境

用途:把接入方 Agent Runtime 注册到知办AI,让知办AI 数字员工可以选择它作为运行环境。

text

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

页面里通常填写:

显示名称:例如 行政协同 ZAP Runtime。管理员在 runtime 列表和数字员工创建页看到的名字。
平台类型:选择 自定义智能体平台 (ZAP 协议)。表示知办AI服务器按 ZAP 协议调用接入方 Agent Runtime。
部署方式:选择 外部服务接入。表示接入方 Agent 服务负责推理和工具执行。
服务地址:例如 https://agent.example.com。填接入方 Agent Runtime 根地址,系统会自动拼 /zap/v1/runtime_card 等路径。
访问凭证:填写你的 runtime_api_key。知办AI服务器调接入方 Agent Runtime 的 /zap/v1/* 时使用。
外部环境标识:可选，例如 chuangye-prod。用于让接入方在 /instances 和新建 /sessions 中识别当前托管环境；不是知办租户 ID，也不参与鉴权。请勿填写密钥或个人敏感信息。

填写后先点“测试连通性”。测试会做三件事:

带 Authorization: Bearer <runtime_api_key> 请求 GET <服务地址>/zap/v1/runtime_card。
校验 protocol_version、default_agent_key、runtime_ui_components 等基础能力。
如果是平台级 runtime,还会要求 multi_tenant_isolation=true。

测试通过后再保存/启用。保存后,这个 runtime 会出现在知办AI 数字员工创建页的“运行环境”下拉里。

1.3 创建数字员工

text

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

页面里关键字段:

字段	填什么	影响
名称/头像/简介	给终端用户看的知办AI 数字员工资料	决定客户端列表和聊天入口展示。
运行环境	选择刚才创建的 ZAP runtime，或租户已被授权使用的运行环境	决定知办AI服务器把消息推到哪个接入方 Agent Runtime。
Agent key	不需要手动填写,由知办AI后台按所选运行环境自动生成或补齐	知办AI服务器创建 session 时会把它作为 `agent_key` 传给接入方 Agent Runtime；运行期只校验系统是否已保存该值,缺失时会话失败,不会临时用 runtime 默认值兜底。
能力装配	勾选知识库、技能、应用等	接入方 Agent 服务调用知办AI服务器能力时会受这些绑定限制。

保存草稿后只记录配置;发布后终端用户才能看到并发起会话。

Step 2 接入方 Agent 服务配置

bash

export ZHIBAN_BASE_URL=https://zhiban.creditease.corp
export ZHIBAN_CLIENT_ID=agentsdk_xxx
export ZHIBAN_CLIENT_SECRET=secret_xxx
export ZHIBAN_RUNTIME_API_KEY=runtime_xxx

Step 3 接入方 Agent 服务调用知办AI服务器

这是接入方 Agent 服务 → 知办AI服务器的方向。接入方 Agent 服务运行时需要查知识库、后续 SkillHub 或其它平台能力时，先用 client_id/client_secret + ctx.tenant_id 换 tenant/runtime-scoped 短期 Session Token，再在知识库请求中传当前 ctx.agent_id。在线请求必须使用当前 ZAP session 上下文，不能用环境变量里的固定 Agent 覆盖当前数字员工。

curlPython SDKGo SDK

bash

TOKEN=$(curl -sX POST -H "Content-Type: application/json" \
  -d '{"grant_type":"runtime_access","client_id":"'$ZHIBAN_CLIENT_ID'","client_secret":"'$ZHIBAN_CLIENT_SECRET'","tenant_id":"'$TENANT_ID'"}' \
  "$ZHIBAN_BASE_URL/api/external/v1/oauth/token" | jq -r .access_token)

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"差旅报销标准"}' \
  "$ZHIBAN_BASE_URL/api/external/v1/knowledge/retrieve"

python

from zhiban_agent_sdk import ZhibanClient

with ZhibanClient.for_runtime_access(
    "https://zhiban.creditease.corp",
    "agentsdk_xxx",
    "secret_xxx",
    tenant_id=ctx.tenant_id,
    user_id=ctx.user_id,
) as client:
    result = client.kb.retrieve_associated(agent_id=ctx.agent_id, query="差旅报销标准")

c, _ := zhibansdk.NewWithTenantRuntimeAccess(
    baseURL, clientID, clientSecret, tenantID,
)
res, _ := c.KB().RetrieveAssociated(ctx, agentID, "差旅报销标准")

更多能力域见服务端 API 总览。

Step 4 知办AI推对话给接入方 Agent Runtime

这是知办AI服务器 → 接入方 Agent Runtime 的方向。接入方 Agent Runtime 需要实现 /zap/v1/* 数据面;使用官方 SDK 时,这些路由由 SDK 自动生成,业务方主要写 handler。

Endpoint	谁调用	输入	输出	必须程度
`GET /zap/v1/runtime_card`	知办AI服务器	无 body	runtime 能力声明	必须
`PUT /zap/v1/tenants/{tenant_id}`	知办AI服务器	租户资料	`runtime_identity.tenant_id`	推荐
`POST /zap/v1/agents`	知办AI服务器	知办AI 数字员工配置	`agent_key`	推荐
`POST /zap/v1/instances`	知办AI服务器	租户、用户、身份事实、知办AI 数字员工上下文	`runtime_identity`、`mapping_status`	推荐
`POST /zap/v1/sessions`	知办AI服务器	`agent_key`、平台用户、`runtime_identity`	`session_id`、可选 `session_token`	必须
`POST /zap/v1/sessions/{id}/messages`	知办AI服务器	用户消息 blocks	SSE 事件流	必须
`POST /zap/v1/sessions/{id}/cancel`	知办AI服务器	无 body	取消结果	推荐
`DELETE /zap/v1/sessions/{id}`	知办AI服务器	无 body	删除结果	推荐

最小 FastAPI 示例：

python

from fastapi import FastAPI
from zhiban_agent_sdk.zap import ZapRuntime, emp
from zhiban_agent_sdk.zap.fastapi import build_router

app = FastAPI()
runtime = ZapRuntime(
    token_env="ZHIBAN_RUNTIME_API_KEY",
    name="admin-assistant-runtime",
    framework="zap",
    vendor="your-company",
)
runtime.add_agent("main", name="行政协同助手", system_prompt="你是行政协同助手。")
runtime.set_identity_provider(my_identity_store)  # 可选: 实现 tenant/user upsert/resolve

@runtime.on_message
async def handle(ctx, inbound):
    # SDK 会把知办AI服务器创建 session 时传入的用户/会话上下文挂到 ctx 上。
    # 这些字段可以直接用于租户隔离、记忆检索、审计和工具调用参数。
    print("zap ctx", ctx.to_log_dict())

    if "报表" in inbound.text:
        return [emp.chart(kind="bar", title="月度行政费用", data=[
            {"label": "1月", "value": 12.0},
            {"label": "2月", "value": 10.6},
        ])]
    return [emp.markdown("收到，我来处理。")]

app.include_router(build_router(runtime), prefix="/zap/v1")

完整 wire 层见 ZAP 消息协议。

租户同步什么时候发生

租户同步不是用户点开聊天时才做。下面两类后台动作会让知办AI服务器调用接入方 Agent Runtime:

场景	触发点	知办AI服务器调用
新租户注册后,平台默认启用某个外部 ZAP runtime	`tenant_runtime_enablements:<tenant_id>:provision` 配置变更	`PUT /zap/v1/tenants/{tenant_id}`
后台管理在租户下新增或启用自定义 ZAP 托管环境	`tenant_runtime_enablements:<tenant_id>` 配置变更	`PUT /zap/v1/tenants/{tenant_id}`

请求示例:

json

{
  "tenant": {
    "tenant_id": "tnt_xxx",
    "name": "某某公司",
    "status": "active"
  },
  "metadata": {
    "source": "easyo",
    "runtime_environment_id": 16
  }
}

响应示例:

json

{
  "ok": true,
  "runtime_identity": {"tenant_id": "tenant_123"},
  "mapping_status": "matched"
}

这一步只同步/更新接入方本地租户,不创建用户、不创建会话。调用失败不会阻断知办AI自己的租户开通,但知办AI服务器会记录失败;后续用户登录初始化实例时,POST /instances 仍会携带完整租户资料作为兜底。

数字员工信息什么时候同步

当知办AI 数字员工绑定了外部 ZAP runtime,且 runtime_card 声明了 control_plane_capabilities 里的 agent.create/update/delete/list,知办AI服务器会把数字员工配置同步给接入方 Agent Runtime。

触发点:

场景	知办AI服务器行为
新建并发布知办AI 数字员工	写 `runtime_resync_outbox`,prewarm worker 生成 `agent_register` 任务,调用 `POST /zap/v1/agents`。
修改名称、模型、工具或能力绑定后发布/保存	同上,幂等更新接入方 runtime 内的 `agent_key` 配置。
删除或下架数字员工	如果 runtime 声明删除能力,后续可调用对应 delete 端点；未声明时不调用。

POST /zap/v1/agents 同步的是“知办AI 数字员工入口配置”,例如 agent_key/name/model/tools;它不是用户专属实例。用户专属本地实例仍由 POST /zap/v1/instances 返回的 runtime_identity.agent_instance_id 表达。

用户体系怎么关联

如果接入方 Agent Runtime 有自己的用户表、权限体系、记忆或用户专属实例,推荐实现 POST /zap/v1/instances。知办AI会把“平台知道的事实”和“当前知办AI 数字员工上下文”推给 runtime,但不会替 runtime 选择唯一键,也不会在后台配置“按邮箱/手机号/工号匹配”。

这个设计跟 SCIM / OIDC 的行业做法一致:平台把身份事实同步出去,外部系统保存自己的本地映射;OIDC 场景下稳定主体通常是 issuer + subject,邮箱、手机号和姓名只是 profile。

管理后台不配置“身份来源 / 唯一匹配字段 / 匹配策略”。这些是接入方系统自己的本地用户策略:可以用 OIDC subject、LDAP objectGUID、邮箱、手机号、工号或人工绑定,但由 runtime 自己决定并持久化。

用户登录后的实例初始化链路:

后台测试连通,知办AI读取 GET /zap/v1/runtime_card。runtime 声明 agent_instance_initialization.supports_initialize=true 后，知办AI服务器自动启用实例初始化流程；这不是后台人工开关。
终端用户登录后，知办AI服务器按通讯录可见性计算该用户可见且绑定外部 ZAP runtime 的知办AI 数字员工。
对每个相关知办AI 数字员工，知办AI服务器生成 agent_instance_init 预热任务。
任务执行时，知办AI服务器读取当前租户、当前用户 profile、平台账号 UUID、成员关系、OIDC/LDAP provider subject、已验证联系方式，以及当前知办AI 数字员工的 agent_id / agent_key / name。
知办AI服务器调 POST /zap/v1/instances。请求里会带 agent 对象，用于让接入方创建或定位自己的本地 Agent 实例；同时会带 llm 对象，给接入方服务端调用知办AI AIGC 网关。后台配置了外部环境标识时，还会带 metadata.runtime_environment.external_id。
接入方 Agent Runtime 返回 runtime_identity.tenant_id/user_id,如果有“租户 + 用户 + 数字员工”维度的本地实例,还要返回 runtime_identity.agent_instance_id。
知办AI服务器调 POST /zap/v1/sessions，在 body 里附上 agent_key、上一步返回的 runtime_identity，以及同一个可选 metadata.runtime_environment.external_id。如果登录预热还没完成，会话前会幂等补调一次同一初始化接口。
SDK handler 通过 ctx.runtime_identity 获取 tenant_id/user_id/agent_instance_id，通过 ctx.external_environment_id 获取外部环境标识；旧版 ctx.external_identity 保留为兼容别名。

用于系统通知 API 或主动发送聊天消息 API 时，字段对应关系如下：

API 字段	ZAP Runtime 可读取来源	含义
`user_id`	`/zap/v1/instances` 或 `/zap/v1/sessions` 的 `user.user_id` / SDK `ctx.user_id`	目标知办用户账号 ID，值为知办平台稳定 UUID
`agent_id`	`/zap/v1/agents` 同步配置里的数字员工 UUID，或 `/zap/v1/instances` 的 `agent.agent_id`	知办数字员工 ID，值为知办平台稳定 UUID
外部环境标识	`/zap/v1/instances`、新建 `/zap/v1/sessions` 的 `metadata.runtime_environment.external_id`；Python SDK 为 `ctx.external_environment_id`，Go SDK 为 `inbound.Context.ExternalEnvironmentID`	接入方自定义的环境级引用；不参与知办身份、授权或租户隔离
`third_notification_id` / `third_message_id`	接入方自己的通知或消息 ID	对方系统资源 ID，用于排查和审计关联；按调用的通知 / 聊天接口选择字段

agent_key 和 agent_instance_id 不是一回事:

字段	谁提供	解决什么问题
`agent_key`	知办AI 数字员工配置	定位接入方 Agent Runtime 里的哪类业务入口,例如 `main`、`finance`；由知办AI后台托管生成/补齐并保存,不得在运行期临时依赖 runtime 默认值。
`runtime_identity.agent_instance_id`	接入方 Agent Runtime 在初始化响应里返回	如果接入方系统会给“某租户 + 某用户 + 某数字员工”创建独立本地实例,就用它定位那个实例。没有用户或 agent 专属实例时可以不返回。

如果接入方系统是“每个租户/用户/数字员工一个本地实例”,请在 POST /instances 响应的 runtime_identity.agent_instance_id 中返回;SDK 会把它随 session 保存下来,handler 可以从 ctx.runtime_identity 读取。

POST /zap/v1/instances 里与实例初始化相关的核心字段示例:

jsonc

{
  "tenant": {"tenant_id": "tnt_xxx", "name": "某某公司", "status": "active"},
  "user": {"user_id": "acc_xxx", "display_name": "张三"},
  "agent": {
    "agent_id": "de_xxx",
    "agent_key": "main",
    "name": "行政协同助手"
  },
  "identity": {
    "source": "easyo",
    "provider_subjects": {"oidc": "stable-sub"}
  },
  "llm": {
    "base_url": "https://aigc-gateway.example.com/v1",
    "api_key": "sk_tenant_account_xxx",
    "model": "gpt-5.4",
    "source": "aigc_gateway",
    "scope": "tenant_account"
  },
  "metadata": {
    "runtime_environment": {
      "external_id": "chuangye-prod"
    }
  }
}

llm.api_key 是当前“租户 + 用户”维度的模型调用密钥,只给接入方 Agent Runtime 服务端使用。知办AI必须先成功创建/复用这个用户级 key 才会继续初始化实例;如果创建、落库或解密失败,本次 /instances 会失败并由知办AI服务器重试,不会把平台全局 AIGC token 作为兜底 key 传给接入方。不要把 llm.api_key 返回给浏览器/移动端,不要写日志,不要保存到会话消息或本地聊天 metadata。如果接入方完全使用自己的模型网关,可以忽略这个对象。

响应示例:

jsonc

{
  "ok": true,
  "runtime_identity": {
    "tenant_id": "tenant_123",
    "user_id": "user_456",
    "agent_instance_id": "agent_instance_789"
  },
  "mapping_status": "matched"
}

runtime 自己处理本地用户映射并返回 mapping_status; 知办AI不替 runtime 查库,也不维护外部系统用户可用性的全局标记。runtime 返回 matched/created 后知办AI服务器才继续正式会话,返回 pending/conflict 时本次会话停止。

mapping_status 的含义:

值	runtime 表达的意思	知办AI服务器行为
`matched`	已找到并绑定本地用户	继续创建 session。
`created`	已创建本地影子用户或接入方本地实例	继续创建 session。
`pending`	需要 runtime 管理员人工绑定或异步处理	本次会话停止,后续可重试。
`conflict`	找到多个候选或安全策略不允许自动绑定	本次会话停止,提示处理。

runtime 常见处理方式:

租户现状	runtime 可用事实
已接 OIDC / SSO	`provider_subjects.oidc`、兼容 `provider_issuer/provider_subject`。
已接 LDAP	`provider_subjects.ldap` 或兼容 `provider_subject`。
没有统一 SSO	`user_id`、已验证邮箱/手机号、用户名、部门等 profile。
只有姓名	`display_name` 只能展示,不应作为唯一识别依据。

这块由接入方 runtime 处理最终绑定:知办AI传平台 tenant_id/user_id、用户 profile 和 provider subject 等身份事实,但不会替外部系统写它自己的用户表。外部系统返回 runtime_identity 后,双方都用这组映射进行后续对话、记忆和审计。

Handler 入参与注册口

使用 build_router(runtime) 后，SDK 会自动暴露 /zap/v1/runtime_card、/agents、/sessions*，并负责：

校验 Authorization: Bearer <runtime_api_key>。
若配置 identity provider,暴露 /instances 并把租户/用户/数字员工实例初始化请求交给你的 store。
/instances 请求里的 llm 会交给接入方 runtime 的实例初始化逻辑；如果你的 runtime 需要使用知办AI AIGC 网关,请在本地实例初始化时保存安全引用或放入服务端内存上下文,后续消息 handler 按 runtime_identity.agent_instance_id 找回这份租户用户级配置来调用模型,不要落明文日志。
/instances 请求里的 metadata.runtime_environment.external_id 会原样交给 identity provider；Python provider 从 payload["metadata"]["runtime_environment"]["external_id"] 读取，Go provider 从 req.ExternalEnvironmentID() 读取。
创建/读取 session，并把知办AI服务器传来的 tenant、account、conversation、debug flags 放进 ZapMessageContext。
把 POST /sessions 中的 runtime_identity、identity、profile 保存在 session metadata,handler 可通过 ctx.runtime_identity 读取；ctx.external_identity 是兼容别名。
把 POST /sessions 中的 metadata.runtime_environment.external_id 暴露为 Python ctx.external_environment_id / Go inbound.Context.ExternalEnvironmentID；空值返回 None / 空字符串。
把 handler 返回的 EMP blocks 包装成 ZAP SSE 终态事件。
对异常做敏感信息清洗。

业务方只需要注册 handler：

python

@runtime.on_message
async def handle_default(ctx, inbound):
    # fallback handler
    ...

@runtime.on_agent_message("finance")
async def handle_finance(ctx, inbound):
    # 多入口 runtime 可按 agent_key 注册不同 handler
    ...

handler 入参：

入参	说明
`ctx.session_id`	本次 ZAP session ID
`ctx.agent_key`	当前数字员工在 runtime 内的 key
`ctx.tenant_id`	当前租户 ID
`ctx.user_id`	当前用户/账号 ID
`ctx.conversation_id`	平台侧会话 ID，可能为空
`ctx.purpose` / `ctx.session_kind`	session 用途和类型
`ctx.debug_flags`	调试标记
`ctx.runtime_identity`	runtime 本地用户映射，来自 identity resolve 或 session metadata
`ctx.external_identity`	兼容旧版 SDK 的别名，返回同一份 runtime identity
`ctx.external_environment_id`	后台为当前托管环境配置的接入方外部引用；未配置时为 `None`
`ctx.state`	业务注入的 LLM client、数据库、知识库 client 等依赖
`ctx.to_log_dict()`	安全日志快照，不包含 bearer token、session_token 或 header
`inbound.text`	SDK 抽取后的用户文本
`inbound.blocks`	原始入站 blocks，表单/审批回填会在这里

handler 可以返回 EMP blocks、ZapHandlerResult，或用于工具过程 / HITL 的事件流 [(event_name, data), ...]。SDK 会负责把它们编码成 SSE。

apps/example/agent-example 当前就是按这个标准模式组织：/zap/v1/* 由 build_router(_zap_runtime) 暴露，行政场景只通过 @_zap_runtime.on_agent_message("main") 注册处理逻辑。真实自然语言入口走 Agno/tool calling 选择行政场景；协议回灌 block 和 session 状态推进由 handler 确定性处理，避免模型改写审批状态。

SDK 对外能力

当前 Python / Go SDK 对外都应提供两个 surface：

Surface	import	方向	用途
外部 API Client	Python: `from zhiban_agent_sdk import ZhibanClient`；Go: `zhibansdk.New(...)`	接入方 Agent 服务 / 外部系统 → 知办AI服务器	OAuth 换证、知识库读取/检索，后续按能力域扩展
ZAP Runtime SDK	Python: `from zhiban_agent_sdk import zap`；Go: `gitlab.creditease.corp/aigc/zhiban-agent-sdk-go/zap`	知办AI服务器 → 接入方 Agent Runtime	RuntimeCard、Runtime 内业务入口管理、sessions、SSE events、EMP blocks、errors、session store

zhiban_agent_sdk.zap 当前模块：

模块	提供能力
`zap.runtime`	`ZapRuntime`、入站消息上下文、handler 结果
`zap.fastapi`	快速挂载 `/zap/v1/runtime_card`、`/identity`、`/agents`、`/sessions`；也提供 `require_runtime_bearer(runtime)` 给手写 router 复用
`zap.emp`	`markdown`、`chart`、`table`、`form`、`approval`、`action`、`file`、`progress`、`artifact` 等 block builder
`zap.events`	SSE encoder 与 `message.*` event helper
`zap.errors`	ZAP 错误 envelope 与敏感信息清洗
`zap.session`	`InMemorySessionStore`、TTL、token hash、时间工具

apps/example/agent-example 使用本地 SQLite 演示接入方系统自己的租户/用户体系:它保存本地 tenants/users/link 表,并通过 /instances 完成本地用户和本地 Agent 实例初始化,返回标准 runtime_identity。这是给自建多租户 Agent Runtime 团队看的参考实现,不是知办AI主库的一部分。

Go SDK 的 ZAP Runtime 使用 Go 原生 net/http 风格，不强依赖 Gin / Echo / Fiber：

runtime := zap.NewRuntime(
    zap.WithRuntimeTokenEnv("ZHIBAN_RUNTIME_API_KEY"),
    zap.WithName("admin-assistant-runtime"),
)
runtime.AddAgent("main", zap.AgentCard{Name: "行政协同助手"})

runtime.OnMessage(func(ctx context.Context, inbound zap.InboundMessage, stream zap.Stream) error {
    log.Printf("zap ctx: tenant=%s account=%s session=%s",
        inbound.Context.TenantUUID,
        inbound.Context.AccountUUID,
        inbound.Context.SessionID,
    )
    return stream.Completed(zap.Markdown("收到，我来处理。"))
})

http.ListenAndServe(":7801", runtime.Handler("/zap/v1"))

使用 runtime.Handler("/zap/v1") 后，SDK 自动暴露 ZAP RuntimeCard、Runtime 内业务入口管理、sessions、messages SSE、cancel、delete 等端点，并负责 bearer 鉴权、session 上下文校验、SSE 编码和错误清洗。业务方不需要手写 /zap/v1/* 协议胶水。

agent-example 已覆盖的场景

apps/example/agent-example 是面向接入方 Agent Runtime 团队的参考实现，内置 4 个端到端行政业务场景：多工具联办、三段采购审批、行政分析报告、行政服务申请表。每个场景的触发话术、流程要点和截图见示例场景。

这些场景不是产品端写死的 mock；它们在 reference runtime 里通过 ZAP sessions、SSE events、EMP blocks 和本地工具/fixture/memory 组合实现，用来验证接入方 Agent Runtime 应该如何接入。

安全注意事项

client_secret 与 runtime_api_key 都是长期凭证，不能进 Git、日志或前端包。
AIGC token、runtime API key、JWT 签名材料等真实凭证只能通过环境变量、K8s Secret、Vault/KMS 或部署平台注入,不能写入 tracked 配置文件。
Session Token 是短期凭证，SDK 默认内存缓存并在过期前续期。
Runtime 服务必须校验 Authorization: Bearer <runtime_api_key>，不允许裸放。
平台级外部 runtime 必须声明并实现多租户隔离；租户级 runtime 也建议按 tenant/account/conversation 做隔离。
外部 runtime 自己的用户映射表必须按 tenant 维度隔离;不要把 user_id、邮箱或手机号当成跨租户全局唯一。
身份初始化和回调日志里不得记录 bearer token、session_token、client_secret 或密码。
生产必须使用 HTTPS；HTTP 只用于本地调试。

行业最佳实践与知办AI适配性

参考	行业做法	知办AI 适配判断	采用方案
Google developer docs 标题指南	用清晰、唯一的标题帮助读者浏览和定位。	适配。当前长页里“接入、API、协议、组件”混在一起，标题层级不够可扫读。	拆成接入指南、服务端 API、协议与组件三类，并在本页保留路径索引。
Microsoft Learn 文档类型	文档按概念、操作、示例、参考分层。	适配。接入方开发者既需要“怎么接入”的步骤，也需要稳定的协议/API reference。	本页只讲操作路径；协议和组件作为 reference 独立成页。
Stripe API Reference 与 Stripe SDKs	Guides、API Reference、SDK 分开，SDK 降低集成样板代码。	适配。知办AI SDK 已同时提供外部 API client 与 ZAP Runtime SDK。	在本页明确 SDK 两个 surface，并把 SDK 可提供能力列出来。
Alibaba Cloud Go SDK	Go SDK 以强类型 client、配置项、凭证与错误处理封装云 API 调用，调用方不直接拼接底层 HTTP 细节。	适配。Go 版知办 SDK 应保留强类型外部 API client，同时用 `net/http` 风格 runtime handler 封装 ZAP 数据面。	Go SDK 采用 `Client` + `zap.Runtime` 两个入口；`zap.Runtime` 自动暴露 `/zap/v1/*`，业务方只注册消息 handler。
OpenAI Agents SDK / handoffs	SDK 负责运行时抽象、工具注册、上下文传递和执行编排，业务方只实现 handler/tool。	适配。ZAP Runtime SDK 应提供标准 handler 入参、会话上下文、工具/Agent 注册口，而不是让每个 Agent 手写协议胶水。	`ZapRuntime` 暴露 `on_message`、`on_agent_message`、`ZapMessageContext`；FastAPI adapter 自动处理 runtime 鉴权、session 和 SSE。
Agno Tools / Agent Tools 与 OpenAI function calling	LLM 应用通过工具调用选择外部动作；工具有清晰名称、参数和说明，应用侧执行并校验结果。	适配。真实用户自然语言不应靠字符串表分流；但表单/审批回灌是结构化协议事件，应由代码确定性处理。	agent-example 的真实行政话术先进入 Agno，模型调用 `start_admin_approval_flow` 等工具选择路径；ZAP handler 只对 `form_response`、`approval_response`、`action_callback` 和 `demo` 回归入口做确定性分支。
LangChain runtime context / tools context 与 Vercel AI SDK tools	工具调用可拿到用户、会话、上下文等运行时信息；工具入参/出参由 SDK 约束。	适配。知办AI需要把 tenant、account、session、conversation 等上下文稳定传给接入方 Agent Runtime。	handler 通过 `ctx.tenant_id`、`ctx.user_id`、`ctx.session_id`、`ctx.conversation_id` 读取上下文，`ctx.to_log_dict()` 仅用于安全日志/调试。
OpenID Connect Core	OIDC `sub` 是 issuer 范围内稳定且不复用的用户主体标识。	适配。租户接 SSO 时,知办AI只把 `provider_subjects.oidc` 和 profile 传给 runtime,不在后台配置“唯一匹配字段”。	runtime 自己决定是否用 `issuer + subject` 绑定本地用户。
SCIM RFC 7643 / RFC 7644	跨系统身份同步通常由接收方保存本地资源 ID,调用方侧 ID 作为外部引用。	适配。接入方 Agent Runtime 不是知办AI主库从库,必须自己维护本地 tenant/user/agent instance。	ZAP identity 接口只推送事实;runtime 返回 `runtime_identity` 和 `mapping_status`。

故障排查

现象	常见原因	排查方向
`/oauth/token` 返回 401	`client_id` / `client_secret` 错误或凭证被撤销	后台检查 Agent SDK 凭证状态，重新生成 secret
服务端 API 返回 403	Session Token scope 不足	在凭证中勾选对应能力后重新换 token
Runtime probe 失败	`/zap/v1/runtime_card` 不通或 Bearer Token 不匹配	用 curl 带 `runtime_api_key` 直接调 runtime
聊天一直处理中	接入方 Agent Runtime 没有流式返回 `message.completed` 或上游 LLM 卡住	看接入方 Agent 服务日志与 SSE 流是否有终止事件
富组件不渲染	block `type` / 字段名不符合 EMP 约定	对照 EMP 组件清单，特别注意图表使用 `chart_kind`

自定义 Agent Runtime 接入 ​

文档分层 ​

术语先统一 ​

端到端接入流程 ​

Step 0 接入前准备 ​

Step 1 后台页面怎么配 ​

1.1 创建 Agent SDK 凭证 ​

1.2 创建智能体托管环境 ​

1.3 创建数字员工 ​

Step 2 接入方 Agent 服务配置 ​

Step 3 接入方 Agent 服务调用知办AI服务器 ​

Step 4 知办AI推对话给接入方 Agent Runtime ​

租户同步什么时候发生 ​

数字员工信息什么时候同步 ​

用户体系怎么关联 ​

Handler 入参与注册口 ​

SDK 对外能力 ​

agent-example 已覆盖的场景 ​

安全注意事项 ​

行业最佳实践与知办AI适配性 ​

故障排查 ​

相关链接 ​

自定义 Agent Runtime 接入

文档分层

术语先统一

端到端接入流程

Step 0 接入前准备

Step 1 后台页面怎么配

1.1 创建 Agent SDK 凭证

1.2 创建智能体托管环境

1.3 创建数字员工

Step 2 接入方 Agent 服务配置

Step 3 接入方 Agent 服务调用知办AI服务器

Step 4 知办AI推对话给接入方 Agent Runtime

租户同步什么时候发生

数字员工信息什么时候同步

用户体系怎么关联

Handler 入参与注册口

SDK 对外能力

agent-example 已覆盖的场景

安全注意事项

行业最佳实践与知办AI适配性

故障排查

相关链接