ChatKit: Yleiskatsaus ja asennus
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Edellinen versio kuvasi rajapintaa, jota ei enää ole olemassa:
new ChatKit({ apiKey, agentId })-oliota,ChatProvider-,ChatWindow- jaMessageInput-komponentteja,@openai/chatkit/react-moduulia eikäcdn.openai.com/chatkit/…-skriptiä. Tämä oppitunti noudattaa virallisia OpenAI ChatKit -oppaita, Python SDK:n versiotaopenai-chatkit1.6.5 ja pakettia@openai/chatkit-react1.6.1. Ajoimme esimerkkipalvelimen paikallisesti varmistaaksemme jokaisen vaiheen. Huomaa: Agent Builder sulkeutuu 30. marraskuuta 2026; ChatKit pysyy käytettävissä. Lähteet: ChatKit · Edistyneet integraatiot ChatKitin kanssa · Python SDK:n pikaopas · Virallinen aloitussovellus.
Miksi ChatKit
Olet rakentanut agentin Agents SDK:lla. Se toimii päätelatteessasi, eikä kukaan muu voi käyttää sitä. Saadaksesi sen käyttäjiesi käsiin tarvitset keskustelukäyttöliittymän – ja hyvän chat-käyttöliittymän rakentaminen tyhjästä on kallista. Sinun on hallittava vieritys, viestien suoratoisto, keskustelun jatkaminen, liitteet, työkalukutsujen näyttö ja verkkovirheiden käsittely.
ChatKit on OpenAI:n vastaus: keskustelukomponentti, jonka upotat tuotteeseesi ja joka hoitaa koko käyttäjäkokemuksen. Dokumentaatio korostaa sen interaktiivisia widgettejä, aloitusehdotuksia, työkalukutsujen näyttöä, liitteitä ja agentin päättelyn visualisointia. Sinä pidät kontrollin siitä, mikä on tärkeää: agentista, datastasi ja säännöistäsi.
Kaksi tapaa käyttää sitä
ChatKit on pelkkä käyttöliittymä. Se tarvitsee palvelimen, joka vastaanottaa viestejä, ajaa agentin ja suoratoistaa vastauksen takaisin. OpenAI kuvailee kahta lähestymistapaa:
| Polku | Miten se toimii | Kenelle se on tarkoitettu |
|---|---|---|
| Oma ChatKit-palvelimesi (edistynyt integraatio) | Python-palvelimesi käyttää openai-chatkit-SDK:ta vastaanottaakseen pyyntöjä käyttöliittymältä ja ajaakseen valitsemasi agentin, kuten Agents SDK -agentin | Kaikki uudet projektit: tämä on OpenAI:n suosittelema polku |
| Hostattu Agent Builder -työnkulku | OpenAI ajaa Agent Builderissa suunnitellun työnkulun; palvelimesi luo vain istuntoja | Olemassa olevat integraatiot siirtymäkauden aikana: Agent Builder sulkeutuu 30. marraskuuta 2026 |
Tämä kurssi seuraa ensimmäistä polkua – ainoaa, jolla on tulevaisuus. Tiivistämme toisen oppitunnin lopussa niille, joiden on ylläpidettävä olemassa olevaa integraatiota sulkemiseen saakka.
Kolmen osan arkkitehtuuri
ChatKit-integraatio tiivistyy kolmeen elementtiin. Niiden erottaminen toisistaan välttää useimmat aloittelijoiden virheet:
- ChatKit.js, itse komponentti: web-komponentti
<openai-chatkit>, joka näyttää keskustelun iframe-kehyksessä. Se ladataan OpenAI:n CDN:ltä (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), ei npm:stä: npm-paketti@openai/chatkitsisältää vain tyyppimäärittelyt. - React-sidokset,
@openai/chatkit-react, jotka tarjoavatChatKit-komponentin jauseChatKit-hookin. Nämä ovat valinnaisia: ilman Reactia ohjaat web-komponenttia suoraan. - ChatKit-palvelimesi, yksittäinen HTTP-päätepiste, perinteisesti
/chatkit, joka vastaanottaa kaikki käyttöliittymän pyynnöt.ChatKitServer-instanssi reitittää ne, käyttää tallennustilaa (store) keskusteluketjujen pysyvään tallentamiseen ja ajaa agenttisi.
OpenAI API -avain ei koskaan poistu palvelimelta: käyttöliittymä keskustelee vain /chatkit-päätepisteesi kanssa.
Asennus
Asenna käyttöliittymäpuolella React-sidokset ja lataa ChatKit-skripti sivullesi:
npm install @openai/chatkit-react
<!-- Sivusi <head>-osiossa -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Asenna palvelinpuolella ChatKit Python SDK (Python 3.10 tai uudempi), joka tuo mukanaan Agents SDK:n, sekä web-palvelin:
pip install openai-chatkit fastapi uvicorn
Minimaalinen palvelin
Alla oleva palvelin noudattaa virallista pikaopasta. ChatKitServer vaatii vain yhden metodin, respond, jota kutsutaan jokaista käyttäjän viestiä kohden. Se lataa viimeisimmät ketjun kohteet, muuntaa ne agentin syötteeksi metodilla simple_to_agent_input, ajaa agentin suoratoistotilassa ja kääntää tämän virran ChatKit-tapahtumiksi metodilla 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 from the starter app
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]:
# The last 30 thread items, restored in chronological order
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")
Suorita se asettamalla OPENAI_API_KEY ympäristömuuttujaan: uvicorn main:app --port 8000.
Tallennustila (store) ansaitsee pari sanaa. ChatKit ei tallenna mitään itse: ketjut, viestit, widgetit ja työkalukutsut tallentaa luokka, joka periytyy luokasta chatkit.store.Store ja toteuttaa noin tusinan metodia (load_thread, save_thread, load_thread_items, add_thread_item…). Päästäksesi alkuun käytä uudelleen virallisesta aloitussovelluksesta löytyvää memory_store.py -tiedostoa: se pitää kaiken muistissa prosessin käynnissä ollessa. Tuotannossa korvaa se tietokannalla. Dokumentaatio suosittelee olioiden tallentamista JSON-muodossa, jotta SDK-päivitykset eivät pakota sinua tekemään skeemamuutoksia.
React-käyttöliittymä
Käyttöliittymäpuolella useChatKit vastaanottaa konfiguraation ja palauttaa control-objektin, jonka välität ChatKit-komponentille:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Kehitysvaiheessa paikkamerkkiarvo riittää; tuotannossa
// käytä toimialueavaintasi (katso alta)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Palvele käyttöliittymää ja /chatkit:tä samasta lähteestä (origin): kehitysvaiheessa build-työkalusi välityspalvelin (proxy) hoitaa tämän (aloitussovellus määrittää Viten välityspalvelimen ohjaamaan /chatkit porttiin 8000). Jos palvelin on eri lähteessä, salli se nimenomaisesti, esimerkiksi FastAPI:n CORSMiddleware:lla.
Ilman Reactia
WordPress-sivusto, Rails-sovellus tai staattinen sivu voi integroida saman avustajan: web-komponentti toimii suoraan, kun CDN-skripti on ladattu.
<!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>
Jokaisella asetuksella, jonka näet seuraavissa oppitunneissa, on sama muoto molemmissa tapauksissa: objekti, joka välitetään useChatKit:lle Reactissa tai setOptions:lle web-komponentissa.
Tietoturva ensimmäisestä päivästä lähtien
Kolme sääntöä, jotka on poimittu ChatKitin tuotanto-oppaasta, pätevät jo prototyyppivaiheesta alkaen:
- API-avain pysyy palvelimella. Sen ei tule esiintyä käyttöliittymäkoodissa eikä repositoriossasi: lue se ympäristömuuttujasta tai salaisuuksien hallintajärjestelmästä.
- Todenna jokainen
/chatkit-pyyntö. SDK ei hoida tätä: sovelluksesi on varmistettava käyttäjän istunto tai token ja välitettävä hänen identiteettinsä metodilleserver.processkontekstissa (oppitunti 21). Ilman tätä kuka tahansa voi ajaa agenttiasi kustannuksellasi. - Rekisteröi toimialueesi. Ennen käyttöönottoa ilmoita jokainen isäntänimi, joka näyttää ChatKitin, OpenAI-alustan Domain allowlist -sivulla ja kopioi generoitu avain kohtaan
domainKey. Latautuessaan ChatKit-iframe tarkistaa tämän avaimen OpenAI:lta ja kieltäytyy näytöstä, jos se puuttuu tai ei täsmää.
Jos sinulla on jo Agent Builder -työnkulku
Olemassa olevat integraatiot, jotka on kytketty hostattuun työnkulkuun, toimivat siihen saakka, kunnes Agent Builder sulkeutuu. Niiden periaate eroaa: palvelimesi luo ChatKit-istunnon kutsumalla osoitetta POST https://api.openai.com/v1/chatkit/sessions otsikolla OpenAI-Beta: chatkit_beta=v1, työnkulun tunnisteella (workflow ID) ja jokaiselle todennetulle käyttäjälle uniikilla user-tunnisteella. Se palauttaa sitten käyttöliittymälle saadun client_secret-avaimen. Käyttöliittymäpuolella api-asetus saa tällöin getClientSecret-funktion URL-osoitteen sijaan.
Älä aloita uutta projektia tällä mallilla. Olemassa olevaa integraatiota varten vie työnkulku Agents SDK -koodiksi ja siirry omaan ChatKit-palvelimeesi ennen 30. marraskuuta 2026 noudattaen opasta Migrate from Agent Builder.
Keskeiset asiat
- ChatKit on valmis integroitava keskustelukäyttöliittymä; palvelimesi ajaa agentin
- Kaikille uusille projekteille: oma ChatKit-palvelin (
pip install openai-chatkit), jossa onrespond-metodi ja/chatkit-päätepiste; hostattu Agent Builder sulkeutuu 30. marraskuuta 2026 - Käyttöliittymä ladataan OpenAI:n CDN:ltä; Reactissa käytä
useChatKit:ia ja<ChatKit control={control} />paketista@openai/chatkit-react - Tallennustila (store) säilyttää keskusteluketjut: muistissa testausta varten, tietokannassa tuotantoa varten
- API-avain vain palvelinpuolella, todennettu
/chatkit, rekisteröidyt toimialueetdomainKey:n hankkimiseksi