building-chat-interfaces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Chat Interfaces

构建聊天界面

Build production-grade AI chat interfaces with custom backend integration.

构建支持自定义后端集成的生产级AI聊天界面。

Quick Start

快速开始

bash

undefined

bash

undefined

Backend (Python)

uv add chatkit-sdk agents httpx

Frontend (React)

npm install @openai/chatkit-react

---

npm install @openai/chatkit-react

---

Core Architecture

核心架构

Frontend (React)                    Backend (Python)
┌─────────────────┐                ┌─────────────────┐
│  useChatKit()   │───HTTP/SSE───>│  ChatKitServer  │
│  - custom fetch │                │  - respond()    │
│  - auth headers │                │  - store        │
│  - page context │                │  - agent        │
└─────────────────┘                └─────────────────┘

Frontend (React)                    Backend (Python)
┌─────────────────┐                ┌─────────────────┐
│  useChatKit()   │───HTTP/SSE───>│  ChatKitServer  │
│  - custom fetch │                │  - respond()    │
│  - auth headers │                │  - store        │
│  - page context │                │  - agent        │
└─────────────────┘                └─────────────────┘

Backend Patterns

后端模式

1. ChatKit Server with Custom Agent

1. 自定义Agent的ChatKit Server

python

from chatkit.server import ChatKitServer
from chatkit.agents import stream_agent_response
from agents import Agent, Runner

class CustomChatKitServer(ChatKitServer[RequestContext]):
    """Extend ChatKit server with custom agent."""

    async def respond(
        self,
        thread: ThreadMetadata,
        input_user_message: UserMessageItem | None,
        context: RequestContext,
    ) -> AsyncIterator[ThreadStreamEvent]:
        if not input_user_message:
            return

        # Load conversation history
        previous_items = await self.store.load_thread_items(
            thread.id, after=None, limit=10, order="desc", context=context
        )

        # Build history string for prompt
        history_str = "\n".join([
            f"{item.role}: {item.content}"
            for item in reversed(previous_items.data)
        ])

        # Extract context from metadata
        user_info = context.metadata.get('userInfo', {})
        page_context = context.metadata.get('pageContext', {})

        # Create agent with context in instructions
        agent = Agent(
            name="Assistant",
            tools=[your_search_tool],
            instructions=f"{history_str}\nUser: {user_info.get('name')}\n{system_prompt}",
        )

        # Run agent with streaming
        result = Runner.run_streamed(agent, input_user_message.content)
        async for event in stream_agent_response(context, result):
            yield event

python

from chatkit.server import ChatKitServer
from chatkit.agents import stream_agent_response
from agents import Agent, Runner

class CustomChatKitServer(ChatKitServer[RequestContext]):
    """Extend ChatKit server with custom agent."""

    async def respond(
        self,
        thread: ThreadMetadata,
        input_user_message: UserMessageItem | None,
        context: RequestContext,
    ) -> AsyncIterator[ThreadStreamEvent]:
        if not input_user_message:
            return

        # Load conversation history
        previous_items = await self.store.load_thread_items(
            thread.id, after=None, limit=10, order="desc", context=context
        )

        # Build history string for prompt
        history_str = "\n".join([
            f"{item.role}: {item.content}"
            for item in reversed(previous_items.data)
        ])

        # Extract context from metadata
        user_info = context.metadata.get('userInfo', {})
        page_context = context.metadata.get('pageContext', {})

        # Create agent with context in instructions
        agent = Agent(
            name="Assistant",
            tools=[your_search_tool],
            instructions=f"{history_str}\nUser: {user_info.get('name')}\n{system_prompt}",
        )

        # Run agent with streaming
        result = Runner.run_streamed(agent, input_user_message.content)
        async for event in stream_agent_response(context, result):
            yield event

2. Database Persistence

2. 数据库持久化

python

from sqlmodel.ext.asyncio.session import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine

DATABASE_URL = os.getenv("DATABASE_URL").replace("postgresql://", "postgresql+asyncpg://")
engine = create_async_engine(DATABASE_URL, pool_pre_ping=True)

