OpenAI ChatKit Advanced Samples: four FastAPI and React demos for custom ChatKit backends

What the ChatKit advanced samples are, and who they are for

This repository is not a framework. It is a collection of scenario-driven demos, and the README says so directly: each example pairs a FastAPI backend with a Vite + React frontend, implementing a custom backend with the ChatKit Python SDK and wiring it to the ChatKit.js client. The intended reader is a developer who has already decided to embed ChatKit in an application and now needs to see how a custom backend is structured. The four demos cover different shapes of that problem. Cat Lounge is a caretaker for a virtual cat with energy, happiness and cleanliness stats. Customer Support is an airline concierge with itinerary data and timeline syncing. News Guide is a newsroom assistant with article search, @-mentions and page-aware responses. Metro Map is a chat-driven metro planner backed by a React Flow network of lines and stations. If you want a drop-in chat widget, these files are the wrong starting point. If you want to understand how server tools, client tools, client effects and widgets fit together in a real app, the four examples are deliberately varied enough to answer different questions.

How a ChatKit backend and frontend split the work

The architecture in every example is the same two-process shape: a FastAPI backend that owns the agent and its tools, and a Vite + React frontend that owns the ChatKit panel and the application UI. The repository README groups the features by where they execute, and that grouping is the clearest description of the data flow. Server tool calls retrieve application data for inference. In Cat Lounge, the function tool get_cat_status pulls the latest cat stats. In News Guide, the agent calls a suite of retrieval tools (list_available_tags_and_keywords, get_article_by_id, search_articles_by_tags/keywords/exact_text, get_current_page) before responding, then uses show_article_list_widget to present results. Metro Map syncs map data with get_map and exposes list_lines, list_stations, get_line_route and get_station. Customer Support prepends a CUSTOMER_PROFILE snapshot before each run and exposes tools to change seats, cancel trips, add bags, set meals and request assistance against per-thread state held in AirlineStateManager. The reverse direction matters just as much. Client tool calls execute in the browser: Metro Map's get_selected_stations reads the currently selected nodes from the canvas so the agent can use client-side state in its reply. Fire-and-forget client effects let the server push UI changes without waiting: Cat Lounge invokes update_cat_status and cat_say, handled through onEffect in ChatKitPanel.tsx. The split is worth studying because it decides where your own state lives. Anything the model needs to reason over belongs on the server; anything the canvas already knows stays on the client and is fetched on demand.

Installing and running the Cat Lounge example

The README gives two ways to launch each demo: a script from the repository root, or manual steps inside the example directory. Both require an OPENAI_API_KEY environment variable and uv installed on the machine. Start by exporting the key, since the backend reads it at startup rather than from a config file.

export OPENAI_API_KEY

From the repository root, the top-level package.json exposes one script per example. The cat-lounge script installs dependencies inside examples/cat-lounge and then starts it, so you do not need to run npm install yourself.

npm run cat-lounge

The equivalent manual route is to enter the example directory, install, and start. The README lists this form for the project directory.

cd examples/cat-lounge && npm install && npm run start

Either path should bring the app up at http://localhost:5170. Once the page loads, you are talking to the cat caretaker agent, and the get_cat_status tool in examples/cat-lounge/backend/app/cat_agent.py is what feeds the cat's stats into the model. The two client effects, update_cat_status and cat_say, are what move the UI: the first syncs the displayed stats, the second surfaces speech bubbles. Watch for those effects firing as you chat; they are the clearest demonstration in the repository of the server pushing state changes to a React panel without a round trip through the user.

Where the examples stop and your own code has to begin

These are demos, and the repository treats them that way. There are no releases, so there is no version to pin and no changelog to read. The top-level package.json is marked private and its only devDependency is concurrently, which tells you the root project exists to orchestrate the examples rather than to ship anything. The backend code you would copy lives under each example's backend/app directory, and it is written against the specific scenario: Cat Lounge's agent knows about cat stats, Metro Map's agent knows about lines and stations. There is no shared abstraction layer between the four. If you want a common agent base class or a reusable tool registry, you will write it, and the four examples will not agree on a pattern for you to follow. The licence is the other open question. The repository reports NOASSERTION rather than a recognised SPDX identifier, and the README does not explain the terms. Before you lift code into a product, read LICENSE and decide whether its terms work for you; the examples themselves give no guidance. Finally, the README documents the happy path only. It does not describe what happens when the API key is missing, when the backend crashes mid-stream, or how the frontend recovers from a dropped connection. For a reference implementation that is acceptable. For a production base it means you are designing the failure behaviour yourself.

ChatKit samples compared with building directly on the OpenAI API

The obvious alternative is to skip ChatKit and call the OpenAI API from your own backend, streaming responses into a chat UI you control. The difference is what each side owns. With a direct integration, you own the transport, the message format, the tool-call loop and every piece of UI state; nothing is prescribed, and nothing is handled for you. With ChatKit, the SDK defines the conversation protocol and the client library renders it, which is why these examples can express things like widgets and progress updates declaratively. News Guide streams ProgressUpdateEvent messages while its retrieval tools search tags, authors, keywords, exact text or load the current page, and the event finder agent does the same while scanning dates and days of the week. Metro Map emits a progress update while retrieving map information and another while waiting for a client tool call to complete. Reproducing that behaviour on a raw API integration means inventing an event vocabulary and keeping both ends in sync with it. The trade is control for convention. If your chat needs to look and behave exactly as you specify, the direct route avoids fighting a protocol. If you want the protocol solved, ChatKit is the point of these examples.

Maintenance, upgrade cost and the licence question

The repository is not archived, and the last push was on 2026-08-01. There are no releases, so upgrades are a matter of pulling the branch rather than moving between tagged versions. That is a real cost if you fork an example: you get no changelog, no migration notes and no compatibility statement for the ChatKit SDK versions the examples were written against. The packageManager field pins [email protected] with an integrity hash, but the documented commands use npm, so the two toolchains coexist in the same repository and you should expect to pick one deliberately. On licensing, the repository reports NOASSERTION and the README does not restate the terms. Read LICENSE before you copy backend or frontend code into anything you distribute, and treat the absence of an SPDX identifier as a reason to check rather than a reason to assume permissive terms. I am not giving legal advice here; the point is that the repository itself does not answer the question, and the answer changes what you can do with the code.

Editorial conclusion

Adopt this repository if you already have an OpenAI API key and want a working reference for the ChatKit Python SDK and ChatKit.js before writing your own backend. Skip it if you need a supported product or a maintained package: there are no releases, the examples are demos, and the licence text is not a standard SPDX identifier, so check LICENSE before reusing code. Verify first that your environment can run uv and Node, that ports 5170 through 5173 are free, and that you understand one example end to end, starting with cat-lounge because its single get_cat_status tool and two client effects are the smallest complete loop in the repository.

Frequently asked questions

Official sources

1. Issues
2. openai/openai-chatkit-advanced-samples on GitHub
3. Project website
4. README