Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

ChatKit: Yleiskatsaus ja asennus

Oppitunti 17 / 25 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Miksi ChatKit
  2. Kaksi tapaa käyttää sitä
  3. Kolmen osan arkkitehtuuri
  4. Asennus
  5. Minimaalinen palvelin
  6. React-käyttöliittymä
  7. Ilman Reactia
  8. Tietoturva ensimmäisestä päivästä lähtien
  9. Jos sinulla on jo Agent Builder -työnkulku
  10. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Edellinen versio kuvasi rajapintaa, jota ei enää ole olemassa: new ChatKit({ apiKey, agentId }) -oliota, ChatProvider-, ChatWindow- ja MessageInput-komponentteja, @openai/chatkit/react-moduulia eikä cdn.openai.com/chatkit/…-skriptiä. Tämä oppitunti noudattaa virallisia OpenAI ChatKit -oppaita, Python SDK:n versiota openai-chatkit 1.6.5 ja pakettia @openai/chatkit-react 1.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:

PolkuMiten se toimiiKenelle 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 -agentinKaikki uudet projektit: tämä on OpenAI:n suosittelema polku
Hostattu Agent Builder -työnkulkuOpenAI ajaa Agent Builderissa suunnitellun työnkulun; palvelimesi luo vain istuntojaOlemassa 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:

  1. 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/chatkit sisältää vain tyyppimäärittelyt.
  2. React-sidokset, @openai/chatkit-react, jotka tarjoavat ChatKit-komponentin ja useChatKit-hookin. Nämä ovat valinnaisia: ilman Reactia ohjaat web-komponenttia suoraan.
  3. 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ä metodille server.process kontekstissa (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 on respond-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 toimialueet domainKey:n hankkimiseksi