OpenAI ChatKit (Python SDK)

Warnings

• breaking The `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'.
  Fix: Stay 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.
• gotcha Never 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.
  Fix: Implement 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`.
• gotcha A 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.
  Fix: Ensure 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.
• gotcha The `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.
  Fix: Plan for both a backend implementation using `openai-chatkit` and a compatible frontend integration. The quickstart example above only covers the backend part.
• gotcha Costs 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.
  Fix: Monitor 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.
• deprecated There 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.
  Fix: When 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.

Install

• pip install openai-chatkit Install `openai-chatkit`

Imports

• ChatKitServer

  from openai_chatkit.server import ChatKitServer

• Agent

  from openai.lib.chatkit import Agent

  While examples might implicitly refer to agents, the primary `Agent` class for defining AI logic is part of the main `openai` library's `lib.chatkit` subpackage.
• sessions.create

  client.beta.chatkit.sessions.create(...)

  Session creation is handled through the `beta.chatkit.sessions` client object of the main `openai` library, not directly from `openai-chatkit`.

Quickstart

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)