chatkit-integration_skill

Overview

This skill provides a foundation for integrating the OpenAI ChatKit framework with custom backends and agents. It guides server implementation, React component integration, authentication handling, context injection, and database persistence to get chat working end-to-end. Use this for initial ChatKit setup; advanced streaming and action patterns are handled by related skills.

How this skill works

On the server side, extend the ChatKitServer and override respond() to wire your agent, load recent thread items, build a history string, inject user and page context, and run the agent (optionally streaming results). On the frontend, configure useChatKit with a custom fetch interceptor that injects auth headers and metadata, detect and wait for the ChatKit script to load, and extract page context from the DOM to include in each request. Persist threads and items in your database, scoped by user via a RequestContext.

When to use it

• Bootstrapping ChatKit with a custom agent framework (OpenAI Agents SDK, LangChain, or custom)
• You need server-side context injection and secure authentication (httpOnly cookies, JWT proxy)
• Building a React/Next.js frontend that must load an external ChatKit web component
• Persisting conversations per-user with multi-tenant isolation and retention policies
• When you want a stable foundation before adding streaming UI or interactive widgets

Best practices

• Extend ChatKitServer and only override respond() for agent logic; keep protocol handling in the base class
• Inject conversation history, user info, and page context into the system prompt to ensure the agent has full context
• Scope all operations by user_id in RequestContext to prevent data leaks between users
• Provide a custom fetch in useChatKit to add auth headers (X-User-ID) and metadata on every relevant request
• Warm up database connections on startup and handle failures gracefully so core chat remains available

Example use cases

• Integrate ChatKit with an OpenAI Agents SDK agent that uses a RAG search tool for domain answers
• Next.js app that proxies httpOnly cookie tokens via a server API route and forwards Authorization to ChatKit backend
• Single-page app that extracts page title, headings, and selected text to enrich agent prompts
• Multi-tenant SaaS that persists conversations in PostgreSQL and applies per-organization retention policies
• Documentation site that waits for the ChatKit web component to load before rendering the chat widget