Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

ChatKit: Pregled in namestitev

Lekcija 17 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Zakaj ChatKit
  2. Dva načina napajanja
  3. Arhitektura iz treh delov
  4. Namestitev
  5. Minimalni strežnik
  6. Vmesnik React
  7. Brez Reacta
  8. Varnost od prvega dne
  9. Če že imaš potek dela v Agent Builderju
  10. Ključne ugotovitve

Lekcija na novo napisana 3. novembra 2026. Prejšnja različica je opisovala API, ki ne obstaja več: objekt new ChatKit({ apiKey, agentId }), komponenti ChatProvider in ChatWindow, komponento MessageInput, modul @openai/chatkit/react ter skript cdn.openai.com/chatkit/…. Ta lekcija zdaj sledi uradnim vodnikom za OpenAI ChatKit, Python SDK openai-chatkit 1.6.5 in @openai/chatkit-react 1.6.1. Primer strežnika smo zagnali lokalno, da smo preverili vsak korak. Opomba: Agent Builder se izklopi 30. novembra 2026; ChatKit ostane na voljo. Viri: ChatKit · Napredne integracije s ChatKit · Hitri začetek za Python SDK · Uradna začetna aplikacija.

Zakaj ChatKit

Zgradil si agenta z Agents SDK. Teče v tvojem terminalu in nihče drug ga ne more uporabljati. Da bi ga dal v roke svojim uporabnikom, potrebuješ vmesnik za pogovor – gradnja dobrega uporabniškega vmesnika za klepet od nič pa je draga. Obdelati moraš drsenje, pretakanje sporočil, nadaljevanje pogovora, priloge, prikaz klicev orodij in obravnavo napak v omrežju.

ChatKit je odgovor OpenAI: komponenta za pogovor, ki jo vgradiš v svoj izdelek in ki poskrbi za celotno uporabniško izkušnjo. Dokumentacija poudarja interaktivne gradnike, predloge za začetek, prikaz klicev orodij, priloge in vizualizacijo razmišljanja agenta. Ti obdržiš nadzor nad tistim, kar je pomembno: agentom, svojimi podatki in svojimi pravili.

Dva načina napajanja

ChatKit je le vmesnik. Potrebuje strežnik, ki prejme sporočila, zažene agenta in vrne odgovor nazaj v toku. OpenAI opisuje dva pristopa:

PotKako delujeZa koga je
Tvoj lastni strežnik ChatKit (napredna integracija)Tvoj Python strežnik z uporabo SDK openai-chatkit prejme zahteve iz uporabniškega vmesnika in zažene agenta po tvoji izbiri, na primer agenta Agents SDKVsak nov projekt: to je pot, ki jo OpenAI priporoča
Potek dela v gostovanem Agent BuilderjuOpenAI izvaja potek dela, zasnovan v Agent Builderju; tvoj strežnik le ustvarja sejeObstoječe integracije v prehodnem obdobju: Agent Builder se izklopi 30. novembra 2026

Ta tečaj sledi prvi poti – edini, ki ima prihodnost. Drugo povzamemo na koncu lekcije za tiste, ki morajo do izklopa vzdrževati obstoječo integracijo.

Arhitektura iz treh delov

Integracija ChatKit se zreducira na tri elemente. Razlikovanje med njimi prepreči večino napak začetnikov:

  1. ChatKit.js, sama komponenta: spletna komponenta <openai-chatkit>, ki prikaže pogovor v iframeu. Naloži se z OpenAI-jevega CDN-ja (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), ne iz npm: paket npm @openai/chatkit vsebuje le njegove definicije tipov.
  2. Povezave za React, @openai/chatkit-react, ki izpostavljata komponento ChatKit in hook useChatKit. To je opcijsko: brez Reacta spletno komponento nadzoruješ neposredno.
  3. Tvoj strežnik ChatKit, ena sama končna točka HTTP, običajno /chatkit, ki prejme vse zahteve iz vmesnika. Instanca ChatKitServer jih usmerja, se zanaša na shrambo (store) za trajno shranjevanje niti pogovora in zažene tvojega agenta.

Ključ API za OpenAI nikoli ne zapusti strežnika: vmesnik komunicira le s tvojo končno točko /chatkit.

Namestitev

Na strani vmesnika namesti povezave za React in naloži skript ChatKit na svojo stran:

npm install @openai/chatkit-react
<!-- V <head> svoje strani -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Na strani strežnika namesti Python SDK za ChatKit (Python 3.10 ali novejši), ki vključuje Agents SDK, ter spletni strežnik:

pip install openai-chatkit fastapi uvicorn

Minimalni strežnik

