> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 追问与审批

智能体在执行中停下来问用户（追问），或在执行命令、改文件前请用户放行（审批），chatkit 画默认卡片，用户回答后交给适配器继续。


### 触发追问或审批，答复后继续执行

Mock 演示；业务函数需要替换为真实实现。

#### src/demos/interactions.tsx


````
// Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
// SPDX-License-Identifier: MIT
import '@volcengine/chatkit/styles.css';

import { Chatkit, useChatRuntime } from '@volcengine/chatkit';
import {
  buildAcceptedChatInput,
  type ChatInput,
  type ChatRuntimeAdapter,
  type Interaction,
  type RuntimeIngress,
} from '@volcengine/chatkit/core';
let ingress: RuntimeIngress;
// 本地模拟一个具备 respond 的后端，真实部署按适配器协议产生同形交互。
const adapter: ChatRuntimeAdapter<ChatInput> = {
  start(next) {
    ingress = next;
    return () => {};
  },
  projectAcceptedInput: ({ runId, input }) => (input ? [buildAcceptedChatInput(runId, input)] : []),
  run: async ({ sessionId, runId, input }) => {
    const approval = input.content.some(p => p.type === 'text' && p.text.includes('审批'));
    const interaction: Interaction = approval
      ? {
          kind: 'approval',
          status: 'pending',
          title: '允许读取演示报告？',
          reason: '只读取本地示例，无外部操作。',
          command: 'read quarterly-report',
          decisions: [
            { id: 'allow', label: '允许读取', tone: 'allow' },
            { id: 'deny', label: '拒绝', tone: 'deny' },
          ],
        }
      : {
          kind: 'question',
          status: 'pending',
          questions: [
            {
              id: 'format',
              question: '你希望怎样呈现结果？',
              options: [{ label: '摘要', recommended: true }, { label: '详细说明' }],
              allowOther: true,
            },
          ],
        };
    await ingress.emitMessage({
      sessionId,
      runId,
      eventId: `${runId}:ask`,
      message: {
        id: `assistant:${runId}`,
        runId,
        role: 'assistant',
        parts: [
          {
            id: 'ask',
            type: 'tool-call',
            toolCallId: `ask:${runId}`,
            toolName: 'ask_user',
            args: {},
            metadata: { 'chatkit.interaction': interaction },
          },
        ],
      },
    });
    await ingress.emitCompleted({ sessionId, runId, eventId: `${runId}:done` });
    return true;
  },
  respond: async ({ sessionId, runId, response }) => {
    await ingress.emitMessage({
      sessionId,
      runId,
      eventId: `${runId}:response`,
      message: {
        id: `assistant:${runId}`,
        runId,
        role: 'assistant',
        parts: [{ id: 'result', type: 'text', text: `已收到答复：${JSON.stringify(response)}。演示流程完成。` }],
      },
    });
    await ingress.emitCompleted({ sessionId, runId, eventId: `${runId}:done` });
    return true;
  },
};
export default function Interactions() {
  const runtime = useChatRuntime({ sessionId: 'interactions', adapter });
  return runtime ? (
    <Chatkit runtime={runtime} settings={{ welcome: '参与 Agent 的执行', recommendations: ['触发追问', '触发审批'] }} />
  ) : null;
}

````

#### src/main.css


````
/*
 * Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
 * SPDX-License-Identifier: MIT
 */

/* 示例页只给一个铺满的容器；chatkit 自己渲染 .chatkit-wrapper，接入方不用再包一层。 */
html,
body,
#root {
  height: 100%;
  margin: 0;
}