python

from sqlmodel.ext.asyncio.session import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine

DATABASE_URL = os.getenv("DATABASE_URL").replace("postgresql://", "postgresql+asyncpg://")
engine = create_async_engine(DATABASE_URL, pool_pre_ping=True)

Pre-warm connections on startup

async def warmup_pool(): async with engine.begin() as conn: await conn.execute(text("SELECT 1"))

undefined

async def warmup_pool(): async with engine.begin() as conn: await conn.execute(text("SELECT 1"))

undefined

3. JWT/JWKS Authentication

3. JWT/JWKS身份验证

python

from jose import jwt
import httpx

async def get_current_user(authorization: str = Header()):
    token = authorization.replace("Bearer ", "")
    async with httpx.AsyncClient() as client:
        jwks = (await client.get(JWKS_URL)).json()
    payload = jwt.decode(token, jwks, algorithms=["RS256"])
    return payload

python

from jose import jwt
import httpx

async def get_current_user(authorization: str = Header()):
    token = authorization.replace("Bearer ", "")
    async with httpx.AsyncClient() as client:
        jwks = (await client.get(JWKS_URL)).json()
    payload = jwt.decode(token, jwks, algorithms=["RS256"])
    return payload

Frontend Patterns

前端模式

1. Custom Fetch Interceptor

1. 自定义Fetch拦截器

typescript

const { control, sendUserMessage } = useChatKit({
  api: {
    url: `${backendUrl}/chatkit`,
    domainKey: domainKey,

    // Custom fetch to inject auth and context
    fetch: async (url: string, options: RequestInit) => {
      if (!isLoggedIn) {
        throw new Error('User must be logged in');
      }

      const pageContext = getPageContext();
      const userInfo = { id: userId, name: user.name };

      // Inject metadata into request body
      let modifiedOptions = { ...options };
      if (modifiedOptions.body && typeof modifiedOptions.body === 'string') {
        const parsed = JSON.parse(modifiedOptions.body);
        if (parsed.params?.input) {
          parsed.params.input.metadata = {
            userId, userInfo, pageContext,
            ...parsed.params.input.metadata,
          };
          modifiedOptions.body = JSON.stringify(parsed);
        }
      }

      return fetch(url, {
        ...modifiedOptions,
        headers: {
          ...modifiedOptions.headers,
          'X-User-ID': userId,
          'Content-Type': 'application/json',
        },
      });
    },
  },
});

typescript

const { control, sendUserMessage } = useChatKit({
  api: {
    url: `${backendUrl}/chatkit`,
    domainKey: domainKey,

    // Custom fetch to inject auth and context
    fetch: async (url: string, options: RequestInit) => {
      if (!isLoggedIn) {
        throw new Error('User must be logged in');
      }

      const pageContext = getPageContext();
      const userInfo = { id: userId, name: user.name };

      // Inject metadata into request body
      let modifiedOptions = { ...options };
      if (modifiedOptions.body && typeof modifiedOptions.body === 'string') {
        const parsed = JSON.parse(modifiedOptions.body);
        if (parsed.params?.input) {
          parsed.params.input.metadata = {
            userId, userInfo, pageContext,
            ...parsed.params.input.metadata,
          };
          modifiedOptions.body = JSON.stringify(parsed);
        }
      }

      return fetch(url, {
        ...modifiedOptions,
        headers: {
          ...modifiedOptions.headers,
          'X-User-ID': userId,
          'Content-Type': 'application/json',
        },
      });
    },
  },
});

2. Page Context Extraction

2. 页面上下文提取

typescript

const getPageContext = useCallback(() => {
  if (typeof window === 'undefined') return null;

  const metaDescription = document.querySelector('meta[name="description"]')
    ?.getAttribute('content') || '';

  const mainContent = document.querySelector('article') ||
                     document.querySelector('main') ||
                     document.body;

  const headings = Array.from(mainContent.querySelectorAll('h1, h2, h3'))
    .slice(0, 5)
    .map(h => h.textContent?.trim())
    .filter(Boolean)
    .join(', ');

  return {
    url: window.location.href,
    title: document.title,
    path: window.location.pathname,
    description: metaDescription,
    headings: headings,
  };
}, []);

