OpenAI's reference architecture for chat that actually does things

What it does

This repo is a cookbook of four scenario-driven apps—virtual cat caretaker, airline concierge, newsroom assistant, and metro map planner—built atop OpenAI’s ChatKit SDK. Each pairs a FastAPI backend with a Vite + React frontend to demonstrate patterns for tool calling, widget rendering, and state synchronization between model and UI.

The interesting bit

The demos go beyond the usual “chat with a PDF” toy examples. The metro planner locks map interactions while the agent streams a response; the airline concierge prepends a full customer profile as hidden context before every run; the cat lounge fires client-side effects to sync speech bubbles and stat bars. It’s a field guide to the boring-but-hard part of AI apps: keeping the model’s hallucinations aligned with your actual application state.

Key highlights

• Server tools retrieve live data (itineraries, cat stats, news articles, metro maps) before the model responds
• Client tools let the agent read UI state like selected map nodes, and client effects push mutations back to the frontend mid-stream
• Widgets with actions capture user choices (flight selection, meal preferences, cat names) without round-tripping through the model
• Progress updates stream during long retrievals so the UI doesn’t feel frozen
• End-to-end image attachments and built-in dictation in the customer support demo

Caveats

• The README is thorough on patterns but thin on why you’d pick ChatKit over rolling your own or using a framework like LangChain
• Each example is tightly coupled to OpenAI’s stack; portability to other providers is unclear
• The truncated README cuts off mid-sentence on thread titles, suggesting this is actively evolving

Verdict

Worth studying if you’re building agentic UIs and need to see state management done right. Skip it if you want a drop-in chat component without the architectural opinions.