This repository contains a few advanced examples, which serve a complete ChatKit playground that pairs a FastAPI backend with a Vite + React frontend.

The top-level backend and frontend directories provide a basic project template that demonstrates ChatKit UI, widgets, and client tools.

• It runs a custom ChatKit server built with ChatKit Python SDK and OpenAI Agents SDK for Python.
• Available agent tools: get_weather for rendering a widget, switch_theme and record_fact as client tools

The Vite server proxies all /chatkit traffic straight to the local FastAPI service so you can develop the client and server in tandem without extra wiring.

1. Start FastAPI backend API.
2. Configure the frontend's domain key and launch the Vite app.
3. Explore the demo flow.

Each step is detailed below.

From the repository root you can bootstrap the backend in one step:

npm run backend

This command runs uv sync for backend/ and launches Uvicorn on http://127.0.0.1:8000. Make sure uv is installed and OPENAI_API_KEY is exported beforehand.

If you prefer running the backend from inside backend/, follow the manual steps:

cd backend
uv sync
export OPENAI_API_KEY=sk-proj-...
uv run uvicorn app.main:app --reload --port 8000

If you don't have uv, you can do the same with:

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -e .
export OPENAI_API_KEY=sk-proj-...
uvicorn app.main:app --reload

The development API listens on http://127.0.0.1:8000.

From the repository root you can start the frontend directly:

npm run frontend

This script launches Vite on http://127.0.0.1:5170.

To configure and run the frontend manually:

cd frontend
npm install
npm run dev

Optional configuration hooks live in frontend/src/lib/config.ts if you want to tweak API URLs or UI defaults.

To launch both the backend and frontend together from the repository root, you can use npm start. This command also requires uv plus the necessary environment variables (for example OPENAI_API_KEY) to be set beforehand.

The Vite dev server runs at http://127.0.0.1:5170, and this works fine for local development. However, for production deployments:

1. Host the frontend on infrastructure you control behind a managed domain.
2. Register that domain on the domain allowlist page and add it to frontend/vite.config.ts under server.allowedHosts.
3. Set VITE_CHATKIT_API_DOMAIN_KEY to the value returned by the allowlist page.

If you want to verify this remote access during development, temporarily expose the app with a tunnel (e.g. ngrok http 5170 or cloudflared tunnel --url http://localhost:5170) and add that hostname to your domain allowlist before testing.

With the app reachable locally or via a tunnel, open it in the browser and try a few interactions. The sample ChatKit UI ships with three tools that trigger visible actions in the pane:

1. Fact Recording - prompt: My name is Kaz
2. Weather Info - prompt: What's the weather in San Francisco today?
3. Theme Switcher - prompt: Change the theme to dark mode

Under the examples directory, you'll find three more sample apps that ground the starter kit in real-world scenarios:

1. Customer Support: airline customer support workflow.
2. Knowledge Assistant: knowledge-base agent backed by OpenAI's File Search tool.
3. Marketing Assets: marketing creative workflow.

Each example under examples/ includes the helper scripts (npm start, npm run frontend, npm run backend) pre-configured with its dedicated ports, so you can cd into an example and run npm start to boot its backend and frontend together. Please note that when you run npm start, uv must already be installed and all required environment variables should be exported.