ChatKit: Áttekintés és telepítés
Ezen az oldalon
A leckét 2026. november 3-án írtuk át. Az előző verzió egy már nem létező API-t írt le: egy
new ChatKit({ apiKey, agentId })objektumot,ChatProvider,ChatWindowésMessageInputkomponenseket, egy@openai/chatkit/reactmodult és egycdn.openai.com/chatkit/…szkriptet. Ez a lecke most a hivatalos OpenAI ChatKit útmutatókat, a Python SDKopenai-chatkit1.6.5 verzióját és az@openai/chatkit-react1.6.1 verzióját követi. Minden lépést ellenőriztünk egy helyileg futtatott példaszerverrel. Megjegyzés: Az Agent Builder 2026. november 30-án leáll; a ChatKit továbbra is elérhető marad. Források: ChatKit · Haladó integrációk a ChatKittel · Python SDK gyorsindítás · Hivatalos kezdőalkalmazás.
Miért a ChatKit?
Építettél már egy ügynököt az Agents SDK-val. Az a terminálodban fut, és senki más nem használhatja. Ahhoz, hogy a felhasználóid kezébe add, szükséged van egy beszélgetési felületre – egy jó chat UI nulláról történő megépítése azonban költséges. Kezelned kell a görgetést, az üzenetek streamelését, a beszélgetés folytatását, a csatolmányokat, az eszközlehívások megjelenítését és a hálózati hibakezelést.
A ChatKit az OpenAI válasza: egy beszélgetési komponens, amelyet beágyazhatsz a termékedbe, és amely kezeli a teljes felhasználói élményt. A dokumentáció kiemeli az interaktív widgeteket, a kezdő javaslatokat, az eszközlehívások megjelenítését, a csatolmányokat és az ügynök következtetéseinek vizualizációját. Te megtartod az irányítást ami felett fontos: az ügynök, az adataid és a szabályaid felett.
Két mód a működtetésre
A ChatKit csupán egy felület. Szüksége van egy szerverre, amely fogadja az üzeneteket, futtatja az ügynököt, majd visszastrímeli a választ. Az OpenAI két megközelítést ír le:
| Útvonal | Hogyan működik | Kinek szól |
|---|---|---|
| Saját ChatKit szerver (haladó integráció) | A saját Python szervered az openai-chatkit SDK-t használva fogadja a kéréseket a felületről, és a választott ügynököt futtatja, például egy Agents SDK ügynököt | Bármely új projekt: ezt az utat ajánlja az OpenAI |
| Hostolt Agent Builder munkafolyamat | Az OpenAI futtat egy az Agent Builderben tervezett munkafolyamatot; a szervered csak munkameneteket hoz létre | Meglévő integrációk az átmeneti időszak alatt: az Agent Builder 2026. november 30-án leáll |
Ez a tanfolyam az első utat követi – ez az egyetlen, amelynek jövője van. A második utat a lecke végén foglaljuk össze azok számára, akiknek egy meglévő integrációt kell karbantartaniuk a leállításig.
A háromrészes architektúra
Egy ChatKit integráció három elemre vezethető vissza. Ezek megkülönböztetése elkerüli a legtöbb kezdő hibát:
- ChatKit.js, maga a komponens: egy
<openai-chatkit>webkomponens, amely egy iframe-ben jeleníti meg a beszélgetést. Az OpenAI CDN-jéről töltődik be (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), nem az npm-ről: az@openai/chatkitnpm csomag csak a típusdefinícióit tartalmazza. - React kötések,
@openai/chatkit-react, amelyek elérhetővé teszik aChatKitkomponenst és auseChatKithookot. Ezek opcionálisak: React nélkül közvetlenül irányítod a webkomponenst. - A te ChatKit szervered, egy egyetlen HTTP végpont, hagyományosan
/chatkit, amely fogadja az összes kérést a felületről. EgyChatKitServerpéldány útvonalazza ezeket, egy tárolóra (store) támaszkodik a beszélgetési szálak megőrzéséhez, és futtatja az ügynöködet.
Az OpenAI API kulcs soha nem hagyja el a szervert: a felület csak a te /chatkit végpontoddal kommunikál.
Telepítés
A felület oldalán telepítsd a React kötéseket, és töltsd be a ChatKit szkriptet az oldaladon:
npm install @openai/chatkit-react
<!-- Az oldalad <head> részében -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
A szerver oldalán telepítsd a ChatKit Python SDK-t (Python 3.10 vagy újabb), amely magával hozza az Agents SDK-t, plusz egy web szervert:
pip install openai-chatkit fastapi uvicorn
A minimális szerver
Az alábbi szerver a hivatalos gyorsindítást követi. A ChatKitServer csak egy metódust igényel, a respond-ot, amelyet minden felhasználói üzenetnél meghívnak. Ez betölti a szál legfrissebb elemeit, átalakítja őket ügynök-bemenetté a simple_to_agent_input segítségével, streaming módban futtatja az ügynököt, majd a stream_agent_response segítségével ezt a streamet ChatKit eseményekké fordítja:
# 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 # memóriában tároló a kezdőalkalmazásból
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]:
# Az utolsó 30 szálelem, időrendi sorrendben visszaállítva
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")
Futtasd az OPENAI_API_KEY környezeti változóval: uvicorn main:app --port 8000.
A tároló (store) érdemel két szót. A ChatKit önmagában semmit nem tárol: a szálakat, üzeneteket, widgeteket és eszközlehívásokat egy olyan osztály őrzi meg, amely örökli a chatkit.store.Store osztályt, és megvalósít körülbelül tucatnyi metódust (load_thread, save_thread, load_thread_items, add_thread_item…). A kezdéshez használd újra a hivatalos kezdőalkalmazás memory_store.py fájlját: ez mindent a memóriában tart, amíg a folyamat fut. Éles környezetben cseréld le ezt egy adatbázisra. A dokumentáció azt ajánlja, hogy az objektumokat JSON-ként tárold, így az SDK frissítései nem kényszerítenek rád séma-migrációkat.
A React felület
A felület oldalán a useChatKit megkapja a konfigurációt, és visszaad egy control objektumot, amelyet átadsz a ChatKit komponensnek:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Fejlesztés során egy helyettesítő érték is elég; éles környezetben
// használd a tartománykulcsodat (lásd lentebb)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Szolgáld ki a felületet és a /chatkit végpontot ugyanarról az eredetről (origin): fejlesztés során ezt az építőeszközöd proxyja kezeli (a kezdőalkalmazás konfigurálja a Vite proxyját, hogy a /chatkit kéréseket a 8000-es portra irányítsa). Ha a szerver másik eredeten él, engedélyezd ezt kifejezetten, például a FastAPI CORSMiddlewareével.
React nélkül
Egy WordPress oldal, egy Rails alkalmazás vagy egy statikus oldal is integrálhatja ugyanazt az asszisztenst: a webkomponens közvetlenül működik, amint a CDN szkript betöltődött.
<!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>
Minden opció, amelyet a következő leckékben látni fogsz, ugyanilyen formájú mindkét esetben: egy objektum, amelyet átadsz a useChatKit-nak Reactben, vagy a setOptions-nak a webkomponensen.
Biztonság az első naptól
Három szabály, amelyet a ChatKit éles környezeti útmutatójából vettünk át, már a prototípus szakasztól kezdve érvényes:
- Az API kulcs a szerveren marad. Nem jelenhet meg a felületi kódban vagy a tárolódban: olvasd be környezeti változóból vagy titokkezelőből.
- Hitelesíts minden kérést a
/chatkitfelé. Az SDK ezt nem kezeli: az alkalmazásodnak ellenőriznie kell a felhasználó munkamenetét vagy tokenjét, majd átadnia a személyazonosságát aserver.processhívásának kontextusában (21. lecke). Enélkül bárki futtathatja az ügynöködet a te költségedre. - Regisztráld a tartományaidat. Mielőtt élesítenéd, jelentsd be minden gazdanevet, amelyen a ChatKit meg fog jelenni, az OpenAI platform Tartomány engedélyezési lista oldalán, és másold be a generált kulcsot a
domainKeyértékének. Betöltéskor a ChatKit iframe ellenőrzi ezt a kulcsot az OpenAI-nál, és megtagadja a megjelenítést, ha az hiányzik vagy nem egyezik.
Ha már van Agent Builder munkafolyamatod
A hostolt munkafolyamathoz kapcsolt meglévő integrációk az Agent Builder leállításáig működnek. Elvük eltér: a szervered egy ChatKit munkamenetet hoz létre a POST https://api.openai.com/v1/chatkit/sessions hívásával, az OpenAI-Beta: chatkit_beta=v1 fejléccel, a munkafolyamat azonosítójával és egy minden hitelesített felhasználóra egyedi user azonosítóval. Ezután visszaadja a megszerzett client_secret értéket a felületnek. A felület oldalán az api opció ekkor egy getClientSecret függvényt vár egy URL helyett.
Ne kezdj új projektet ezen a modellen. Egy meglévő integráció esetén exportáld a munkafolyamatot Agents SDK kóddá, és válts a saját ChatKit szerveredre 2026. november 30. előtt, követve a Migrálás az Agent Builderből útmutatót.
Főbb megállapítások
- A ChatKit egy beépítésre kész beszélgetési felület; a szervered futtatja az ügynököt
- Bármely új projekthez: saját ChatKit szerver (
pip install openai-chatkit), egyrespondmetódussal és egy/chatkitvégponttal; a hostolt Agent Builder 2026. november 30-án leáll - A felület az OpenAI CDN-jéről töltődik be; Reactben használd a
useChatKit-ot és a<ChatKit control={control} />komponenst az@openai/chatkit-reactcsomagból - A tároló őrzi meg a beszélgetési szálakat: teszteléshez memóriában, éles környezethez adatbázisban
- API kulcs csak szerveroldalon, hitelesített
/chatkit, regisztrált tartományok adomainKeymegszerzéséhez