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

↳ CHATKIT / 面向 Agent 应用的 React SDK

# 为你的 Agent，
构建完整的
对话界面。

连接已有后端，呈现流式回答、思考与工具执行，管理多会话，并把业务能力融入对话。

[开始接入 ↗](/guide/quick-start.html)[浏览示例](/demos.html)

`pnpm add @volcengine/chatkit`复制文档与示例基于当前本地源码 · React 18 / 19

** LIVE PREVIEW **本地 Mock**↻ 重播演示

01 基础对话02 工具执行03 业务卡片

### 真实 ChatKit · 本地 Mock 回放

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

#### src/demos/hero-demo.tsx


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

import { Chatkit, type ChatkitDataPartRenderer, useChatRuntime } from '@volcengine/chatkit';
import { useEffect, useMemo, useRef, useState } from 'react';

import { createHeroAdapter } from './hero-adapter';
const Card: ChatkitDataPartRenderer = ({ data }) => {
  const order = data as { item: string; amount: string; status: string };
  return (
    <article className="demo-card">
      <header>
        订单详情<span className="demo-badge">{order.status}</span>
      </header>
      <p>{order.item}</p>
      <strong>{order.amount}</strong>
    </article>
  );
};
export default function HeroDemo() {
  const scene = new URLSearchParams(location.search).get('scene') ?? 'tool-flow';
  const [streamState, setStreamState] = useState('准备演示');
  const adapter = useMemo(() => createHeroAdapter(scene), [scene]);
  const runtime = useChatRuntime({ sessionId: `hero-${scene}`, adapter });
  const started = useRef(false);
  useEffect(() => {
    if (runtime && !started.current) {
      started.current = true;
      void runtime.actions.send({
        content: [
          {
            type: 'text',
            text:
              scene === 'custom-card'
                ? '帮我买两台云服务器'
                : scene === 'first-chat'
                ? 'ChatKit 能帮我构建什么？'
                : '查询订单进度并整理配送信息',
          },
        ],
        attachments: [],
      });
    }
  }, [runtime, scene]);
  return runtime ? (
    <div className="demo-column" data-stream-state={streamState}>
      <div className="demo-stream-status" role="status">
        <span data-active={streamState === '正在流式输出'} />
        {streamState}
        <small>真实增量事件 · Mock</small>
      </div>
      <div className="demo-main">
        <Chatkit
          runtime={runtime}
          onEvent={event => {
            if (event.name === 'run_started') setStreamState('正在流式输出');
            if (event.name === 'run_settled')
              setStreamState(event.payload.status === 'completed' ? '本轮已完成' : '本轮已停止');
          }}
          settings={{ toolFlow: scene === 'first-chat' ? 'none' : 'group', tools: { groupDefaultExpanded: true } }}
          renderers={{
            parts: { 'acme.order-card': Card },
            tools: {
              report_heartbeat: { hidden: true },
              query_order: { runningLabel: '正在查询订单', successLabel: '已查询订单' },
              web_search: { runningLabel: '查询配送信息', successLabel: '已获得配送信息' },
            },
          }}
        />
      </div>
    </div>
  ) : null;
}

````

#### src/demos/hero-adapter.ts


````
// Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
// SPDX-License-Identifier: MIT
import { createMockAdapter } from '@volcengine/chatkit/adapters/mock';
import {
  buildAcceptedChatInput,
  type ChatInput,
  type ChatRuntimeAdapter,
  type RuntimeIngress,
} from '@volcengine/chatkit/core';