typescript

const getPageContext = useCallback(() => {
  if (typeof window === 'undefined') return null;

  const metaDescription = document.querySelector('meta[name="description"]')
    ?.getAttribute('content') || '';

  const mainContent = document.querySelector('article') ||
                     document.querySelector('main') ||
                     document.body;

  const headings = Array.from(mainContent.querySelectorAll('h1, h2, h3'))
    .slice(0, 5)
    .map(h => h.textContent?.trim())
    .filter(Boolean)
    .join(', ');

  return {
    url: window.location.href,
    title: document.title,
    path: window.location.pathname,
    description: metaDescription,
    headings: headings,
  };
}, []);

3. Script Loading Detection

3. 脚本加载检测

typescript

const [scriptStatus, setScriptStatus] = useState<'pending' | 'ready' | 'error'>(
  isBrowser && window.customElements?.get('openai-chatkit') ? 'ready' : 'pending'
);

useEffect(() => {
  if (!isBrowser || scriptStatus !== 'pending') return;

  if (window.customElements?.get('openai-chatkit')) {
    setScriptStatus('ready');
    return;
  }

  customElements.whenDefined('openai-chatkit').then(() => {
    setScriptStatus('ready');
  });
}, []);

// Only render when ready
{isOpen && scriptStatus === 'ready' && <ChatKit control={control} />}

typescript

const [scriptStatus, setScriptStatus] = useState<'pending' | 'ready' | 'error'>(
  isBrowser && window.customElements?.get('openai-chatkit') ? 'ready' : 'pending'
);

useEffect(() => {
  if (!isBrowser || scriptStatus !== 'pending') return;

  if (window.customElements?.get('openai-chatkit')) {
    setScriptStatus('ready');
    return;
  }

  customElements.whenDefined('openai-chatkit').then(() => {
    setScriptStatus('ready');
  });
}, []);

// Only render when ready
{isOpen && scriptStatus === 'ready' && <ChatKit control={control} />}

Next.js Integration

Next.js集成

httpOnly Cookie Proxy

httpOnly Cookie代理

When auth tokens are in httpOnly cookies (can't be read by JavaScript):

typescript

// app/api/chatkit/route.ts
import { NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const idToken = cookieStore.get("auth_token")?.value;

  if (!idToken) {
    return NextResponse.json({ error: "Not authenticated" }, { status: 401 });
  }

  const response = await fetch(`${API_BASE}/chatkit`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${idToken}`,
      "Content-Type": "application/json",
    },
    body: await request.text(),
  });

  // Handle SSE streaming
  if (response.headers.get("content-type")?.includes("text/event-stream")) {
    return new Response(response.body, {
      status: response.status,
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache",
      },
    });
  }

  return NextResponse.json(await response.json(), { status: response.status });
}

当身份验证令牌存储在httpOnly Cookie中（无法通过JavaScript读取）时：

typescript

// app/api/chatkit/route.ts
import { NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";

export async function POST(request: NextRequest) {
  const cookieStore = await cookies();
  const idToken = cookieStore.get("auth_token")?.value;

  if (!idToken) {
    return NextResponse.json({ error: "Not authenticated" }, { status: 401 });
  }

  const response = await fetch(`${API_BASE}/chatkit`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${idToken}`,
      "Content-Type": "application/json",
    },
    body: await request.text(),
  });

  // Handle SSE streaming
  if (response.headers.get("content-type")?.includes("text/event-stream")) {
    return new Response(response.body, {
      status: response.status,
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache",
      },
    });
  }

  return NextResponse.json(await response.json(), { status: response.status });
}

Script Loading Strategy

脚本加载策略

tsx

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* MUST be beforeInteractive for web components */}
        <Script
          src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

tsx

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* MUST be beforeInteractive for web components */}
        <Script
          src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

