openai/openai-chatkit-advanced-samples

openai/openai-chatkit-advanced-samples

Description: Starter app to build with OpenAI ChatKit SDK

License: NOASSERTION

Stars: 637

Forks: 297

Open issues: 10

Created: 2025-10-06T01:08:49Z

Pushed: 2026-03-27T21:05:29Z

Default branch: main

Fork: no

Archived: no

README:

OpenAI ChatKit Examples

This repository collects scenario-driven ChatKit demos. Each example pairs a FastAPI backend with a Vite + React frontend, implementing a custom backend using ChatKit Python SDK and wiring it up with ChatKit.js client-side.

You can run the following examples:

• [Cat Lounge](examples/cat-lounge) - caretaker for a virtual cat that helps improve energy, happiness, and cleanliness stats.
• [Customer Support](examples/customer-support) – airline concierge with live itinerary data, timeline syncing, and domain-specific tools.
• [News Guide](examples/news-guide) – Foxhollow Dispatch newsroom assistant with article search, @-mentions, and page-aware responses.
• [Metro Map](examples/metro-map) – chat-driven metro planner with a React Flow network of lines and stations.

Quickstart

1. Export OPENAI_API_KEY. 2. Make sure uv is installed. 3. Launch an example from the repo root, or with npm run start from the project directory:

| Example | Command for repo root | Command for project directory | URL | | ---------------- | -------------------------- | ---------------------------------------------------------- | --------------------- | | Cat Lounge | npm run cat-lounge | cd examples/cat-lounge && npm install && npm run start | http://localhost:5170 | | Customer Support | npm run customer-support | cd examples/customer-support && npm install && npm start | http://localhost:5171 | | News Guide | npm run news-guide | cd examples/news-guide && npm install && npm run start | http://localhost:5172 | | Metro Map | npm run metro-map | cd examples/metro-map && npm install && npm run start | http://localhost:5173 |

Feature index

Server tool calls to retrieve application data for inference

• Cat Lounge:
• Function tool get_cat_status ([cat_agent.py](examples/cat-lounge/backend/app/cat_agent.py)) pulls the latest cat stats for the agent.
• News Guide:
• The agent leans on a suite of retrieval tools—list_available_tags_and_keywords, get_article_by_id, search_articles_by_tags/keywords/exact_text, and get_current_page—before responding, and uses show_article_list_widget to present results ([news_agent.py](examples/news-guide/backend/app/agents/news_agent.py)).
• Hidden context such as the featured landing page is normalized into agent input so summaries and recommendations stay grounded ([news_agent.py](examples/news-guide/backend/app/agents/news_agent.py)).
• Metro Map:
• The metro agent syncs map data with get_map and surfaces line and station details via list_lines, list_stations, get_line_route, and get_station before giving directions ([metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py)).
• show_line_selector presents the user a multiple-choice question using a widget.
• Route-planning replies attach entity sources for the stations in the suggested path as annotations.
• Customer Support:
• The concierge prepends a ` snapshot (itinerary, loyalty, recent timeline) before each run and exposes tools to change seats, cancel trips, add bags, set meals, surface flight options, and request assistance against the per-thread AirlineStateManager` state ([server.py](examples/customer-support/backend/app/server.py), [support_agent.py](examples/customer-support/backend/app/support_agent.py), [airline_state.py](examples/customer-support/backend/app/airline_state.py)).

Client tool calls that mutate or fetch UI state

• Metro Map:
• Client tool get_selected_stations pulls the currently selected nodes from the canvas so the agent can use client-side state in its response ([ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx), [metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py)).

Fire-and-forget client effects

• Cat Lounge:
• Client effects update_cat_status and cat_say are invoked by server tools to sync UI state and surface speech bubbles; handled via onEffect in [ChatKitPanel.tsx](examples/cat-lounge/frontend/src/components/ChatKitPanel.tsx).
• Metro Map:
• Client effect location_select_mode is streamed within the server action handler ([server.py](examples/metro-map/backend/app/server.py)) after a line is chosen and updates the metro map canvas ([ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx)).
• Client effect add_station is streamed by the agent after map updates to immediately sync the canvas and focus the newly created stop ([metro_map_agent.py](examples/metro-map/backend/app/agents/metro_map_agent.py), [ChatKitPanel.tsx](examples/metro-map/frontend/src/components/ChatKitPanel.tsx)).
• Customer Support:
• The server streams customer_profile/update effects after tools or widget actions so the side panel mirrors the latest itinerary, loyalty, and timeline data ([support_agent.py](examples/customer-support/backend/app/support_agent.py), [server.py](examples/customer-support/backend/app/server.py)).

Page-aware model responses

• News Guide:
• The ChatKit client forwards the currently open article id in an article-id header so the backend can scope responses to “this page” ([ChatKitPanel.tsx](examples/news-guide/frontend/src/components/ChatKitPanel.tsx)).
• The server reads that request context and exposes get_current_page so the agent can load full content without asking the user to paste it ([main.py](examples/news-guide/backend/app/main.py), [news_agent.py](examples/news-guide/backend/app/agents/news_agent.py)).

Progress updates

• News Guide:
• Retrieval tools stream ProgressUpdateEvent messages while searching tags, authors, keywords, exact text, or loading the current page so the UI surfaces “Searching…”/“Loading…” states ([news_agent.py](examples/news-guide/backend/app/agents/news_agent.py)).
• The event finder emits progress as it scans dates, days of week, or keywords to keep users informed during longer lookups ([event_finder_agent.py](examples/news-guide/backend/app/agents/event_finder_agent.py)).
• Metro Map:
• The metro agent emits a progress update while retrieving map information in get_map; it also emits a progress update…