ChatKit: Översikt och installation
På denna sida
Lektionen omskriven den 3 november 2026. Den tidigare versionen beskrev ett API som inte längre finns: ett
new ChatKit({ apiKey, agentId })-objekt, komponenternaChatProvider,ChatWindowochMessageInput, modulen@openai/chatkit/reactsamt skriptetcdn.openai.com/chatkit/…. Denna lektion följer nu de officiella OpenAI ChatKit-guidearna, Python SDKopenai-chatkit1.6.5 och@openai/chatkit-react1.6.1. Vi körde exempelservern lokalt för att verifiera varje steg. Observera: Agent Builder stängs ner den 30 november 2026; ChatKit förblir tillgängligt. Källor: ChatKit · Avancerade integrationer med ChatKit · Snabbstart för Python SDK · Officiell startapp.
Varför ChatKit
Du har byggt en agent med Agents SDK. Den körs i din terminal och ingen annan kan använda den. För att lägga den i dina användares händer behöver du ett konversationsgränssnitt – och att bygga ett bra chatt-UI från grunden är dyrt. Du måste hantera rullning, strömmande meddelanden, återupptagande av konversationer, bifogade filer, visning av verktygsanrop och hantering av nätverksfel.
ChatKit är OpenAIs svar: en konversationskomponent som du bäddar in i din produkt och som hanterar hela användarupplevelsen. Dokumentationen lyfter fram dess interaktiva widgetar, startförslag, visning av verktygsanrop, bifogade filer och visualisering av agentens resonemang. Du behåller kontrollen över det som betyder något: agenten, dina data och dina regler.
Två sätt att driva den
ChatKit är bara ett gränssnitt. Det behöver en server som tar emot meddelanden, kör agenten och strömmar svaret tillbaka. OpenAI beskriver två tillvägagångssätt:
| Väg | Hur det fungerar | För vem det är |
|---|---|---|
| Din egen ChatKit-server (avancerad integration) | Din Python-server, som använder SDK:t openai-chatkit, tar emot förfrågningar från UI:t och kör agenten du väljer, till exempel en Agents SDK-agent | Alla nya projekt: detta är vägen OpenAI rekommenderar |
| Hostad Agent Builder-arbetsflöde | OpenAI kör ett arbetsflöde designat i Agent Builder; din server skapar bara sessioner | Befintliga integrationer under övergångsperioden: Agent Builder stängs ner den 30 november 2026 |
Denna kurs följer den första vägen – den enda som har en framtid. Vi sammanfattar den andra i slutet av lektionen för dig som behöver underhålla en befintlig integration fram till nedstängningen.
Arkitekturen med tre delar
En ChatKit-integration kokar ner till tre element. Att skilja på dem undviker de flesta nybörjarfel:
- ChatKit.js, själva komponenten: en webbkompontent
<openai-chatkit>som visar konversationen i en iframe. Den laddas från OpenAIs CDN (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), inte från npm: npm-paketet@openai/chatkitinnehåller endast dess typdefinitioner. - React-bindningar,
@openai/chatkit-react, som exponerar komponentenChatKitoch hookenuseChatKit. Dessa är valfria: utan React styr du webbkompontenten direkt. - Din ChatKit-server, en enda HTTP-slutpunkt, konventionellt
/chatkit, som tar emot alla förfrågningar från gränssnittet. EnChatKitServer-instans routar dem, förlitar sig på en store (datalager) för att beständiggöra konversationstrådar och kör din agent.
OpenAI API-nyckeln lämnar aldrig servern: gränssnittet pratar bara med din /chatkit-slutpunkt.
Installera
På gränssnittssidan installerar du React-bindningarna och laddar ChatKit-skriptet i din sida:
npm install @openai/chatkit-react
<!-- I <head> på din sida -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
På serversidan installerar du ChatKit Python SDK (Python 3.10 eller senare), vilket tar med sig Agents SDK, plus en webbserver:
pip install openai-chatkit fastapi uvicorn
Den minimala servern
Servern nedan följer den officiella snabbstarten. ChatKitServer kräver endast en metod, respond, som anropas för varje användarmeddelande. Den laddar om de senaste trådobjekten, konverterar dem till agentinmatning med simple_to_agent_input, kör agenten i strömmande läge och översätter den strömmen till ChatKit-händelser med stream_agent_response:
# main.py
from typing import Any, AsyncIterator
from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse
from memory_store import MemoryStore # in-memory store från startappen
assistant = Agent[AgentContext[dict[str, Any]]](
name="Product Assistant",
instructions="You help product users. Respond in English, briefly.",
model="gpt-6.1-sol",
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
async def respond(
self,
thread: ThreadMetadata,
input_user_message: UserMessageItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
# De senaste 30 trådobjekten, återställda i kronologisk ordning
page = await self.store.load_thread_items(
thread.id, after=None, limit=30, order="desc", context=context
)
agent_input = await simple_to_agent_input(list(reversed(page.data)))
agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
result = Runner.run_streamed(assistant, agent_input, context=agent_context)
async for event in stream_agent_response(agent_context, result):
yield event
app = FastAPI()
server = MyChatKitServer(MemoryStore())
@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
result = await server.process(await request.body(), {})
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")
Kör den med OPENAI_API_KEY i din miljö: uvicorn main:app --port 8000.
Storen förtjänar två ord. ChatKit lagrar ingenting på egen hand: trådar, meddelanden, widgetar och verktygsanrop beständiggörs av en klass som ärver från chatkit.store.Store och implementerar cirka ett dussin metoder (load_thread, save_thread, load_thread_items, add_thread_item…). För att komma igång återanvänder du filen memory_store.py från den officiella startappen: den håller allt i minnet medan processen körs. I produktion ersätter du den med en databas. Dokumentationen rekommenderar att objekt lagras som JSON så att SDK-uppdateringar inte tvingar fram schemamigreringar för dig.
React-gränssnittet
På gränssnittssidan tar useChatKit emot konfigurationen och returnerar ett control-objekt, som du skickar till komponenten ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// I utveckling räcker ett platshållarvärde; i produktion,
// använd din domännyckel (se nedan)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Servera gränssnittet och /chatkit från samma origin: i utveckling hanterar ditt byggnadsverktygs proxy detta (startappen konfigurerar Vites proxy för att omdirigera /chatkit till port 8000). Om servern finns på en annan origin tillåter du den explicit, till exempel med FastAPI:s CORSMiddleware.
Utan React
En WordPress-sajt, en Rails-applikation eller en statisk sida kan integrera samma assistent: webbkompontenten fungerar direkt så snart CDN-skriptet har laddats.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
</head>
<body>
<div id="chat-root" style="height: 600px"></div>
<script>
const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
api: { url: '/chatkit', domainKey: 'local-dev' },
});
document.getElementById('chat-root').append(chatkit);
</script>
</body>
</html>
Varje alternativ du kommer att se i de följande lektionerna har samma form i båda fallen: ett objekt som skickas till useChatKit i React, eller till setOptions på webbkompontenten.
Säkerhet från dag ett
Tre regler, hämtade från ChatKit-produktionsguiden, gäller från prototypstadiet:
- API-nyckeln stannar på servern. Den får inte förekomma i gränssnittskod eller i ditt arkiv: läs den från en miljövariabel eller en hemlighetshanterare.
- Autentisera varje förfrågan till
/chatkit. SDK:t hanterar inte detta: din applikation måste verifiera användarens session eller token och sedan skicka deras identitet tillserver.processi kontexten (lektion 21). Utan detta kan vem som helst köra din agent på din bekostnad. - Registrera dina domäner. Innan du går live deklarerar du varje värdnamn som ska visa ChatKit på OpenAI-plattformens sida Domain allowlist och kopierar den genererade nyckeln till
domainKey. Vid laddning verifierar ChatKit-iframen denna nyckel med OpenAI och vägrar att visas om den saknas eller inte matchar.
Om du redan har ett Agent Builder-arbetsflöde
Befintliga integrationer kopplade till ett hostat arbetsflöde fungerar tills Agent Builder stängs ner. Deras princip skiljer sig: din server skapar en ChatKit-session genom att anropa POST https://api.openai.com/v1/chatkit/sessions, med headern OpenAI-Beta: chatkit_beta=v1, arbetsflödes-ID:t och en user-identifierare unik för varje autentiserad användare. Den returnerar sedan den erhållna client_secret till gränssnittet. På gränssnittssidan tar alternativet api då emot en funktion getClientSecret istället för en URL.
Påbörja inga nya projekt med denna modell. För en befintlig integration exporterar du arbetsflödet till Agents SDK-kod och byter till din egen ChatKit-server före den 30 november 2026, enligt guiden Migrate from Agent Builder.
Viktiga punkter
- ChatKit är ett konversationsgränssnitt redo att integreras; din server kör agenten
- För alla nya projekt: din egen ChatKit-server (
pip install openai-chatkit), med en metodrespondoch en slutpunkt/chatkit; den hostade Agent Builder stängs ner den 30 november 2026 - Gränssnittet laddas från OpenAIs CDN; i React använder du
useChatKitoch<ChatKit control={control} />från@openai/chatkit-react - Storen beständiggör konversationstrådar: i minne för testning, i en databas för produktion
- API-nyckel endast på serversidan, autentiserad
/chatkit, registrerade domäner för att erhålladomainKey