/** A short local stream for the landing page; other scenes use the built-in Mock scripts. */
export function createHeroAdapter(scene: string): ChatRuntimeAdapter<ChatInput> {
  if (scene !== 'first-chat')
    return createMockAdapter({
      pace: 2.5,
      getScenarioId: () => (scene === 'custom-card' ? 'custom-data' : 'product-tools'),
    });
  let ingress: RuntimeIngress | undefined;
  return {
    start(next) {
      ingress = next;
      return () => {
        if (ingress === next) ingress = undefined;
      };
    },
    projectAcceptedInput: ({ runId, input }) => (input ? [buildAcceptedChatInput(runId, input)] : []),
    abort: async ({ sessionId, runId }) => {
      await ingress?.emitInterrupted({ sessionId, runId, eventId: `${runId}:stop`, reason: 'protocol' });
      return true;
    },
    run: async ({ sessionId, runId, input }, context) => {
      const output = ingress;
      if (!output) return false;
      const meta = { sessionId, runId };
      await output.emitMessage({ ...meta, eventId: `${runId}:input`, message: buildAcceptedChatInput(runId, input) });
      const messageId = `answer:${runId}`;
      await output.emitMessage({
        ...meta,
        eventId: `${runId}:answer`,
        message: { id: messageId, runId, role: 'assistant', parts: [{ id: 'text', type: 'text', text: '' }] },
      });
      const text =
        'ChatKit 把你的 Agent，变成用户能直接使用的对话体验。\n\n你正在看到的回答由**真实增量事件**逐段送入运行时，再由 ChatKit 显示。\n\n- **连接后端**：选择已有适配器，或接入自己的协议。\n- **呈现过程**：流式正文、思考与工具执行，组织在同一个界面。\n- **融入业务**：加入附件、知识库、业务卡片和回答操作。\n\n切换上方场景，继续体验工具执行和业务卡片。';
      for (let i = 0; i < text.length; i += 3) {
        await new Promise(resolve => setTimeout(resolve, 65));
        if (context.signal.aborted) return false;
        await output.emitDelta({
          ...meta,
          eventId: `${runId}:${i}`,
          messageId,
          partId: 'text',
          delta: text.slice(i, i + 3),
        });
      }
      await output.emitCompleted({ ...meta, eventId: `${runId}:done` });
      return true;
    },
  };
}

````

#### 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/hero-demo';
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-hero-demo",
  "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


````
# hero-demo

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

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

````

思考 → 工具执行 → 流式回答点击重播，观察完整过程 ↗

你的后端，熟悉的接入方式

ADKA2AOpenAIHermesCodexOpenCode

[全部适配器 ↗](/backends/overview.html)

看见能力

## 从一条消息，到一次完整的任务。

先体验效果，再按 SOP 把它接入你的应用。

[MESSAGE / 示意帮我整理一下接入步骤**从一个想法，开始对话。**

连接你的 Agent，让回答逐步呈现。

******01### 流式回答 ↗

让回答逐步呈现，支持 Markdown、代码与丰富内容。

默认展示](/features/streaming.html)[EXECUTION / 示意

✓**理解问题**思考✓**检索相关资料**工具↳**整理结果**回答02### 看见 Agent 的执行 ↗

思考、工具调用、执行状态，组织成清晰的过程。

需要对应事件](/features/reasoning-and-tools.html)[HUMAN IN THE LOOP / 示意**继续之前，需要你的确认。**

允许 Agent 执行这一步操作吗？

批准执行 ↗暂不执行03### 参与追问与审批 ↗

让用户补充信息、确认关键步骤，继续推进任务。

需要后端能力](/features/interactions.html)[CONTEXT / 示意**把上下文，一起带进对话。**

↗ 产品手册.pdf PDF＠ 知识库 CONTEXT04### 自然地输入上下文 ↗

附件、提及、指令与语音，融入同一输入体验。

需要应用配置](/features/attachments.html)[SESSIONS / 示意

** 季度运营分析 当前会话** 产品接入咨询 后台运行** 新的想法…05### 切换任务，继续执行 ↗

多个会话各自运行，切回来查看已收到的内容。

由应用接入](/features/sessions.html)[BUSINESS UI / 示意

云服务器订单 待确认**ecs.g8i.large × 2**业务结果，直接成为操作入口 **↗**06### 让结果成为业务入口 ↗

把结构化数据变成业务卡片、工具结果与操作。

需要渲染配置](/features/artifacts.html)

