OpenMax
免费试用

交互卡片

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

交互卡片

cards-basic demo

演示截图。演示跑在内存里的示例 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 的文案不说「操作失败」,因为操作可能已生效。

没有这项能力时

cards-without-capability demo

演示截图。演示跑在内存里的示例 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 前面。