MCP Tool Authentication

MCP工具身份验证

MCP protocol doesn't forward auth headers. Pass credentials via system prompt:

python

SYSTEM_PROMPT = """You are Assistant.

MCP协议不会转发身份验证头。通过系统提示传递凭据：

python

SYSTEM_PROMPT = """You are Assistant.

Authentication Context

User ID: {user_id}
Access Token: {access_token}

CRITICAL: When calling ANY MCP tool, include:

user_id: "{user_id}"
access_token: "{access_token}" """

User ID: {user_id}
Access Token: {access_token}

CRITICAL: When calling ANY MCP tool, include:

user_id: "{user_id}"
access_token: "{access_token}" """

Format with credentials

instructions = SYSTEM_PROMPT.format( user_id=context.user_id, access_token=context.metadata.get("access_token", ""), )

---

instructions = SYSTEM_PROMPT.format( user_id=context.user_id, access_token=context.metadata.get("access_token", ""), )

---

Common Pitfalls

常见陷阱

Issue	Symptom	Fix
History not in prompt	Agent doesn't remember conversation	Include history as string in system prompt
Context not transmitted	Agent missing user/page info	Add to request metadata, extract in backend
Script not loaded	Component fails to render	Detect script loading, wait before rendering
Auth headers missing	Backend rejects requests	Use custom fetch interceptor
httpOnly cookies	Can't read token from JS	Create server-side API route proxy
First request slow	7+ second delay	Pre-warm database connection pool

问题	症状	解决方法
对话历史未加入提示词	Agent无法记住对话内容	将对话历史以字符串形式加入系统提示词
上下文未传递	Agent缺少用户/页面信息	添加到请求元数据中，在后端提取
脚本未加载	组件渲染失败	检测脚本加载状态，等待加载完成后再渲染
身份验证头缺失	后端拒绝请求	使用自定义Fetch拦截器
httpOnly Cookie问题	无法通过JS读取令牌	创建服务端API路由代理
首次请求缓慢	延迟超过7秒	预预热数据库连接池

Verification

验证

Run:

python3 scripts/verify.py

Expected:

✓ building-chat-interfaces skill ready

运行：

python3 scripts/verify.py

预期结果：

✓ building-chat-interfaces skill ready

If Verification Fails

验证失败时的处理

Check: references/ folder has chatkit-integration-patterns.md
Stop and report if still failing

检查：references/文件夹中是否存在chatkit-integration-patterns.md
如果仍失败，请停止操作并上报

Related Skills (Tiered System)

References

参考资料

references/chatkit-integration-patterns.md - Complete patterns with evidence
references/nextjs-httponly-proxy.md - Next.js cookie proxy patterns

references/chatkit-integration-patterns.md - 包含验证依据的完整模式文档
references/nextjs-httponly-proxy.md - Next.js Cookie代理模式

building-chat-interfaces

Original

Translation

Building Chat Interfaces

构建聊天界面

Quick Start

快速开始

Backend (Python)

Backend (Python)

Frontend (React)

Frontend (React)

Core Architecture

核心架构

Backend Patterns

后端模式

1. ChatKit Server with Custom Agent

1. 自定义Agent的ChatKit Server

2. Database Persistence

2. 数据库持久化

Pre-warm connections on startup

Pre-warm connections on startup

3. JWT/JWKS Authentication

3. JWT/JWKS身份验证

Frontend Patterns

前端模式

1. Custom Fetch Interceptor

1. 自定义Fetch拦截器

2. Page Context Extraction

2. 页面上下文提取

3. Script Loading Detection

3. 脚本加载检测

Next.js Integration

Next.js集成

httpOnly Cookie Proxy

httpOnly Cookie代理

Script Loading Strategy

脚本加载策略

MCP Tool Authentication

MCP工具身份验证

Authentication Context

Authentication Context

Format with credentials

Format with credentials

Common Pitfalls

常见陷阱

Verification

验证

If Verification Fails

验证失败时的处理

Related Skills (Tiered System)

相关技能（分层体系）

References

参考资料