OpenAI ChatKit Advanced Samples: four runnable ChatKit demos, and what each one teaches
Starter app to build with OpenAI ChatKit SDK
At a glance
- What is it?
- The repository packages four scenario demos, each a FastAPI backend plus a Vite and React frontend, so you can read working ChatKit integration instead of guessing at it. The value is in the patterns; the cost is that nothing here is a library you install.
- Who is it for?
- Adopt these samples if you are building a ChatKit integration and want to see server tools, client tools, effects, widgets and progress events wired end to end before committing to your own architecture. Skip them if you need a production template with auth, persistence and deployment, because the README describes none of that.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 46 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the ChatKit advanced samples actually give you
This is a collection of four demos, not a framework. The README describes each one as a scenario: Cat Lounge, Customer Support, News Guide, and Metro Map. Every example pairs a FastAPI backend with a Vite and React frontend, implementing a custom backend against the ChatKit Python SDK and connecting it to the ChatKit.js client. The intended reader is an engineer who has decided to build on ChatKit and now needs to see how a real integration is shaped. The README is explicit that these are scenario-driven demos rather than a starter template you fork once. Where the repository directory listing shows .github/, examples/, package.json, agents.md and a LICENSE file, the substance lives entirely under examples/. Four separate demo applications sit side by side, each with its own backend and frontend, and the root package.json exists only to give them shared launch scripts. That structure tells you something about intent. The authors wanted each demo readable on its own terms, not merged into one configurable app with feature flags. If you are evaluating ChatKit itself, that is helpful. If you wanted a single starting point to trim down, you will be copying a directory and deleting more than you keep.
How a ChatKit demo is wired: FastAPI on one side, React on the other
The mechanism is consistent across the four examples. A FastAPI backend hosts the agent and its tools; a Vite and React frontend mounts the ChatKit panel and handles what the server asks the browser to do. The README's feature index is the clearest map of the data flow, and it distinguishes three categories that matter when you design your own integration. First, server tool calls that retrieve application data for inference: Cat Lounge exposes get_cat_status, News Guide exposes a retrieval suite including list_available_tags_and_keywords, get_article_by_id, search_articles_by_tags, search_articles_by_keywords, search_articles_by_exact_text and get_current_page, Metro Map exposes get_map, list_lines, list_stations, get_line_route and get_station. Second, client tool calls that mutate or fetch UI state: Metro Map's get_selected_stations pulls currently selected nodes from the canvas so the agent can reason about client-side state. Third, fire-and-forget client effects: Cat Lounge streams update_cat_status and cat_say, Metro Map streams location_select_mode and add_station, Customer Support streams customer_profile/update so a side panel mirrors itinerary, loyalty and timeline data. That split is the real lesson here. Retrieval belongs on the server, interactive state belongs on the client, and one-way UI sync belongs in effects that the server fires without waiting for an answer. The News Guide adds a fourth idea worth stealing: page awareness. The ChatKit client forwards the currently open article id in an article-id header, and the backend reads that request context so get_current_page can load the full content without asking the user to paste it. Progress reporting is handled similarly, with ProgressUpdateEvent messages streamed while retrieval tools search tags, authors, keywords, exact text or the current page, and Metro Map emitting progress while waiting for get_selected_stations to return. Customer Support takes a different tack for context: it prepends a CUSTOMER_PROFILE snapshot covering itinerary, loyalty and recent timeline before each run, and keeps per-thread state in an AirlineStateManager.
Installing and running your first ChatKit example
The README gives a three-step quickstart: export OPENAI_API_KEY, make sure uv is installed, then launch an example either from the repository root or from the project directory. The root package.json defines one script per demo, and each script installs the example's dependencies before starting it, so a root-level launch is the shortest path. The uv requirement is stated as a prerequisite rather than installed for you, which is worth noting because the root scripts only run npm. For a first run, News Guide is the most instructive because it exercises retrieval tools, progress events and page awareness at once. It listens on port 5172.
Where these samples stop being the right tool
Nothing in the README describes authentication, multi-user isolation, persistence beyond per-thread in-memory state, or deployment. Customer Support keeps its state in an AirlineStateManager scoped per thread, and that is the only state model the README documents. There is no migration story, no database, no session store mentioned. If your product needs conversation history that survives a restart, or needs to serve more than a demo audience, you are writing that layer yourself and the samples will not hint at how. The other limitation is versioning. The repository lists no releases, and the root package.json pins only concurrently and a packageManager field. The ChatKit Python SDK and ChatKit.js versions your examples resolve to depend on whatever the individual example projects declare, and the README does not reproduce those constraints. That means a demo that works today can break when an SDK publishes a change, and you have no changelog in this repository to consult. Archived status is not the issue: the repository is not archived, and the last push was on 2026-08-01. But a recent push is not the same as a compatibility guarantee, and the README makes no such guarantee. Treat these as reference implementations to read, not as dependencies to track.
ChatKit samples compared with building directly on the Responses API
The obvious alternative is skipping ChatKit and calling the OpenAI API yourself, wiring your own streaming, your own tool dispatch and your own UI. The difference is not capability, it is where the plumbing lives. With a direct integration you own the event stream, the tool-call round trip and the client state synchronization, and you can shape each of them to your product. ChatKit, as these samples demonstrate it, defines those seams for you: server tools, client tools, client effects, widgets, progress events and response lifecycle hooks such as onResponseStart and onResponseEnd, which Metro Map uses to lock map interaction while a response streams and unlock it when the stream ends. That last detail is a good illustration of the trade-off. You get a documented place to put canvas-locking behaviour, and you accept ChatKit's notion of when a response begins and ends. If your UI has a different lifecycle model, or if you need to support clients ChatKit.js does not target, the direct route gives you freedom the samples do not. If your application is a chat panel over your own data, and you want the tool and effect vocabulary already decided, ChatKit plus these examples removes a design phase.
Maintenance cost and what the licence leaves open
Maintenance here is mostly a reading cost. The repository has no releases, so there is no upgrade path to follow and no version to pin. You will be tracking the upstream ChatKit Python SDK and ChatKit.js yourself, and when either changes, the examples may no longer reflect current practice even if the code still runs. The LICENSE file exists at the repository root, but the license identifier is reported as NOASSERTION, meaning the repository metadata does not resolve to a recognized SPDX identifier. That is not legal advice and not a claim about what the file contains; it means you should open LICENSE and read it before you copy code into a product, and route anything ambiguous to whoever handles licensing on your team. Copying demo code into a commercial codebase is exactly the situation where that reading matters. Also note that the examples are separate projects with their own dependency trees, so adopting all four means maintaining four sets of frontend dependencies, not one.
What to check before you copy a pattern out of these demos
Start with the example closest to your use case rather than the simplest one. If your agent needs to read application data before answering, News Guide's retrieval tools and its get_current_page header mechanism are the closest match in the repository. If your agent needs to drive a canvas or any interactive surface, Metro Map's split between get_selected_stations on the client and add_station as a server-streamed effect is the pattern to study, along with the onResponseStart and onResponseEnd handlers that prevent state drift mid-stream. If your agent maintains a profile or session record, Customer Support's CUSTOMER_PROFILE snapshot and AirlineStateManager show one way to keep the model grounded in current state. Cat Lounge is the smallest and the best place to read the widget and effect basics, including show_cat_profile and the profile_card widget, before moving to the larger examples. Whichever you pick, read the backend agent file and the frontend ChatKitPanel.tsx side by side. The README's feature index names both files for almost every feature, and the pairing is where the integration actually becomes legible. What none of them will tell you is how to run this in production, because the repository does not attempt that question.
Editorial conclusion
Adopt these samples if you are building a ChatKit integration and want to see server tools, client tools, effects, widgets and progress events wired end to end before committing to your own architecture. Skip them if you need a production template with auth, persistence and deployment, because the README describes none of that. Verify first that each example still launches on your machine with uv and Node installed, since the repository has no releases and no published version numbers to pin against.
Frequently asked questions
What is openai-chatkit-advanced-samples?
It is a collection of scenario-driven ChatKit demos. Each example pairs a FastAPI backend with a Vite and React frontend, implementing a custom backend with the ChatKit Python SDK and wiring it to the ChatKit.js client.
How do I install and run the ChatKit examples?
Export OPENAI_API_KEY, make sure uv is installed, then launch an example from the repository root with a script such as npm run news-guide, or from the project directory with npm install followed by npm run start. Each example serves on its own port, from 5170 through 5173.
Which examples are included in the repository?
Four: Cat Lounge, a virtual cat caretaker; Customer Support, an airline concierge with itinerary and timeline data; News Guide, a newsroom assistant with article search and page-aware responses; and Metro Map, a chat-driven metro planner with a React Flow network.
What is the difference between server tools, client tools and client effects in ChatKit?
Server tools retrieve application data for inference, such as Cat Lounge's get_cat_status or Metro Map's get_map. Client tools fetch or mutate UI state, such as Metro Map's get_selected_stations. Client effects are fire-and-forget, such as Cat Lounge's cat_say or Customer Support's customer_profile/update.
Can I use the ChatKit samples in production?
The README documents no authentication, deployment or persistence layer, and Customer Support keeps state per thread in an AirlineStateManager. Treat the examples as reference implementations to read and adapt rather than a production template.
What licence are the ChatKit samples under?
The repository has a LICENSE file at its root, but the reported license identifier is NOASSERTION, so the metadata does not resolve to a recognized SPDX identifier. Read the LICENSE file directly before reusing any code.
Community notes