Back to Details

setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

assistant-ui Setup

assistant-ui 安装设置

Always consult assistant-ui.com/llms.txt for latest API.
请始终参考assistant-ui.com/llms.txt获取最新API。

References

参考资料

  • ./references/ai-sdk.md -- AI SDK v6 setup (recommended)
  • ./references/langgraph.md -- LangGraph agent setup
  • ./references/custom-backend.md -- useLocalRuntime / useExternalStoreRuntime
  • ./references/ag-ui.md -- AG-UI protocol
  • ./references/a2a.md -- A2A protocol
  • ./references/styling.md -- Styling options
  • ./references/tanstack.md -- TanStack Router
  • ./references/ai-sdk.md -- AI SDK v6 安装设置（推荐）
  • ./references/langgraph.md -- LangGraph Agent 安装设置
  • ./references/custom-backend.md -- useLocalRuntime / useExternalStoreRuntime 配置
  • ./references/ag-ui.md -- AG-UI 协议
  • ./references/a2a.md -- A2A 协议
  • ./references/styling.md -- 样式设置选项
  • ./references/tanstack.md -- TanStack 路由

Pick Your Setup

选择你的安装方案

Using Vercel AI SDK?
├─ Yes → useChatRuntime (recommended)
└─ No
   ├─ LangGraph agents? → useLangGraphRuntime
   ├─ AG-UI protocol? → useAgUiRuntime
   ├─ A2A protocol? → useA2ARuntime
   ├─ External state (Redux/Zustand)? → useExternalStoreRuntime
   └─ Custom API → useLocalRuntime
是否使用Vercel AI SDK?
├─ 是 → 使用useChatRuntime（推荐）
└─ 否
   ├─ 使用LangGraph Agent? → useLangGraphRuntime
   ├─ 使用AG-UI协议? → useAgUiRuntime
   ├─ 使用A2A协议? → useA2ARuntime
   ├─ 使用外部状态管理（Redux/Zustand）? → useExternalStoreRuntime
   └─ 自定义API → useLocalRuntime

Quick Start (AI SDK)

快速开始（AI SDK）

bash
npm install @assistant-ui/react @assistant-ui/react-ai-sdk @ai-sdk/react ai @ai-sdk/openai
tsx
// app/page.tsx
"use client";
import { AssistantRuntimeProvider, Thread } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";

export default function Chat() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}
ts
// app/api/chat/route.ts
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({ model: openai("gpt-4o"), messages });
  return result.toUIMessageStreamResponse();
}
bash
npm install @assistant-ui/react @assistant-ui/react-ai-sdk @ai-sdk/react ai @ai-sdk/openai
tsx
// app/page.tsx
"use client";
import { AssistantRuntimeProvider, Thread } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";

export default function Chat() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}
ts
// app/api/chat/route.ts
import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({ model: openai("gpt-4o"), messages });
  return result.toUIMessageStreamResponse();
}

Styling

样式设置

tsx
// Option 1: Pre-built CSS
import "@assistant-ui/styles/default.css";

// Option 2: Tailwind (add to tailwind.config.js)
content: ["./node_modules/@assistant-ui/react/dist/**/*.js"]
tsx
// 选项1：预构建CSS
import "@assistant-ui/styles/default.css";

// 选项2：Tailwind（添加到tailwind.config.js）
content: ["./node_modules/@assistant-ui/react/dist/**/*.js"]

Environment Variables

环境变量

env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
NEXT_PUBLIC_ASSISTANT_BASE_URL=https://api.assistant-ui.com  # For cloud
env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
NEXT_PUBLIC_ASSISTANT_BASE_URL=https://api.assistant-ui.com  # 用于云端服务

Common Gotchas

常见问题

"Cannot find module @ai-sdk/react"
bash
npm install @ai-sdk/react
Styles not applied
  • Import CSS at root level or configure Tailwind content paths
Streaming not working
  • Use 
    toUIMessageStreamResponse()
    in API route
  • Check for CORS errors in console
"runtime is undefined"
  • Call 
    useChatRuntime
    inside a component, not at module level
"无法找到模块@ai-sdk/react"
bash
npm install @ai-sdk/react
样式未生效
  • 在根目录导入CSS或配置Tailwind内容路径
流式传输不工作
  • 在API路由中使用
    toUIMessageStreamResponse()
  • 检查控制台中的CORS错误
"runtime未定义"
  • 在组件内部调用
    useChatRuntime
    ，不要在模块级别调用