This repository contains a step-by-step guide for learning advanced integrations with ChatKit. The focus is on building custom self-hosted backends using React/Next.js frontend, FastAPI Python backend, and the OpenAI Agents SDK. You'll build custom agents to replace OpenAI-hosted solutions, with each step adding complexity to both UI and agent features. This is based on OpenAI's official documentation and GitHub repositories.
ChatKit offers two integration approaches:
-
Simple Integration (OpenAI-hosted): OpenAI hosts the backend (agents, scaling, sessions). Focus on frontend UI embed with basic customization. Quick setup (< 1 hour), no server maintenance. Limited control over authentication and data residency.
-
Advanced Integration (Self-hosted): You host the backend (FastAPI server with ChatKit Python SDK). Full control over custom agents, data stores, authentication, and on-premises deployment. More complex setup with development effort for scaling/security. This repository focuses exclusively on the advanced integration approach.
- Node.js/npm for the frontend
- Python/uv for the backend
- OPENAI_API_KEY environment variable
- Clone the repository and run each step's folder independently
Learn: Integration flow and basic architecture.
Create a minimal Next.js frontend with ChatKit JS and a FastAPI backend that implements a basic agent using the OpenAI Agents SDK. Includes InMemory thread persistence, real-time streaming, and environment configuration.
Learn: UI customization and theming.
Implement comprehensive theming with a single customized theme demonstrating color schemes, typography, density settings, and custom start screens. Includes overlay welcome screen and live preview functionality.
Learn: Interactive UI elements and widget rendering.
Implement widgets that the frontend renders within the chat interface. The backend formats and streams widget outputs to create rich, interactive experiences.
Learn: Agent actions and tool integration.
Add tools to the backend agent (such as weather APIs) and handle action workflows. The frontend displays the results of these agent-triggered actions.
Learn: File upload and media processing.
Handle file uploads in the frontend and process them in the backend, including support for vision models and media analysis.
Learn: Conversation persistence and state management.
Implement thread management in the frontend and persistent state storage in the backend for maintaining conversation history.
Learn: Trust and transparency features.
Add metadata and annotations in the backend that the frontend renders to provide transparency about agent reasoning and actions.
The examples/ folder contains complete implementations of different agent types:
customer-support-workflow/- A customer support agent with ticket managementknowledge-assistant-agent/- A knowledge base assistant with document searchmarketing-assets-generator/- An agent that generates marketing content and assets