交互卡片
带按钮和选项的消息卡片:卡片结构、作答与结果、cards 能力和错误,以及规划中和 Agent 运行绑定的审批卡。
交互卡片

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): cards-basic.tsx
"use client";
import type { ChatConversation } from "@openmaxai/chat/host";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function CardsDemo() {
// The demo host provides `cards`: `isOperationAllowed` lets the buttons render and
// `invokeAction` settles the card (the result line comes back as a "card" signal).
const host = useDemoHost();
const { conversations } = useDemoData();
const conversation: ChatConversation = conversations[0];
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversation} />
</div>
</ChatHostProvider>
);
}
演示代码中的 useDemoHost() 是内存宿主,接入真实宿主的写法见概览。
何时使用
- Agent 或集成请用户做决定、给出选项或汇报结果。
- 消息带
card_body/card_preview时,MessageThread自动把它画成卡片,不套气泡,无需挂载组件。 - 卡片由卡片插件
cardRenderer画(一个消息展示插件,默认就装)。它需要宿主提供cards能力;没有时卡片按只读画:正文和结果行照常,按钮和选项不能点。
| 卡底按钮 | 作用 | 宿主方法 |
|---|---|---|
| 业务操作 | 执行产品操作(如「接受方案」),带幂等键 | cards.invokeAction |
| 选项 | 按 action id 回答选择题 | cards.settleChoice(可选) |
| 「创建 Agent」 | 打开你应用的创建 Agent 弹窗 | cards.openCreateAgent(可选) |
规划中,Agent 需要人拍板时发的选择卡或表单卡可以和一次运行绑定,成为审批卡。
卡片结构
type: "CARD" 且带 card_body 的消息会画成卡片:
一条卡片消息
const message = {
id: "m_card",
type: "CARD",
seq: 4,
sender_id: "u_sun",
created_at: "2026-09-20T09:00:00Z",
fallback_text: "[卡片] 计划待确认", // 卡片画不出来时显示这行
card_body: {
schema: "cws.card.v1",
kind: "acme.plan",
mode: "interactive",
title: "计划待确认",
summary: "登录页改版",
blocks: [
{ type: "text", text: "把登录页改成新版,预计两天。", fallback_text: "把登录页改成新版,预计两天。" },
{ type: "fields", items: [{ label: "负责人", value: "Ada", inline: true }] },
],
actions: [
{
id: "a-confirm",
kind: "operation",
label: "确认",
operation: "acme.plan.confirm",
style: "primary",
confirm: { text: "确认之后就照这个计划做?", label: "确认" },
},
],
},
};
| 字段 | 说明 |
|---|---|
schema |
"cws.card.v1",其他值整张卡片退回 fallback_text。"cws.card.preview.v1" 是裁剪预览:没有操作按钮,显示「展开」。 |
kind |
你的卡片类型,如 "acme.plan"。 |
mode |
"interactive"(带一个业务操作)或 "display"(默认)。 |
title、summary |
卡片标题区。 |
blocks |
内容块,见下文。 |
actions |
按钮,见下文。 |
内容块类型:text(text)、markdown(text)、fields(items: [{ label, value, inline? }])、divider、image(url 或 artifact_id,加 alt)、artifact_list(items: [{ name, meta?, url?, artifact_id? }])以及 quote(text、author?)。每个块都带上 fallback_text:类型不认识或缺必填字段的块会显示它,没有就丢弃该块。
| 按钮 | 写法 | 点击后 |
|---|---|---|
| 业务操作 | kind: "operation"、id、label、operation,可选 style(primary、secondary、danger、success)和 confirm: { text, label? } |
仅 mode: "interactive" 卡片,只取第一个。调用 cards.invokeAction。 |
| 选项 | kind: "ui"、operation: "ui.quick_reply"、id、label、params: { text } |
显示在 display 卡片上。宿主有 cards.submitInteraction 时调用它,否则调用 cards.settleChoice;两者都没有时按钮禁用。 |
| 创建 Agent | kind: "ui"、operation: "ui.open_create_agent" |
调用 cards.openCreateAgent(),没有它时禁用。 |
结果
消息上的 card_state({ action_id, actor_id, result_at, status })会在卡片底部显示一行结果,如「Ada 已确认 · 10:42」。多人同时作答时先答先得,结果行显示是谁答的。
结果不会乐观显示:点击后,由服务端把 card_state 写进消息,再经重新拉取消息或实时信号到达:宿主自己读好卡片字段时交 { kind: "card" },只知道「这张卡有人答了」时交 { kind: "messageChanged", change: "card" },组件按 id 取那一条。其他设备上、别人的结果也这样到达。card_superseded、card_expired 分别显示「已被取代」「已过期」,按钮禁用。
提供 cards 能力
cards.ts
import type { ChatCardsPort } from "@openmaxai/chat/host";
const ALLOWED = new Set(["acme.plan.confirm", "acme.plan.reject"]);
export const cards: ChatCardsPort = {
isOperationAllowed: (operation) => operation !== undefined && ALLOWED.has(operation),
async invokeAction({ conversationId, messageId, actionId, operation, idempotencyKey }) {
const res = await api.cardAction(messageId, actionId, { idempotencyKey });
if (res.ok) return { ok: true };
return {
ok: false,
kind: toCardErrorKind(res.code), // 把你的错误码折成下面的枚举
resetIdempotencyKey: res.code === "IDEMPOTENCY_KEY_REUSED",
};
},
expandBody: (conversationId, messageId) => refetchMessage(conversationId, messageId),
// 可选:
settleChoice: async ({ messageId, actionId, idempotencyKey }) => api.answerChoice(messageId, actionId, idempotencyKey),
openCreateAgent: () => openCreateAgentDialog(),
};
isOperationAllowed是操作名白名单,不在名单里的业务操作没有按钮。- 幂等键由消息区生成,每条消息的每个按钮一个,重试同一次点击时沿用。只有服务端明确说该键属于另一次点击时,才返回
resetIdempotencyKey: true;网络错误、超时等都保留原键:操作可能已执行只是响应丢了,换键会执行两次。 expandBody取回裁剪卡片的完整正文并落到消息上。
错误
失败时返回以下 kind 之一,消息区在卡片里显示对应提示:
idempotency-key-reused、operation-retired、superseded、window-expired、action-invalid、forbidden、business-forbidden、not-found、conflict、precondition、rate-limited、unavailable、unknown。
- 归不了类的用
unknown。 forbidden指此人无权点;business-forbidden指业务规则不允许。提示不同。unavailable的文案不说「操作失败」,因为操作可能已生效。
没有这项能力时

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。
演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): cards-without-capability.tsx
"use client";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";
export default function CardsWithoutCapabilityDemo() {
// No `cards` capability: the card body still renders, the action buttons do not.
const host = useDemoHost({ without: ["cards"] });
const { conversations } = useDemoData();
return (
<ChatHostProvider host={host}>
<div className="flex h-full flex-col bg-background text-foreground">
<MessageThread conversation={conversations[0]} />
</div>
</ChatHostProvider>
);
}
卡片插件不装,卡片由消息区按只读画:正文、结果行、「已被取代」「已过期」照常显示;业务按钮不显示;选项和「创建 Agent」禁用,悬停说明「这里暂不支持作答」;被截断的卡片只提示内容未完整,没有「展开」按钮。点什么都不会发请求,也不会发一条消息代替作答。只读会话里不论有没有 cards,选项都禁用,说明是「当前会话是只读的」。
用 SDK 时,适配器有 cards 就有这项能力:createChatHost 把作答结果写进消息仓库,业务卡放行哪些操作由 createChatHost({ cards: { isOperationAllowed } }) 交进来(不给就一律不放行),每次作答发一个 card.interaction 事件给 onEvent;选择卡的草稿存在宿主的 instanceScope.storage 里(storage: "localStorage" 时刷新后还在)。「创建 Agent」由 createChatHost({ cards: { openCreateAgent } }) 交进来(不给就禁用,建宿主时读一次);给了 onEvent 时,引导卡的曝光与点击以 card.onboarding 事件交出,去重、补业务维度、Analytics 同意之后补报都归你的应用。见 @openmaxai/chat-sdk · ChatSdkCardsOptions。createChatHost 提供哪些能力见已知限制 · 默认宿主。
审批卡
规划中 我们的扩展
第二期。Agent 需要人拍板时,运行以中断结束,同时发一张选择卡或表单卡,作答方式和其他卡片一样(选择卡是 cards.settleChoice)。卡片新增三个可选字段,带上它们的卡片就是审批卡,对应 AG-UI 的 Interrupt。用卡片承载中断、卡片上的这三个字段和多人先答先得都是我们的扩展:AG-UI 1.0 的中断随 RUN_FINISHED 交给发起运行的客户端,由它用 RunAgentInput.resume 续跑。
| 卡片字段 | 对应 AG-UI | 说明 |
|---|---|---|
run_id |
所在运行的 runId |
卡片属于哪次运行;运行进度的「等待回答」据此跳到卡片 |
tool_call_id |
Interrupt.toolCallId |
卡片在回答哪一次工具调用;答案作为这次工具调用的结果交回 Agent |
expires_at |
Interrupt.expiresAt |
截止时间(ISO 8601)。过了这个时间卡片显示「已过期」,按钮禁用 |
Interrupt 的其余字段:id 是这张卡片消息的 id,message 是卡片上的问题。
- 三个字段都不带的卡片就是普通卡片,不和任何运行关联。
- 多人同时作答时先答先得,结果行显示是谁答的。
- 过期后作答,服务端返回
window-expired,卡片改为「已过期」。 - 宿主既没有
cards.submitInteraction也没有cards.settleChoice时,审批卡的选项同样禁用。
后端怎么处理作答见接入自有后端。
工具权限请求。 Agent 调用某些工具前需要授权。这类请求可以发成审批卡(reason 为 tool_call 的中断),让 Agent 停下来等人回答;做不做由 Agent 的主人按 Agent 配置。打开后,Agent 会停住,直到有人作答或卡片过期。
API
卡片没有 props,由宿主提供 ChatCardsPort:
| 成员 | 类型 | 说明 |
|---|---|---|
invokeAction |
(input: ChatCardActionInput) => Promise<ChatCardActionResult> |
可选。执行业务操作,一次点击调用一次(有 submitInteraction 时不用它) |
settleChoice |
(input: ChatCardChoiceInput) => Promise<ChatCardActionResult> |
可选。按 action id 回答选择题,不发文字 |
submitInteraction |
(input: ChatCardInteractionInput) => Promise<ChatCardActionResult> |
可选。统一提交:选项、选择卡(多题表单)、业务操作按 interactionType 区分。给了它,三类提交都走它 |
refreshCard |
(conversationId: string, messageId: string) => Promise<boolean> |
可选。重读一张卡并落到消息上,返回是否读成功;选择卡提交结果不明时靠它确认 |
formDrafts |
{ get, set, remove }(按卡片消息 id) |
可选。选择卡的本人本设备草稿存取 |
openCreateAgent |
() => void |
可选。「创建 Agent」按钮的唯一效果 |
expandBody |
(conversationId: string, messageId: string) => void |
可选。取回被截断卡片的完整正文;没有时不画「展开」 |
isOperationAllowed |
(operation: string | undefined) => boolean |
该操作能否显示按钮 |
ChatCardChoiceInput 是 { conversationId, messageId, actionId, idempotencyKey };ChatCardActionInput 多一个 operation。ChatCardActionResult 是 { ok: true, cardRefreshed? } 或 { ok: false, kind, resetIdempotencyKey };cardRefreshed: false 表示提交已成功但卡片没能重读回来,选择卡会进入「确认中」再重读。
依赖的能力
| 能力 | 缺了会怎样 |
|---|---|
cards |
卡片插件不装,卡片按只读画:正文和结果行照常,没有业务按钮,选项禁用 |
cards(settleChoice、submitInteraction 都没有) |
选项按钮禁用,说明「这里暂不支持作答」 |
cards(submitInteraction、invokeAction 都没有) |
业务卡不画卡底 |
cards(expandBody) |
被截断的卡片只提示内容未完整,没有「展开」 |
cards(submitInteraction) |
选择卡只读展示,不能作答 |
cards(formDrafts) |
选择卡不存草稿,刷新后已选项不恢复 |
cards(openCreateAgent) |
「创建 Agent」按钮禁用 |
实时推送(inboundDelivery) |
其他设备上的结果要刷新才出现 |
无障碍
卡底按钮是原生按钮,装饰图标带 aria-hidden。操作失败的提示以文字显示在卡片里,不作为实时区域播报。
常见问题
卡片没有按钮。
宿主没有 cards,或 isOperationAllowed 对该操作返回了 false。
点完按钮,结果行没出来。
消息区在等 card_state。重新拉取消息或发 card 信号。
想自己画某种卡片。
写一个消息展示插件认领那类消息。要换掉内置卡片的画法,把自己的插件排在 cardRenderer 前面。
