Install & Compatibility
Where this runs
tested against v1.6.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 7.516s · 96.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.7s · import 6.966s · 95MB
82MB installed
● package 82MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatKitServer
✓ from chatkit.server import ChatKitServer
✗ from openai_chatkit.server import ChatKitServer
This quickstart demonstrates setting up a basic FastAPI backend that uses `openai-chatkit` to handle chat interactions. It includes creating a ChatKit session (which provides a client secret for frontend authentication) and a response endpoint where your defined AI agent processes user messages. Remember to replace placeholder IDs and ensure your `OPENAI_API_KEY` and `CHATKIT_WORKFLOW_ID` are set as environment variables. A frontend (e.g., using `@openai/chatkit-react`) would then connect to these endpoints.
import os
from fastapi import FastAPI, Request
from openai import OpenAI
from openai_chatkit.server import ChatKitServer, UserMessageItem
from openai.lib.chatkit import Agent
app = FastAPI()
openai_client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY', ''))
# Define your AI agent
assistant_agent = Agent(
model="gpt-4o",
name="Assistant",
instructions="You are a helpful assistant."
)
# Implement your ChatKit server
class MyChatKitServer(ChatKitServer):
def __init__(self):
super().__init__()
self.agent = assistant_agent
async def respond(
self, thread_id: str, input: UserMessageItem, request: Request
):
# Example: Process user input with your agent
# In a real application, you would manage state and agent context here
response_content = f"Echoing: {input.text}"
yield {"type": "text", "text": response_content}
chatkit_server = MyChatKitServer()
@app.post("/api/chatkit/session")
async def create_chat_session(request: Request):
# In a real app, authenticate the user and provide a unique user_id
user_id = "user_123"
# Workflow ID would come from your OpenAI Agent Builder workflow
workflow_id = os.environ.get('CHATKIT_WORKFLOW_ID', 'wf-YOUR_WORKFLOW_ID')
# The client secret should be generated on the server-side only
session = openai_client.beta.chatkit.sessions.create(
workflow_id=workflow_id,
user_id=user_id
)
return {"client_secret": session.client_secret}
@app.post("/api/chatkit/respond")
async def chatkit_respond(request: Request):
return await chatkit_server.handle_request(request)
Debug
Known issues
breakingThe `openai-chatkit` library is currently in beta, and the broader ChatKit and AgentKit ecosystem is evolving rapidly. This means there is a higher likelihood of breaking changes and API adjustments between versions, potentially leading to 'Dependency and Versioning Issues'.fixStay updated with official OpenAI documentation and GitHub releases. Regularly test your integration when updating library versions. Consider pinning exact versions in production to avoid unexpected breakage.
affects: All versions (beta status)
gotchaNever expose your raw OpenAI API key on the client-side. The `openai-chatkit` Python SDK is for backend use, where your server securely generates a short-lived `client_secret` using the main `openai` library's `beta.chatkit.sessions.create` method. This `client_secret` is then safely passed to your frontend ChatKit component for authentication.fixImplement a dedicated backend endpoint (e.g., with FastAPI) to handle the creation of ChatKit sessions and generation of `client_secret`s. Your frontend should only ever receive and use this short-lived `client_secret`.
affects: All versions
gotchaA common 'blank screen' issue on the frontend occurs if the domain where ChatKit is embedded is not explicitly added to the allowlist in your OpenAI organization settings. This is a critical security feature to prevent unauthorized usage.fixEnsure that all domains (including `localhost` for development and your production domains) where ChatKit is embedded are added to the 'Domain Allowlist' in your OpenAI organization settings. Session creation can succeed even if the domain is not allowed, leading to confusing debugging.
affects: All versions
gotchaThe `openai-chatkit` Python SDK is a *backend* library. It does not provide a user interface. You will need a separate frontend component (e.g., `@openai/chatkit-react` for React applications or the ChatKit JS web component) to display the chat interface and interact with your `openai-chatkit` backend.fixPlan for both a backend implementation using `openai-chatkit` and a compatible frontend integration. The quickstart example above only covers the backend part.
affects: All versions
gotchaCosts for ChatKit solutions can be unpredictable, as they are directly tied to OpenAI API usage (token consumption) by your AI agents. This can fluctuate significantly based on user interaction complexity and volume.fixMonitor your OpenAI API usage and set budgets. Design agents to be efficient with token usage. Consider implementing rate limiting or usage caps if cost control is a primary concern.
affects: All versions
deprecatedThere have been reports (as of February 2026) that the official OpenAI ChatKit Starter App repositories experienced issues, specifically returning 404 errors, indicating potential changes or deprecations in how starter templates are meant to be used or deployed.fixWhen starting a new project, refer directly to the latest official documentation and quickstart guides for the `openai-chatkit` Python SDK rather than relying on older starter app repositories which may not be actively maintained or compatible with current API versions. If using a starter app, verify its currency and compatibility.
affects: Likely recent versions, potentially from late 2025 onwards.
Upgrade
Version history
1.6.5latest on PyPI · released May 19, 2026
Audit
Dependencies
openairequiredRequired for interacting with OpenAI APIs to create ChatKit sessions and power AI agents.
fastapioptionalCommonly used web framework for building the backend endpoint that hosts the ChatKit server.