ChatKit: Pregled i instalacija
Na ovoj stranici
Lekcija je ponovno napisana 3. studenoga 2026. Prethodna verzija opisivala je API koji više ne postoji: objekt
new ChatKit({ apiKey, agentId }), komponenteChatProvider,ChatWindowiMessageInput, modul@openai/chatkit/reactte skriptucdn.openai.com/chatkit/…. Ova lekcija sada slijedi službene vodiče za OpenAI ChatKit, Python SDKopenai-chatkit1.6.5 i@openai/chatkit-react1.6.1. Primjer poslužitelja pokrenuli smo lokalno kako bismo verificirali svaki korak. Napomena: Agent Builder se gasi 30. studenoga 2026.; ChatKit ostaje dostupan. Izvori: ChatKit · Napredne integracije s ChatKitom · Brzi start za Python SDK · Službena početna aplikacija.
Zašto ChatKit
Izgradio si agenta pomoću Agents SDK-a. On se pokreće u tvom terminalu i nitko ga drugi ne može koristiti. Da bi ga stavio u ruke svojim korisnicima, trebaš sučelje za razgovor – a izrada dobrog korisničkog sučelja za chat od nule skupa je. Moraš rukovati pomicanjem, strujanjem poruka, nastavkom razgovora, privicima, prikazom poziva alata i rukovanjem mrežnim pogreškama.
ChatKit je OpenAIjev odgovor: komponenta za razgovor koju ugrađuješ u svoj proizvod i koja preuzima cijelo korisničko iskustvo. Dokumentacija ističe njegove interaktivne widgete, početne prijedloge, prikaz poziva alata, privitke i vizualizaciju rezoniranja agenta. Ti zadržavaš kontrolu nad onim što je bitno: agentom, svojim podacima i svojim pravilima.
Dva načina napajanja
ChatKit je samo sučelje. Treba mu poslužitelj koji prima poruke, pokreće agenta i vraća odgovor putem strujanja. OpenAI opisuje dva pristupa:
| Put | Kako funkcionira | Za koga je namijenjen |
|---|---|---|
| Tvoj vlastiti ChatKit poslužitelj (napredna integracija) | Tvoj Python poslužitelj, koristeći SDK openai-chatkit, prima zahtjeve iz sučelja i pokreće agenta po tvom izboru, poput agenta iz Agents SDK-a | Bilo koji novi projekt: ovo je put koji OpenAI preporučuje |
| Tijek rada Hosted Agent Builder | OpenAI pokreće tijek rada dizajniran u Agent Builderu; tvoj poslužitelj samo stvara sesije | Postojeće integracije tijekom prijelaznog razdoblja: Agent Builder se gasi 30. studenoga 2026. |
Ovaj tečaj slijedi prvi put – jedini koji ima budućnost. Sažimamo drugi na kraju lekcije za one koji moraju održavati postojeću integraciju do gašenja.
Arhitektura od tri dijela
Integracija ChatKita svodi se na tri elementa. Razlikovanje njih izbjegava većinu početničkih pogrešaka:
- ChatKit.js, sama komponenta: web komponenta
<openai-chatkit>koja prikazuje razgovor u iframeu. Učitava se s OpenAIjevog CDN-a (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), a ne s npma: npm paket@openai/chatkitsadrži samo njegove definicije tipova. - React vezanja,
@openai/chatkit-react, koja izlažu komponentuChatKiti hookuseChatKit. Oni su opcionalni: bez Reacta, izravno upravljaš web komponentom. - Tvoj ChatKit poslužitelj, jedna HTTP krajnja točka, konvencionalno
/chatkit, koja prima sve zahtjeve iz sučelja. InstancaChatKitServerusmjerava ih, oslanja se na pohranu (store) za trajno spremanje niti razgovora i pokreće tvoj agent.
OpenAI API ključ nikada ne napušta poslužitelj: sučelje komunicira samo s tvojom krajnjom točkom /chatkit.
Instalacija
Na strani sučelja instaliraj React vezanja i učitaj ChatKit skriptu na svoju stranicu:
npm install @openai/chatkit-react
<!-- U <head> tvoje stranice -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Na strani poslužitelja instaliraj ChatKit Python SDK (Python 3.10 ili noviji), koji uključuje Agents SDK, plus web poslužitelj:
pip install openai-chatkit fastapi uvicorn
Minimalni poslužitelj
Poslužitelj u nastavku slijedi službeni brzi start. ChatKitServer zahtijeva samo jednu metodu, respond, koja se poziva za svaku korisničku poruku. Ona ponovno učitava najnovije stavke niti, pretvara ih u ulaz za agenta pomoću simple_to_agent_input, pokreće agenta u načinu strujanja i prevodi taj tok u ChatKit događaje pomoću 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 # pohrana u memoriji iz početne aplikacije
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]:
# Posljednjih 30 stavki niti, vraćenih kronološkim redoslijedom
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")
Pokreni ga s OPENAI_API_KEY u svom okruženju: uvicorn main:app --port 8000.
Pohrana (store) zaslužuje dvije riječi. ChatKit ništa ne pohranjuje sam: niti, poruke, widgete i pozive alata trajno sprema klasa koja nasljeđuje chatkit.store.Store i implementira desetak metoda (load_thread, save_thread, load_thread_items, add_thread_item…). Za početak, ponovno iskoristi datoteku memory_store.py iz službene početne aplikacije: ona sve drži u memoriji dok proces traje. U proizvodnji je zamijeni bazom podataka. Dokumentacija preporučuje pohranjivanje objekata kao JSON kako ažuriranja SDK-a ne bi nametnula migracije sheme.
React sučelje
Na strani sučelja, useChatKit prima konfiguraciju i vraća objekt control, koji prosljeđuješ komponenti ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// U razvoju je dovoljna privremena vrijednost; u proizvodnji
// koristi svoj ključ domene (vidi dolje)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Poslužuj sučelje i /chatkit s istog izvorišta: u razvoju, proxy tvog alata za izgradnju to rješava (početna aplikacija konfigurira Viteov proxy za preusmjeravanje /chatkit na port 8000). Ako poslužitelj živi na drugom izvorištu, eksplicitno ga dopusti, primjerice s FastAPIjevim CORSMiddleware.
Bez Reacta
WordPress stranica, Rails aplikacija ili statična stranica mogu integrirati istog asistenta: web komponenta radi izravno čim se CDN skripta učita.
<!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>
Svaka opcija koju ćeš vidjeti u sljedećim lekcijama ima isti oblik u oba slučaja: objekt se prosljeđuje useChatKit u Reactu ili setOptions na web komponenti.
Sigurnost od prvog dana
Tri pravila, preuzeta iz ChatKit vodiča za proizvodnju, vrijede od faze prototipa:
- API ključ ostaje na poslužitelju. Ne smije se pojavljivati u kodu sučelja niti u tvom repozitoriju: čitaj ga iz varijable okruženja ili upravitelja tajni.
- Autenticiraj svaki zahtjev na
/chatkit. SDK to ne rješava: tvoja aplikacija mora verificirati korisničku sesiju ili token, a zatim proslijediti njihov identitet userver.processunutar konteksta (lekcija 21). Bez ovoga, bilo tko može pokrenuti tvog agenta o tvom trošku. - Registriraj svoje domene. Prije lansiranja, prijavi svako ime hosta koje će prikazivati ChatKit na stranici Popis dopuštenih domena platforme OpenAI i kopiraj generirani ključ u
domainKey. Pri učitavanju, ChatKit iframe verificira taj ključ s OpenAIjem i odbija prikaz ako nedostaje ili se ne podudara.
Ako već imaš tijek rada Agent Buildera
Postojeće integracije povezane s hostiranim tijekom rada funkcioniraju dok se Agent Builder ne ugasi. Njihovo načelo je drugačije: tvoj poslužitelj stvara ChatKit sesiju pozivom POST https://api.openai.com/v1/chatkit/sessions, s zaglavljem OpenAI-Beta: chatkit_beta=v1, ID-jem tijeka rada i identifikatorom user jedinstvenim za svakog autentificiranog korisnika. Zatim vraća dobiveni client_secret sučelju. Na strani sučelja, opcija api tada prima funkciju getClientSecret umjesto URL-a.
Ne započinji novi projekt na ovom modelu. Za postojeću integraciju, izvezi tijek rada u kod Agents SDK-a i prijeđi na vlastiti ChatKit poslužitelj prije 30. studenoga 2026., slijedeći vodič Migracija s Agent Buildera.
Ključne točke
- ChatKit je sučelje za razgovor spremno za integraciju; tvoj poslužitelj pokreće agenta
- Za bilo koji novi projekt: tvoj vlastiti ChatKit poslužitelj (
pip install openai-chatkit), s metodomrespondi krajnjom točkom/chatkit; hostirani Agent Builder gasi se 30. studenoga 2026. - Sučelje se učitava s OpenAIjevog CDN-a; u Reactu koristi
useChatKiti<ChatKit control={control} />iz@openai/chatkit-react - Pohrana trajno sprema niti razgovora: u memoriji za testiranje, u bazi podataka za proizvodnju
- API ključ samo na strani poslužitelja, autentificirani
/chatkit, registrirane domene za dobivanjedomainKey