[浏览完整功能与接入条件 →](/features/overview.html)

理解接入

## 放进你的应用，连接你的 Agent。

应用管理业务，ChatKit 组织对话，后端负责真实执行与持久化。

[APPLICATION**你的应用**页面布局 · 登录与路由 · 业务功能

**↓**](/guide/usage.html)[CHATKIT / 01**ChatKit 界面**消息 · 输入 · 执行流 · 业务内容

**↓**](/features/overview.html)[CHATKIT / 02**会话层**一个适配器实例，每个打开的会话一个运行时

**↓**](/reference/hooks.html)[CHATKIT / 03**Core 运行时**统一状态 · 调度 · 历史与生命周期

**↓**](/guide/concepts.html)[CHATKIT / 04**适配器**将后端协议转换为统一运行事实

**↓**](/backends/overview.html)[BACKEND**你的 Agent 后端**模型与工具执行 · 鉴权 · 会话与历史存储

](/backends/backend-contract.html)

连接后端

## 保留你的后端，选择适合的接入。

可选能力取决于适配器配置与后端支持，界面按有效能力显示。

[Mock↗](/backends/mock.html)[ADK↗](/backends/adk.html)[A2A↗](/backends/a2a.html)[OpenAI 兼容↗](/backends/openai.html)[Hermes↗](/backends/hermes.html)[Hermes Dashboard↗](/backends/hermes-gateway.html)[DSH↗](/backends/dsh.html)[Codex↗](/backends/codex.html)[OpenCode↗](/backends/opencode.html)[自有协议↗](/backends/custom-adapter.html)

你的品牌，你的体验

## 改一次主题，
在整个文档站中体验。

调整 ChatKit 外观，站点与示例同步变化。试好之后，带走真实配置。

[打开主题工作台 ↗](/examples/theme-studio.html)

[`settings`调整已有显示设置 →](/customize/choosing.html)[`features`配置内置功能与入口 →](/customize/choosing.html)[`slots`在固定位置放业务组件 →](/customize/choosing.html)[`renderers`决定业务内容怎样呈现 →](/customize/choosing.html)

[查看 13 类定制场景 SOP →](/customize/overview.html)

开始构建

## 三个步骤，发出第一条消息。

[01### 创建适配器

Mock 无需后端；真实服务按协议选择适配器。

](/backends/overview.html)[02### 连接会话运行时

单会话用 useChatRuntime，多会话用 useChatSessions。

](/guide/usage.html)[03### 渲染 ChatKit

引入样式，提供容器高度，传入运行时。

](/guide/quick-start.html)

### 单会话最小接入

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

#### src/demos/first-chat.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 { createMockAdapter } from '@volcengine/chatkit/adapters/mock';

// 创建一次，保持稳定引用。Mock 仅用于开发与演示。
const adapter = createMockAdapter({ pace: 2 });
export default function FirstChat() {
  const runtime = useChatRuntime({ sessionId: 'first-chat', adapter });
  if (!runtime) return <p>正在打开会话…</p>;
  return (
    <div style={{ height: '100%', minHeight: 440 }}>
      <Chatkit
        runtime={runtime}
        settings={{ welcome: '从第一条消息开始', recommendations: ['帮我查一下接入步骤', '写一份本周周报'] }}
      />
    </div>
  );
}

````

#### 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/first-chat';
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-first-chat",
  "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


````
# first-chat

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

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

````

## 从原型，走向真实业务。

[### 完整应用 ↗

把输入选择、工具执行与业务结果串起来。

](/guide/full-example.html)[### 错误与可观测 ↗

理解恢复边界，接入事件与指标。

](/observability/quick-start.html)[### 上线检查 ↗

核对布局、鉴权、历史与资源管理。

](/guide/go-live.html)