Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

ChatKit: Áttekintés és telepítés

17. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Miért a ChatKit?
  2. Két mód a működtetésre
  3. A háromrészes architektúra
  4. Telepítés
  5. A minimális szerver
  6. A React felület
  7. React nélkül
  8. Biztonság az első naptól
  9. Ha már van Agent Builder munkafolyamatod
  10. Főbb megállapítások

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 és MessageInput komponenseket, egy @openai/chatkit/react modult és egy cdn.openai.com/chatkit/… szkriptet. Ez a lecke most a hivatalos OpenAI ChatKit útmutatókat, a Python SDK openai-chatkit 1.6.5 verzióját és az @openai/chatkit-react 1.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:

ÚtvonalHogyan működikKinek 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ötBármely új projekt: ezt az utat ajánlja az OpenAI
Hostolt Agent Builder munkafolyamatAz OpenAI futtat egy az Agent Builderben tervezett munkafolyamatot; a szervered csak munkameneteket hoz létreMeglé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:

  1. 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/chatkit npm csomag csak a típusdefinícióit tartalmazza.
  2. React kötések, @openai/chatkit-react, amelyek elérhetővé teszik a ChatKit komponenst és a useChatKit hookot. Ezek opcionálisak: React nélkül közvetlenül irányítod a webkomponenst.
  3. A te ChatKit szervered, egy egyetlen HTTP végpont, hagyományosan /chatkit, amely fogadja az összes kérést a felületről. Egy ChatKitServer pé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 /chatkit felé. 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 a server.process hí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), egy respond metódussal és egy /chatkit vé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-react csomagbó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 a domainKey megszerzéséhez