Spodnji strežnik sledi uradnemu hitremu začetku. ChatKitServer zahteva le eno metodo, respond, ki se pokliče za vsako uporabniško sporočilo. Ponovno naloži zadnje elemente niti, jih pretvori v vhod za agenta z simple_to_agent_input, zažene agenta v načinu pretoka in ta pretok prevede v dogodke ChatKit z 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  # shramba v pomnilniku iz zač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]:
        # Zadnjih 30 elementov niti, obnovljenih v kronološkem vrstnem redu
        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")

Zaženi ga z OPENAI_API_KEY v svojem okolju: uvicorn main:app --port 8000.

Shramba (store) zasluži dve besedi. ChatKit sam ne shrani ničesar: niti, sporočila, gradnike in klice orodij trajno shrani razred, ki deduje od chatkit.store.Store in implementira približno ducat metod (load_thread, save_thread, load_thread_items, add_thread_item…). Za začetek ponovno uporabi datoteko memory_store.py iz uradne začetne aplikacije: vse ohrani v pomnilniku, dokler proces teče. V proizvodnji jo zamenjaj z bazo podatkov. Dokumentacija priporoča shranjevanje objektov kot JSON, da posodobitve SDK ne bodo vsiljevale selitev sheme.

Vmesnik React

Na strani vmesnika useChatKit prejme konfiguracijo in vrne objekt control, ki ga posreduješ komponenti ChatKit:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // V razvojnem okolju je dovolj nadomestna vrednost; v proizvodnji
      // uporabi svoj ključ domene (glej spodaj)
      domainKey: 'local-dev',
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

Vmesnik in /chatkit streži z istega izvora: v razvojnem okolju to opravi proxy tvojega orodja za gradnjo (začetna aplikacija konfigurira Viteov proxy za preusmeritev /chatkit na vrata 8000). Če strežnik deluje na drugem izvoru, ga izrecno dovoli, na primer s CORSMiddleware v FastAPI.

Brez Reacta

Spletno mesto WordPress, aplikacija Rails ali statična stran lahko integrirata istega asistenta: spletna komponenta deluje neposredno, ko se skript CDN naloži.

<!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>

Vsaka možnost, ki jo boš videl v naslednjih lekcijah, ima v obeh primerih enako obliko: objekt, posredovan funkciji useChatKit v Reactu ali metodi setOptions na spletni komponenti.

Varnost od prvega dne

Tri pravila, povzeta po vodniku za proizvodnjo ChatKit, veljajo že od faze prototipa:

  • Ključ API ostane na strežniku. Ne sme se pojaviti v kodi vmesnika ali v tvojem repozitoriju: preberi ga iz spremenljivke okolja ali upravitelja skrivnosti.
  • Avtenticiraj vsako zahtevo za /chatkit. SDK tega ne obravnava: tvoja aplikacija mora preveriti sejo ali žeton uporabnika, nato pa njegovo identiteto posredovati funkciji server.process v kontekstu (lekcija 21). Brez tega lahko kdorkoli zažene tvojega agenta na tvoje stroške.
  • Registriraj svoje domene. Preden greš v produkcijo, na strani Seznam dovoljenih domen na platformi OpenAI deklariraj vsako gostiteljsko ime, ki bo prikazovalo ChatKit, in kopiraj generirani ključ v domainKey. Ob nalaganju iframe ChatKit preveri ta ključ pri OpenAI in zavrne prikaz, če manjka ali se ne ujema.

Če že imaš potek dela v Agent Builderju

Obstoječe integracije, povezane z gostovanim potekom dela, delujejo do izklopa Agent Builderja. Njihovo načelo je drugačno: tvoj strežnik ustvari sejo ChatKit s klicem POST https://api.openai.com/v1/chatkit/sessions, z glavo OpenAI-Beta: chatkit_beta=v1, ID-jem poteka dela in identifikatorjem user, ki je edinstven za vsakega avtenticiranega uporabnika. Nato vrne pridobljeni client_secret vmesniku. Na strani vmesnika možnost api nato namesto URL-ja prevzame funkcijo getClientSecret.

Ne začni novega projekta s tem modelom. Za obstoječo integracijo izvozi potek dela v kodo Agents SDK in preklopi na svoj lastni strežnik ChatKit pred 30. novembrom 2026, tako da slediš vodniku Selitev iz Agent Builderja.

Ključne ugotovitve

  • ChatKit je vmesnik za pogovor, pripravljen za integracijo; tvoj strežnik poganja agenta
  • Za vsak nov projekt: tvoj lastni strežnik ChatKit (pip install openai-chatkit) z metodo respond in končno točko /chatkit; gostovani Agent Builder se izklopi 30. novembra 2026
  • Vmesnik se naloži z OpenAI-jevega CDN-ja; v Reactu uporabi useChatKit in <ChatKit control={control} /> iz @openai/chatkit-react
  • Shramba trajno hrani niti pogovora: v pomnilniku za testiranje, v bazi podatkov za proizvodnjo
  • Ključ API samo na strani strežnika, avtenticirana /chatkit, registrirane domene za pridobitev domainKey