EMP 组件清单

EMP block 是接入方 Agent Runtime 返回给知办AI的结构化组件。接入方 Agent 服务不需要把图表、表单、审批、文件都拼成 Markdown,而是返回结构化 block,由知办AI客户端按 type 渲染。

截图放置规则

每个组件下方都有独立的截图占位框。截图文件放到 docs/public/openapi/emp-components/,文件名按占位框标注;然后取消占位框上方被注释的图片引用、删除占位框即可。

通用结构

{
  "type": "chart",
  "title": "月度行政费用",
  "chart_kind": "bar",
  "data": [
    { "label": "1月", "value": 12.0 },
    { "label": "2月", "value": 10.6 }
  ]
}

接入方 Agent Runtime 推荐用 SDK builder,避免字段名漂移:

from zhiban_agent_sdk.zap import emp

blocks = [
    emp.markdown("已生成行政运营报告。"),
    emp.chart(kind="bar", title="月度行政费用", data=[
        {"label": "1月", "value": 12.0},
        {"label": "2月", "value": 10.6},
    ]),
]

组件索引

下面的“agent-example 触发方式”是截图专用精确短语:在知办客户端对接 agent-example 的数字员工会话里,用户消息只发这一句话,不要加前后缀。

类别	组件	type	SDK builder	agent-example 触发方式
内容	Markdown	markdown	emp.markdown()	普通 markdown / 文本回复
内容	代码	code	emp.code()	代码块
数据	表格	table	emp.table()	表格组件
数据	图表	chart	emp.chart()	柱状图 / 折线图 / 饼图 / 散点图 / 雷达图 / KPI / 复杂图 fallback
交互	表单	form	emp.form()	表单组件
交互	审批	approval / 表单式审批	emp.approval() / emp.form()	审批 / 三段审批表单
交互	确认	confirm	emp.confirm()	二次确认
交互	操作按钮	action	emp.action()	操作按钮
媒体	图片	image	emp.image()	图片
媒体	文件	file	emp.file()	文件
媒体	音频/视频	audio / video	emp.audio() / emp.video()	音频 / 视频
过程	进度	progress	emp.progress()	进度
过程	计划	plan	emp.plan()	计划
过程	工具调用/推理	message.tool_call / message.reasoning	SSE helper	工具调用 / 推理过程
来源	引用来源	source	emp.source()	来源引用
产物	Artifact	artifact:<kind>	emp.artifact()	Artifact
错误	内联错误	error	emp.error()	内联错误

组件截图

Markdown / 文本

代码

表格

图表

chart_kind 是图表类型的规范字段,不使用 chart_type。

图表	触发话术	截图文件
柱状图	柱状图	chart-bar.png
折线图	折线图	chart-line.png
饼图	饼图	chart-pie.png
散点图	散点图	chart-scatter.png
雷达图	雷达图	chart-radar.png
KPI	KPI	chart-kpi.png
复杂图 fallback	复杂图 fallback	chart-mixed-fallback.png

表单

表单适合补充字段、申请单、入职准备、访客接待等场景。用户提交后,知办AI会把字段作为 form_response 推回接入方 Agent Runtime,见 ZAP 消息协议 · HITL。

form.submit_label 可选,由接入方 Agent Runtime 定义主按钮文案;未提供时客户端使用"提交"。按钮文案只表达动作,不改变 form_response 提交语义。若表单不在 message.awaiting_user 待填写态或缺少会话上下文,客户端会保持字段和按钮不可编辑,并在按钮外展示不可提交原因;不要把"需最新版客户端"一类降级说明写进提交按钮。

审批 / 确认 / 操作

审批可以用 approval block,也可以像 agent-example 的三段审批一样用 form 承载"通过/不通过/原因/下一步"字段。

工具过程 / 推理过程

工具和推理通常作为 SSE 中间帧出现,客户端会在最终答案前展示"思考、调用、结果"的过程。

进度 / 计划

图片 / 文件 / 音视频

image 组件必须提供可加载图片地址。优先字段为 preview_url / previewUrl,兼容 url / src;客户端会在消息气泡内展示缩略图,点击后进入大图预览。图片地址可以是公网 URL,也可以是受保护的 /message-files/{uuid}/preview / /api/agent-bus/v1/message-files/{uuid}/preview;受保护地址由客户端补 API 前缀并携带登录态鉴权。只给 name / mime_type 不给 URL 时,客户端只能展示"暂无图片预览地址"。图片 URL 的实际 Content-Type 必须与 mime_type 一致;例如声明 image/png 时不能返回 image/svg+xml,否则 Flutter 客户端会按图片加载失败处理并展示占位图。

{
  "type": "image",
  "name": "行政看板截图.png",
  "preview_url": "/message-files/img-uuid/preview",
  "mime_type": "image/png"
}

file 组件必须提供可下载地址。优先字段为 download_url / downloadUrl,兼容 url / src;客户端按文件名后缀展示文件类型图标,并提供"下载"动作。文件组件标题区用纸clip图标和"附件"文案,主体卡横向展示文件类型图标、文件名、大小/类型和右侧操作区。pdf / html / htm 会额外提供内嵌"预览"动作;其它 Office 文件保留置灰预览按钮,下载交给系统浏览器或默认应用。

{
  "type": "file",
  "name": "行政运营分析报告.xlsx",
  "download_url": "/message-files/file-uuid/download",
  "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 486400
}

video 组件必须提供客户端可访问、Content-Type 正确、最好支持 Range 请求的 url / src。地址不可达或平台播放器初始化失败时,客户端会 fail-soft 退化为文件卡;这表示下载信息可展示,但不会出现内联播放器。

来源 / 产物 / 错误

字段注意事项

• 图表必须使用 chart_kind,SDK 的 emp.chart(kind=...) 会自动生成正确字段。
• 图表数据应是结构化 data 或 series,不要把 Mermaid 代码块塞进 chart。
• 未注册或旧客户端不支持的 block 必须可读降级,不应让用户看到空白。
• form 字段类型以客户端支持为准;新增字段类型前先更新协议和客户端渲染。
• 文件、图片、音视频 URL 必须走可鉴权或可过期的下载链接,不要泄露长期私有地址。图片使用 preview_url,文件使用 download_url;只给文件名不会产生预览或下载能力。

相关链接

• 自定义 Agent Runtime 接入
• ZAP 消息协议
• 租户服务端 API 总览