Four ChatKit demos, and the tool call taxonomy they teach
Starter app to build with OpenAI ChatKit SDK
At a glance
- What is it?
- openai-chatkit-advanced-samples is a set of four scenario apps, each a FastAPI backend using the ChatKit Python SDK paired with a Vite and React frontend wired to ChatKit.js, whose real value is a worked taxonomy of three kinds of tool call, server tools for data, client tools for UI state, and fire-and-forget effects that stream UI changes without a reply.
- Who is it for?
- Use it as a reference for the wiring rather than as a product to extend. Each demo is small enough to read end to end, and between them they cover the three things you have to get right when building a ChatKit backend: how the server reaches application data, how the server reads state that only exists in the browser, and how it updates the UI without waiting for the model.
- 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 107 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 November 15, 2026, and from our analysis. They are not legal advice.
Star history
- openai/openai-chatkit-advanced-samples671 ★ · +17
| Repository | 2026-09-15 | 2026-11-15 |
|---|---|---|
| openai/openai-chatkit-advanced-samples | 654 | 671 |
17 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Four apps, four ports, one npm script each
The repository is four independent applications rather than one, and the top level is small enough to see: a package.json, a package-lock.json, a README, an agents.md, a LICENSE, a .github directory and the examples folder.
Each example is a FastAPI backend paired with a Vite and React frontend, with a custom backend built on the ChatKit Python SDK and the browser side wired through ChatKit.js. The four are Cat Lounge, a caretaker for a virtual cat whose energy, happiness and cleanliness stats the agent manages; Customer Support, an airline concierge with live itinerary data; News Guide, a newsroom assistant with article search, mentions and page-aware replies; and Metro Map, a chat-driven metro planner drawing its network with React Flow.
Each gets its own dev server port so you can run more than one at a time: 5170 for Cat Lounge, 5171 for Customer Support, 5172 for News Guide, 5173 for Metro Map. The root package.json exposes one script per app, and each script installs that example's dependencies and starts it.
npm run cat-lounge
cd examples/cat-lounge && npm install && npm run startSetup is two prerequisites: an exported OPENAI_API_KEY and uv on the machine.
package.json names pnpm while every script calls npm
The packaging metadata contradicts the scripts, and it is the kind of contradiction that costs an afternoon.
The packageManager field declares pnpm at a specific version with a content hash, which is the strict form that tells Corepack exactly which build to fetch. Every script in the same file then runs npm, in the shape npm --prefix examples/cat-lounge install followed by npm --prefix examples/cat-lounge start. There is also a package-lock.json in the repository, which is npm's lockfile rather than pnpm's.
So three signals point two ways. A developer with Corepack enabled who follows the declared package manager will not run the scripts as written, and a developer who runs the scripts is using a different tool than the repository declares.
The second oddity is the devDependencies block. It contains exactly one entry, concurrently at a caret range, and no script in the file references it. So a dependency is installed on every launch and never used, which suggests the per-example scripts used to run two processes in parallel from the root and no longer do.
Neither point breaks anything on its own. Together they signal that the root manifest was assembled for demonstration rather than maintained as infrastructure, which is worth knowing before you copy it.
Three kinds of tool call, and the distinction is the lesson
The feature index is organised by capability, and the taxonomy is the most reusable thing in the repository.
Server tool calls retrieve application data for the inference step. Cat Lounge exposes get_cat_status for the latest stats. News Guide leans on a retrieval suite: list_available_tags_and_keywords, get_article_by_id, search_articles_by_tags/keywords/exact_text, and get_current_page, plus a show_article_list_widget tool to present results. Metro Map syncs map data with get_map and then surfaces detail through list_lines, list_stations, get_line_route and get_station before giving directions.
Client tool calls fetch or mutate state that only exists in the browser. There is exactly one in the whole repository: get_selected_stations in Metro Map, which pulls the currently selected nodes off the canvas so the agent can use client-side state in its answer.
Fire-and-forget client effects update the UI without a return value. Cat Lounge invokes update_cat_status and cat_say, handled through an onEffect handler in the panel component. Metro Map streams location_select_mode inside a server action handler once a line is chosen, and streams add_station from the agent after a map update so the canvas syncs immediately and focuses the new stop.
One call of the first kind, one of the second, two of the third, across four applications: that ratio is the design lesson.
State lives per thread and is prepended as a profile block
Customer Support shows what happens when the agent mutates something rather than only reading it.
Before each run, the concierge prepends a CUSTOMER_PROFILE snapshot containing the itinerary, the loyalty status and the recent timeline. So the model is not asked to remember the passenger; it is handed a block of current state at the top of every request.
The mutations behind that block are ordinary domain tools: change seats, cancel trips, add bags, set meals, surface flight options and request assistance. Each acts against an AirlineStateManager that is scoped per thread, so two conversations in the same process do not share a passenger.
Per-thread state is the detail to copy. It is what makes a chat interface safe to run for many people at once, and it is also what makes the conversation reproducible: the state manager is the record of what the agent did, separate from what it said.
The panel mirrors the same data on the client. The server streams customer_profile/update effects after tools or widget actions, so the itinerary, loyalty and timeline shown beside the conversation stays in step with what the agent did.
None of that requires a database to demonstrate the pattern, which is why this is a useful sample even though it is an airline toy.
Page awareness travels in a request header
News Guide solves a problem that comes up in every documentation or reader application: the model has no idea what the user is looking at.
The client forwards the currently open article id in an article-id header on the request. The server reads that request context and exposes it to the agent as get_current_page, so the agent can load the full content of the page the user is on without the user pasting it into the chat.
The same example handles context the user never sees. The featured landing page and similar hidden state are normalised into agent input before the model sees them, with the stated purpose of keeping summaries and recommendations grounded rather than invented.
That pairing is the useful part: the header is how the browser tells the server what it knows, and the normalisation step is how the server decides what the model is allowed to treat as fact.
The trap is obvious once you see the design. An id in a header is client-supplied, so the backend is trusting a value that any caller can set, which means the lookup has to validate that the id exists and that the caller may see it.
Progress events are emitted from inside the slow tool
A retrieval that takes eight seconds looks broken if nothing is printed, so two of the examples stream progress while they work.
News Guide's retrieval tools emit ProgressUpdateEvent messages while searching by tags, authors, keywords or exact text, and while loading the current page, which is what surfaces the searching and loading states in the interface. A separate event finder agent emits progress as it scans dates, days of the week or keywords, so a lookup that fans out over a calendar still reports movement.
Metro Map does the same in get_map while retrieving map information, and then does something subtler: it emits a progress update while it is waiting for a client tool call to complete. A client tool such as get_selected_stations is a round trip to the browser, so the agent has a window where nothing is happening and the user has no idea why.
That second case is the one to remember. When the round trip leaves your server, you own the silence, and the fix is an event rather than a longer timeout.
Progress events are also what let you distinguish a slow tool from a stuck one, which is worth more to a user than a faster answer would be.
The canvas is locked while the stream is open
Metro Map has the only example with a canvas the user can also manipulate, and it is the one that shows how to keep two sources of truth apart.
The client locks map interaction when a response starts and unlocks it when the stream ends, through onResponseStart and onResponseEnd handlers on the panel component. The stated reason is that canvas state must not drift while the agent is updating it.
That is the whole problem in one sentence. The agent is about to push a new map state to the canvas, and a user who pans or clicks in between produces a local state the server does not know about and does not intend to keep.
Two details complete the pattern. add_station is streamed by the agent after a map update so the canvas syncs immediately and focuses the newly created stop, which means the agent is steering the viewer's attention and the UI needs to follow. And route-planning replies attach entity sources for the stations in the suggested path as annotations, so each stop in the answer is linked back to the entity it came from rather than being a bare string.
The client tool closes the loop: the server asks the canvas what is selected, the user picks, the agent reasons over that, and the stream pushes the result back into a canvas that is locked for the duration.
Editorial conclusion
Use it as a reference for the wiring rather than as a product to extend. Each demo is small enough to read end to end, and between them they cover the three things you have to get right when building a ChatKit backend: how the server reaches application data, how the server reads state that only exists in the browser, and how it updates the UI without waiting for the model. Read the Metro Map example first if your app has a canvas, since the client tool and the response lifecycle handlers are the parts that are hardest to derive. Note the repository declares pnpm while every launch script calls npm, and that its single dev dependency is unused, so treat the tooling as illustrative rather than as a setup you can copy unchanged.
Frequently asked questions
What is openai-chatkit-advanced-samples?
It is a repository of four scenario-driven ChatKit demos: Cat Lounge, Customer Support, News Guide and Metro Map. Each pairs a FastAPI backend using the ChatKit Python SDK with a Vite and React frontend wired through ChatKit.js, and each runs on its own dev port from 5170 to 5173.
How do I run one of the ChatKit example apps?
Export OPENAI_API_KEY, make sure uv is installed, then launch from the repository root with a script such as npm run cat-lounge, or from inside the example with npm install followed by npm run start. Cat Lounge serves on 5170, Customer Support on 5171, News Guide on 5172 and Metro Map on 5173.
What is the difference between the tool call types in these ChatKit samples?
Server tool calls retrieve application data for inference, such as get_cat_status, get_map or search_articles_by_tags. Client tool calls fetch state that only exists in the browser, with get_selected_stations as the only instance here. Fire-and-forget client effects stream UI updates with no return value, such as update_cat_status, cat_say, location_select_mode and add_station.
How does the News Guide example know which page the user is on?
The ChatKit client forwards the currently open article id in an article-id header, and the server reads that request context and exposes get_current_page so the agent can load the full page content without the user pasting it. Hidden context such as the featured landing page is normalised into agent input to keep answers grounded.
How does the Customer Support example keep agent state?
It prepends a CUSTOMER_PROFILE snapshot of itinerary, loyalty and recent timeline before each run, and applies tools such as changing seats, cancelling trips, adding bags, setting meals and requesting assistance against an AirlineStateManager scoped per thread. The server then streams customer_profile/update effects so the side panel mirrors the change.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openai-openai-chatkit-advanced-samples)Star history chart for your README
[](https://hysenlabs.com/projects/openai-openai-chatkit-advanced-samples)Was this useful?