body {
  color: var(--chatkit-color-text, #0b0b0f);
  font-family: 'PingFang SC', system-ui, -apple-system, 'Microsoft YaHei', sans-serif;
  font-size: 13px;
}

/* 示例的 iframe 不宽，输入框左右留一点边距，不贴着边。 */
.chatkit-composer-wrapper {
  width: calc(100% - 24px);
  margin-bottom: 12px;
}

.demo-missing {
  padding: 24px;
  color: var(--chatkit-color-text-tertiary, #7a7880);
}

/*
 * 下面是示例页面自己的外观（页面布局、示例里的业务按钮和卡片），代表接入方页面上自己的样式，
 * 和 chatkit 无关。示例代码里以 demo- 开头的类名都在这里。
 */

/* 页面布局：上下排、左右排、聊天区占剩下的空间 */
.demo-column {
  display: flex;
  flex-direction: column;
  height: 100%;
}

.demo-row {
  position: relative;
  display: flex;
  flex: 1;
  min-height: 0;
  height: 100%;
}

.demo-main {
  flex: 1;
  min-width: 0;
  min-height: 0;
}

/* 页面顶部的一条：开关、单选、页面自己的头部 */
.demo-bar {
  display: flex;
  flex-wrap: wrap;
  gap: 6px 12px;
  align-items: center;
  padding: 8px 12px;
  background: var(--chatkit-color-bg-subtle, #fafafb);
  border-bottom: 1px solid var(--chatkit-color-border, #e8e8ec);
}

.demo-bar strong {
  margin-right: auto;
  font-size: 14px;
}

.demo-bar label {
  display: inline-flex;
  gap: 4px;
  align-items: center;
  cursor: pointer;
}

/* 页面侧边的一栏：后端收到的内容、事件列表 */
.demo-side {
  box-sizing: border-box;
  flex-shrink: 0;
  width: 190px;
  padding: 12px;
  overflow: auto;
  font-size: 12px;
  line-height: 1.6;
  background: var(--chatkit-color-bg-subtle, #fafafb);
  border-left: 1px solid var(--chatkit-color-border, #e8e8ec);
}

.demo-side h4 {
  margin: 0 0 8px;
  font-size: 12px;
}

.demo-side pre {
  margin: 0 0 8px;
  padding: 8px;
  font-size: 11px;
  font-family: ui-monospace, Menlo, monospace;
  white-space: pre-wrap;
  word-break: break-all;
  background: var(--chatkit-color-bg, #fff);
  border: 1px solid var(--chatkit-color-border, #e8e8ec);
  border-radius: 6px;
}

.demo-muted {
  color: var(--chatkit-color-text-tertiary, #8f959e);
}

/* 抽屉：盖在聊天区上面的会话列表 */
.demo-drawer {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 0;
  z-index: 20;
  box-shadow: 8px 0 24px rgb(0 0 0 / 12%);
}

/* 两个会话示例：宽屏保留左右侧栏，窄屏用按钮展开列表，不挤占聊天区。 */
.demo-session-sidebar {
  flex-shrink: 0;
  width: 200px;
  max-width: 100%;
}

.demo-session-layout[data-placement='right'] .demo-session-sidebar {
  order: 1;
}

.demo-session-layout .demo-session-toggle,
.demo-session-toggle-bar {
  display: none;
}

.demo-session-layout[data-placement='drawer'] .demo-session-toggle {
  display: inline-flex;
}

.demo-session-layout[data-placement='drawer'] .demo-session-sidebar {
  position: absolute;
  inset: 0 auto 0 0;
  z-index: 20;
  display: none;
  box-shadow: 8px 0 24px rgb(0 0 0 / 12%);
}

.demo-session-layout[data-placement='drawer'][data-open='true'] .demo-session-sidebar {
  display: block;
}

@media (width <= 520px) {
  .demo-session-layout .demo-session-placement {
    display: none;
  }

  .demo-session-layout .demo-session-toggle,
  .demo-session-toggle-bar {
    display: flex;
  }

  .demo-session-layout .demo-session-sidebar {
    position: absolute;
    inset: 0 auto 0 0;
    z-index: 20;
    display: none;
    box-shadow: 8px 0 24px rgb(0 0 0 / 12%);
  }

  .demo-session-layout[data-open='true'] .demo-session-sidebar {
    display: block;
  }
}

/* 业务按钮：工具栏、操作栏、顶栏里的小按钮 */
.demo-chip {
  display: inline-flex;
  gap: 4px;
  align-items: center;
  height: 28px;
  padding: 0 10px;
  color: inherit;
  font-size: 12px;
  font-family: inherit;
  white-space: nowrap;
  background: var(--chatkit-color-bg, #fff);
  border: 0.5px solid #b8b7c3;
  border-radius: 14px;
  cursor: pointer;
}

.demo-chip:hover {
  background: var(--chatkit-color-bg-hover, #f2f3f5);
}

.demo-chip[aria-pressed='true'] {
  color: var(--chatkit-color-bg, #fff);
  background: var(--chatkit-color-text, #0b0b0f);
  border-color: var(--chatkit-color-text, #0b0b0f);
}

.demo-chips {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  align-items: center;
  padding: 6px 0;
  font-size: 12px;
}

/* 标出插槽位置的色块 */
.demo-slot {
  display: inline-block;
  box-sizing: border-box;
  padding: 1px 6px;
  color: #ad4e00;
  font-size: 10.5px;
  line-height: 18px;
  white-space: nowrap;
  background: #fff3e0;
  border: 1px dashed #ffab40;
  border-radius: 4px;
}

/* 业务卡片 */
.demo-card {
  box-sizing: border-box;
  max-width: 360px;
  margin: 8px 0;
  padding: 12px 14px;
  font-size: 13px;
  line-height: 1.6;
  background: var(--chatkit-color-bg, #fff);
  border: 0.5px solid #d2d1e0;
  border-radius: 16px;
}

.demo-card header {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  margin-bottom: 4px;
  font-weight: 600;
}

.demo-card footer {
  display: flex;
  gap: 8px;
  margin-top: 8px;
}

.demo-badge {
  padding: 0 8px;
  color: var(--chatkit-color-text-secondary, #3f3f51);
  font-weight: 400;
  font-size: 11px;
  line-height: 20px;
  background: #ebebf5;
  border-radius: 10px;
}

/* 右侧面板里的内容 */
.demo-panel {
  padding: 16px;
  font-size: 13px;
  line-height: 1.7;
}

.demo-panel header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  margin-bottom: 12px;
  font-weight: 600;
  font-size: 15px;
}

/* 菜单：点按钮展开的列表 */
.demo-menu {
  position: relative;
  display: inline-block;
}

.demo-menu ul {
  position: absolute;
  bottom: 34px;
  left: 0;
  z-index: 30;
  min-width: 180px;
  margin: 0;
  padding: 4px;
  list-style: none;
  background: var(--chatkit-color-bg, #fff);
  border: 1px solid #e1e3e8;
  border-radius: 8px;
  box-shadow: 0 8px 24px rgb(0 0 0 / 12%);
}

.demo-menu li button {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  padding: 6px 10px;
  color: inherit;
  font-size: 13px;
  font-family: inherit;
  text-align: left;
  background: none;
  border: 0;
  border-radius: 6px;
  cursor: pointer;
}

.demo-menu li button:hover {
  background: var(--chatkit-color-bg-hover, #f2f3f5);
}

/* 顶栏、公告这类占一整行的内容 */
.demo-line {
  display: flex;
  gap: 8px;
  align-items: center;
  padding: 6px 14px;
  font-size: 12px;
}

.demo-line--notice {
  margin: 0 16px 8px;
  padding: 8px 12px;
  color: var(--chatkit-color-text-secondary, #3f3f51);
  background: var(--chatkit-color-bg-subtle, #f6f6fc);
  border-radius: 8px;
}

/* 完整应用：左边会话列表，中间顶栏加聊天区，右边一栏卡片 */
.demo-app {
  display: flex;
  height: 100%;
  color: var(--chatkit-color-text, #0b0b0f);
  background: var(--chatkit-color-bg, #fff);
}

.demo-app .chatkit-session-list {
  border-right: 1px solid #ececf0;
}

.demo-app-main {
  display: flex;
  flex: 1;
  flex-direction: column;
  min-width: 0;
}

.demo-app-header {
  display: flex;
  flex-shrink: 0;
  gap: 12px;
  align-items: center;
  justify-content: space-between;
  height: 56px;
  padding: 0 24px 0 16px;
  font-size: 12px;
}

.demo-app-header strong {
  overflow: hidden;
  font-weight: 500;
  font-size: 16px;
  white-space: nowrap;
  text-overflow: ellipsis;
}

.demo-app-body {
  display: flex;
  flex: 1;
  min-height: 0;
}

.demo-app-rail {
  display: flex;
  flex-shrink: 0;
  flex-direction: column;
  gap: 12px;
  box-sizing: border-box;
  width: 280px;
  padding: 4px 24px 24px 0;
  overflow: auto;
}

.demo-rail-card {
  display: flex;
  flex-direction: column;
  gap: 2px;
  padding: 8px;
  border: 1px solid #e6e6ea;
  border-radius: 16px;
}

.demo-rail-card h4 {
  margin: 0;
  padding: 8px;
  color: var(--chatkit-color-text-tertiary, #7a7880);
  font-weight: 500;
  font-size: 14px;
  line-height: 22px;
}

.demo-rail-row {
  display: flex;
  gap: 10px;
  align-items: center;
  min-height: 38px;
  padding: 0 8px;
  color: inherit;
  font-size: 13px;
  font-family: inherit;
  line-height: 22px;
  text-align: left;
  background: none;
  border: 0;
  border-radius: 10px;
}

button.demo-rail-row {
  cursor: pointer;
}

button.demo-rail-row:hover {
  background: #f3f3f5;
}

.demo-rail-row span {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}

/* 状态圆点：没开始是虚线圈，进行中转圈，结束是绿色 */
.demo-rail-row i {
  box-sizing: border-box;
  flex-shrink: 0;
  width: 16px;
  height: 16px;
  margin: 0 3px;
  border: 1.5px dashed #b8b7c3;
  border-radius: 50%;
}

.demo-rail-row[data-status='running'] i,
.demo-rail-row[data-status='queued'] i {
  border-color: #e6e6ea;
  border-top-color: var(--chatkit-color-text, #0b0b0f);
  border-style: solid;
  animation: demo-spin 0.9s linear infinite;
}

.demo-rail-row[data-status='completed'] i {
  background: #2db55d;
  border-color: #2db55d;
  border-style: solid;
  box-shadow: inset 0 0 0 3px var(--chatkit-color-bg, #fff);
}

.demo-rail-row[data-status='failed'] i,
.demo-rail-row[data-status='interrupted'] i {
  background: #ec4e6d;
  border-color: #ec4e6d;
  border-style: solid;
  box-shadow: inset 0 0 0 3px var(--chatkit-color-bg, #fff);
}

@keyframes demo-spin {
  to {
    transform: rotate(360deg);
  }
}

/* 会话列表上方的产品名、下方的用户 */
.demo-brand,
.demo-user {
  display: flex;
  gap: 8px;
  align-items: center;
  padding: 4px;
  font-weight: 600;
  font-size: 16px;
}

.demo-user {
  font-weight: 400;
  font-size: 13px;
}

.demo-brand::before,
.demo-user::before {
  width: 20px;
  height: 20px;
  background: var(--chatkit-color-text, #0b0b0f);
  border-radius: 6px;
  content: '';
}

.demo-user::before {
  background: linear-gradient(135deg, #2f79ff, #ec4e6d);
  border-radius: 50%;
}

.demo-legal {
  padding: 6px 0 2px;
  color: #6e718c;
  font-size: 11px;
  line-height: 20px;
  text-align: center;
  opacity: 0.6;
}

/* 窄的时候先收起右边一栏，再收起会话列表 */
@media (width <= 1080px) {
  .demo-app-rail {
    display: none;
  }
}

@media (width <= 760px) {
  .demo-app .chatkit-session-list {
    width: 180px;
  }
}

@media (width <= 520px) {
  .demo-app .chatkit-session-list {
    display: none;
  }
}

.studio-session-picker {
  display: none;
}

@media (width <= 560px) {
  .studio-session-list {
    display: none;
  }

  .studio-session-picker {
    display: block;
    max-width: 140px;
  }
}

/* Demo host status, driven by the runtime's public lifecycle events. */
.demo-stream-status {
  display: flex;
  align-items: center;
  gap: 7px;
  padding: 9px 14px;
  border-bottom: 1px solid var(--chatkit-color-border, #e5e6eb);
  font-size: 10px;
  color: var(--chatkit-color-text-secondary, #6e6e78);
}

.demo-stream-status > span {
  width: 5px;
  height: 5px;
  border-radius: 50%;
  background: currentcolor;
}

.demo-stream-status > span[data-active='true'] {
  animation: demo-live-pulse 1.2s ease-in-out infinite;
}

.demo-stream-status small {
  margin-left: auto;
  font-size: 9px;
}

@keyframes demo-live-pulse {
  50% {
    opacity: 0.25;
  }
}

@media (prefers-reduced-motion: reduce) {
  .demo-stream-status > span[data-active='true'] {
    animation: none;
  }
}

.demo-theme-sample {
  padding: 4px 7px;
  border: 1px solid var(--chatkit-color-border);
  border-radius: var(--chatkit-radius-md);
  background: var(--chatkit-color-bg);
  color: var(--chatkit-color-link);
  font: inherit;
  font-size: 11px;
  white-space: nowrap;
  cursor: pointer;
}

.demo-theme-sample:focus-visible {
  outline: 2px solid var(--chatkit-color-primary);
  outline-offset: 2px;
}

````

#### src/main.tsx


````
import './main.css';
import '@volcengine/chatkit/styles.css';
import { createRoot } from 'react-dom/client';
import Demo from './demos/interactions';
createRoot(document.getElementById('root')!).render(<Demo />);

````

#### index.html


````
<!doctype html><html lang="zh"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><div id="root"></div><script type="module" src="/src/main.tsx"></script></html>
````

#### package.json


````
{
  "name": "chatkit-example-interactions",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.20.0",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build"
  },
  "dependencies": {
    "@volcengine/chatkit": "file:../chatkit.tgz",
    "react": "18.3.1",
    "react-dom": "18.3.1"
  },
  "devDependencies": {
    "vite": "^6.4.1",
    "typescript": "5.9.3",
    "@vitejs/plugin-react": "^4.0.0"
  }
}
````

#### vite.config.ts


````
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({plugins:[react()]});

````

#### README.md


````
# interactions

本示例与本站预览来自同一份本地代码。

1. 下载页面提供的本地 SDK chatkit.tgz，放在本示例目录的上一级。
2. corepack enable；pnpm install；pnpm dev。
3. 开发真实业务时替换 Mock、上传、语音等演示实现。数据不构成真实业务服务。

````

## 接入 SOP

**前提条件：**&#x540E;端需提供交互请求与答复能力；部分连接协议使用自定义卡片。

1. 按协议将问题或审批挂到工具交互信息上。
2. 默认卡片走 respond；Codex 等特定连接按对应适配器页提供卡片和回答方式。
3. 保留 pending、answering、answered 或取消状态，处理发送失败与重复点击。

### 验证结果

使用真实后端触发问题，回答后检查执行继续；拒绝或失败后应进入相应状态。

### 排错入口

Mock 通用对话不能证明审批服务已接通；只读卡片先检查 respond 或连接专用回答函数。

完整文件可从本页示例下载；对应[配置参考](/reference/config.md)与[公开入口](/reference/entry-points.md)用于核对准确签名。

## 什么时候出现

适配器在工具调用片段的 `metadata['chatkit.interaction']` 上挂交互请求，界面按它画卡片：

| 交互请求                      | 默认卡片                                     | 回答           |
| ------------------------- | ---------------------------------------- | ------------ |
| 追问（`kind: 'question'`）    | 问题标题、带编号的选项（推荐项加标记）、自由填写框；单独成块，不收进折叠的执行流 | 点选项或填写后发送    |
| 审批（`kind: 'approval'`）    | 说明、待执行的命令、后端给的决定按钮                       | 点一个决定        |
| 等外部结果（`kind: 'external'`） | 没有默认卡片，照常是一行工具                           | 由接入方自己画、自己回答 |

回答后追问卡片只留下问题本身，回答显示为一条用户消息（顶部引用被回答的问题），之后的回答另起一条。

## 回答怎么发出

卡片调用 `actions.respond(toolCallId, response)`（运行时上是 `runtime.respond({ toolCallId, response })`）：

- 回答作为新的一轮交给适配器的 `respond` 能力函数；有一轮在进行时不受理；
- 交互请求立刻标为回答中（`answering`），新的一轮有了产出后记为已回答（`answered`），没受理时退回等待（`pending`），可以再答；
- 适配器没有 `respond` 时卡片只读，选项不可点。

各适配器从协议里怎么认出交互请求、`respond` 要发什么，见对应的接入页，例如 [ADK · 长时工具与追问](/backends/adk.md#长时工具与追问)。

## 换成自己的卡片

按工具名登记整行接管，默认卡片就不再出现；自己的卡片里用 `getChatkitInteraction` 读请求，用 `useChatkitActions().respond` 回答。也可以直接用导出的 `ChatkitInteractionCard` 包一层：

```tsx
import { ChatkitInteractionCard, getChatkitInteraction, useChatkitActions } from '@volcengine/chatkit';

function AskUser({ toolCallId, metadata }: ChatkitToolViewProps) {
  const { respond } = useChatkitActions();
  const interaction = getChatkitInteraction(metadata);
  if (!interaction) return null;
  return (
    <ChatkitInteractionCard
      interaction={interaction}
      onRespond={respond ? response => respond(toolCallId, response) : undefined}
    />
  );
}

<Chatkit sessions={sessions} renderers={{ tools: { ask_user: { render: AskUser } } }} />;
```