ChatKit: Prezentare generală și instalare
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară descria un API care nu mai există: un obiect
new ChatKit({ apiKey, agentId }), componenteleChatProvider,ChatWindowșiMessageInput, un modul@openai/chatkit/reactși un scriptcdn.openai.com/chatkit/…. Această lecție urmează acum ghidurile oficiale OpenAI ChatKit, SDK-ul Pythonopenai-chatkit1.6.5 și@openai/chatkit-react1.6.1. Am rulat serverul exemplu local pentru a verifica fiecare pas. Notă: Agent Builder se închide la 30 noiembrie 2026; ChatKit rămâne disponibil. Surse: ChatKit · Integrări avansate cu ChatKit · Ghid rapid SDK Python · Aplicație de pornire oficială.
De ce ChatKit
Ați construit un agent cu SDK-ul Agents. Acesta rulează în terminalul dumneavoastră, iar nimeni altcineva nu îl poate utiliza. Pentru a-l pune la dispoziția utilizatorilor, aveți nevoie de o interfață de conversație, iar construirea unei interfețe de chat bune de la zero este costisitoare. Trebuie să gestionați derularea, transmiterea în flux a mesajelor, reluarea conversației, atașamentele, afișarea apelurilor de instrumente și gestionarea erorilor de rețea.
ChatKit este răspunsul OpenAI: o componentă de conversație pe care o încorporați în produsul dumneavoastră și care gestionează întreaga experiență a utilizatorului. Documentația evidențiază widget-urile interactive, sugestiile de pornire, afișarea apelurilor de instrumente, atașamentele și vizualizarea raționamentului agentului. Dumneavoastră păstrați controlul asupra a ceea ce contează: agentul, datele și regulile dumneavoastră.
Două modalități de alimentare
ChatKit este doar o interfață. Are nevoie de un server care primește mesajele, rulează agentul și transmite răspunsul înapoi în flux. OpenAI descrie două abordări:
| Cale | Cum funcționează | Pentru cine este |
|---|---|---|
| Propriul server ChatKit (integrare avansată) | Serverul dumneavoastră Python, folosind SDK-ul openai-chatkit, primește cereri de la interfață și rulează agentul la alegere, cum ar fi un agent din SDK-ul Agents | Orice proiect nou: aceasta este calea recomandată de OpenAI |
| Flux de lucru găzduit Agent Builder | OpenAI rulează un flux de lucru conceput în Agent Builder; serverul dumneavoastră creează doar sesiuni | Integrări existente în perioada de tranziție: Agent Builder se închide la 30 noiembrie 2026 |
Acest curs urmează prima cale — singura care are viitor. Rezumăm a doua cale la sfârșitul lecției pentru cei care trebuie să mențină o integrare existentă până la închidere.
Arhitectura din trei componente
O integrare ChatKit se reduce la trei elemente. Distingerea lor evită majoritatea greșelilor de începător:
- ChatKit.js, componenta în sine: o componentă web
<openai-chatkit>care afișează conversația într-un iframe. Se încarcă de pe CDN-ul OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), nu din npm: pachetul npm@openai/chatkitconține doar definițiile sale de tip. - Legături React,
@openai/chatkit-react, care expun componentaChatKitși hook-uluseChatKit. Acestea sunt opționale: fără React, controlați direct componenta web. - Serverul dumneavoastră ChatKit, un singur punct final HTTP, convențional
/chatkit, care primește toate cererile de la interfață. O instanțăChatKitServerle direcționează, se bazează pe un store pentru a persista firele de conversație și rulează agentul dumneavoastră.
Cheia API OpenAI nu părăsește niciodată serverul: interfața vorbește doar cu punctul final /chatkit al dumneavoastră.
Instalare
În partea de interfață, instalați legăturile React și încărcați scriptul ChatKit în pagina dumneavoastră:
npm install @openai/chatkit-react
<!-- În <head> al paginii dumneavoastră -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
În partea de server, instalați SDK-ul Python ChatKit (Python 3.10 sau versiuni ulterioare), care include SDK-ul Agents, plus un server web:
pip install openai-chatkit fastapi uvicorn
Serverul minimal
Serverul de mai jos urmează ghidul rapid oficial. ChatKitServer necesită o singură metodă, respond, apelată pentru fiecare mesaj al utilizatorului. Aceasta reîncarcă ultimele elemente ale firului de conversație, le convertește în intrare pentru agent cu simple_to_agent_input, rulează agentul în mod flux și traduce acel flux în evenimente ChatKit cu 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 # store în memorie din aplicația de pornire
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]:
# Ultimele 30 de elemente ale firului, restaurate în ordine cronologică
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")
Rulați-l cu OPENAI_API_KEY în mediul dumneavoastră: uvicorn main:app --port 8000.
Store-ul merită două cuvinte. ChatKit nu stochează nimic de unul singur: firele de conversație, mesajele, widget-urile și apelurile de instrumente sunt persistate de o clasă care moștenește din chatkit.store.Store și implementează aproximativ o duzină de metode (load_thread, save_thread, load_thread_items, add_thread_item…). Pentru început, reutilizați fișierul memory_store.py din aplicația de pornire oficială: acesta păstrează totul în memorie cât timp procesul rulează. În producție, înlocuiți-l cu o bază de date. Documentația recomandă stocarea obiectelor ca JSON, astfel încât actualizările SDK să nu vă oblige la migrări de schemă.
Interfața React
În partea de interfață, useChatKit primește configurația și returnează un obiect control, pe care îl transmiteți componentei ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// În dezvoltare, o valoare placeholder este suficientă; în producție,
// utilizați cheia de domeniu (vezi mai jos)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Deserviți interfața și /chatkit de la aceeași origine: în dezvoltare, proxy-ul instrumentului de build se ocupă de acest lucru (aplicația de pornire configurează proxy-ul Vite pentru a redirecționa /chatkit către portul 8000). Dacă serverul se află pe o origine diferită, permiteți-l explicit, de exemplu cu CORSMiddleware din FastAPI.
Fără React
Un site WordPress, o aplicație Rails sau o pagină statică pot integra același asistent: componenta web funcționează direct imediat ce scriptul CDN este încărcat.
<!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>
Fiecare opțiune pe care o veți vedea în lecțiile următoare are aceeași formă în ambele cazuri: un obiect transmis lui useChatKit în React sau lui setOptions pe componenta web.
Securitate din prima zi
Trei reguli, desprinse din ghidul de producție ChatKit, se aplică încă din etapa de prototip:
- Cheia API rămâne pe server. Nu trebuie să apară în codul interfeței sau în repository-ul dumneavoastră: citiți-o dintr-o variabilă de mediu sau dintr-un manager de secrete.
- Autentificați fiecare cerere către
/chatkit. SDK-ul nu gestionează acest lucru: aplicația dumneavoastră trebuie să verifice sesiunea sau token-ul utilizatorului, apoi să transmită identitatea acestuia cătreserver.processîn context (lecția 21). Fără aceasta, oricine poate rula agentul dumneavoastră pe cheltuiala dumneavoastră. - Înregistrați domeniile. Înainte de a trece în producție, declarați fiecare nume de gazdă care va afișa ChatKit pe pagina Domain allowlist din platforma OpenAI și copiați cheia generată în
domainKey. La încărcare, iframe-ul ChatKit verifică această cheie cu OpenAI și refuză afișarea dacă lipsește sau nu corespunde.
Dacă aveți deja un flux de lucru Agent Builder
Integrările existente conectate la un flux de lucru găzduit funcționează până la închiderea Agent Builder. Principiul lor diferă: serverul dumneavoastră creează o sesiune ChatKit apelând POST https://api.openai.com/v1/chatkit/sessions, cu antetul OpenAI-Beta: chatkit_beta=v1, ID-ul fluxului de lucru și un identificator user unic pentru fiecare utilizator autentificat. Apoi returnează client_secret obținut către interfață. În partea de interfață, opțiunea api primește atunci o funcție getClientSecret în loc de un URL.
Nu începeți un proiect nou pe acest model. Pentru o integrare existentă, exportați fluxul de lucru în cod Agents SDK și treceți la propriul server ChatKit înainte de 30 noiembrie 2026, urmând ghidul Migrate from Agent Builder.
Puncte cheie
- ChatKit este o interfață de conversație gata de integrat; serverul dumneavoastră rulează agentul
- Pentru orice proiect nou: propriul server ChatKit (
pip install openai-chatkit), cu o metodărespondși un punct final/chatkit; Agent Builder găzduit se închide la 30 noiembrie 2026 - Interfața se încarcă de pe CDN-ul OpenAI; în React, utilizați
useChatKitși<ChatKit control={control} />din@openai/chatkit-react - Store-ul persistă firele de conversație: în memorie pentru testare, într-o bază de date pentru producție
- Cheie API doar pe server,
/chatkitautentificat, domenii înregistrate pentru a obținedomainKey