ChatKit: apžvalga ir diegimas
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija aprašė API, kuris nebeegzistuoja: objektą
new ChatKit({ apiKey, agentId }), komponentusChatProvider,ChatWindowirMessageInput, modulį@openai/chatkit/reactbei scenarijųcdn.openai.com/chatkit/…. Ši pamoka dabar remiasi oficialiais „OpenAI“ ChatKit vadovais, Python SDKopenai-chatkit1.6.5 ir@openai/chatkit-react1.6.1. Pavyzdinį serverį paleidome lokaliai, kad patikrintume kiekvieną žingsnį. Pastaba: „Agent Builder“ bus uždarytas 2026 m. lapkričio 30 d.; ChatKit išliks prieinamas. Šaltiniai: ChatKit · Pažangios integracijos su ChatKit · Python SDK greitas startas · Oficiali starterio programa.
Kodėl ChatKit
Sukūrei agentą naudodamas Agents SDK. Jis veikia tavo terminale, ir niekas kitas jo naudoti negali. Norėdamas jį perduoti naudotojams, tau reikia pokalbių sąsajos, o geros pokalbių sąsajos kūrimas nuo nulio yra brangus. Turi tvarkyti slinkimą, žinučių srautinį perdavimą, pokalbio atnaujinimą, priedus, įrankių iškvietimų rodymą ir tinklo klaidų apdorojimą.
ChatKit yra „OpenAI“ atsakymas: pokalbių komponentas, kurį įterpi į savo produktą ir kuris perima visą naudotojo patirtį. Dokumentacijoje pabrėžiami interaktyvūs valdikliai, pradiniai pasiūlymai, įrankių iškvietimų rodymas, priedai ir agento samprotavimų vizualizacija. Tu išlaikai kontrolę over tai, kas svarbu: agento, savo duomenų ir savo taisyklių.
Du būdai jį valdyti
ChatKit yra tik sąsaja. Jam reikia serverio, kuris gauna žinutes, paleidžia agentą ir srautiniu būdu grąžina atsakymą. „OpenAI“ aprašo du būdus:
| Kelias | Kaip tai veikia | Kam skirta |
|---|---|---|
| Tavo nuosavas ChatKit serveris (pažangi integracija) | Tavo Python serveris, naudojantis openai-chatkit SDK, gauna užklausas iš sąsajos ir paleidžia tavo pasirinktą agentą, pavyzdžiui, Agents SDK agentą | Bet koks naujas projektas: tai yra „OpenAI“ rekomenduojamas kelias |
| Prieglobos „Agent Builder“ darbo eiga | „OpenAI“ paleidžia „Agent Builder“ sukurtą darbo eigą; tavo serveris tik kuria sesijas | Esamos integracijos pereinamuoju laikotarpiu: „Agent Builder“ bus uždarytas 2026 m. lapkričio 30 d. |
Šiame kurse seka pirmąjį kelią – vienintelį, turintį ateitį. Antrojo santrauką pateikiame pamokos pabaigoje tiems, kuriems reikia prižiūrėti esamą integraciją iki uždarymo.
Trijų dalių architektūra
ChatKit integraciją sudaro trys elementai. Jų atskyrimas padeda išvengti daugelio pradedančiųjų klaidų:
- ChatKit.js, pats komponentas: žiniatinklio komponentas
<openai-chatkit>, rodantis pokalbį iframe. Jis užkraunamas iš „OpenAI“ CDN (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), o ne iš npm: npm paketas@openai/chatkitturi tik jo tipų apibrėžimus. - React saitai,
@openai/chatkit-react, kurie pateikia komponentąChatKitir hook’ąuseChatKit. Tai neprivaloma: be React tiesiogiai valdai žiniatinklio komponentą. - Tavo ChatKit serveris, vienas HTTP galinis taškas, pagal susitarimą
/chatkit, gaunantis visas sąsajos užklausas.ChatKitServeregzempliorius jas maršrutizuoja, naudoja saugyklą pokalbių gijoms išsaugoti ir paleidžia tavo agentą.
„OpenAI“ API raktas niekada neišeina iš serverio: sąsaja bendrauja tik su tavo /chatkit galiniu tašku.
Diegimas
Sąsajos pusėje įdiek React saitus ir įkelk ChatKit scenarijų į savo puslapį:
npm install @openai/chatkit-react
<!-- Savo puslapio <head> dalyje -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Serverio pusėje įdiek ChatKit Python SDK (Python 3.10 ar naujesnė versija), kuris įtraukia Agents SDK, bei žiniatinklio serverį:
pip install openai-chatkit fastapi uvicorn
Minimalus serveris
Toliau pateiktas serveris atitinka oficialų greitą startą. ChatKitServer reikia tik vieno metodo, respond, kuris kviečiamas kiekvienam naudotojo pranešimui. Jis iš naujo įkelia naujausius gijos elementus, konvertuoja juos į agento įvestį naudodamas simple_to_agent_input, paleidžia agentą srautiniu režimu ir tą srautą verčia į ChatKit įvykius naudodamas 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 # atmintyje laikoma saugykla iš starterio programos
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]:
# Paskutiniai 30 gijos elementų, atkurti chronologine tvarka
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")
Paleisk jį su OPENAI_API_KEY savo aplinkoje: uvicorn main:app --port 8000.
Saugykla nusipelno dviejų žodžių. ChatKit nieko nesaugo pati: gijas, žinutes, valdiklius ir įrankių iškvietimus išsaugo klasė, paveldima iš chatkit.store.Store ir įgyvendinanti apie дюжинą metodų (load_thread, save_thread, load_thread_items, add_thread_item…). Pradžiai pakartotinai naudok memory_store.py failą iš oficialios starterio programos: jis viską laiko atmintyje, kol vyksta procesas. Gamyboje pakeisk jį duomenų baze. Dokumentacijoje rekomenduojama objektus saugoti kaip JSON, kad SDK atnaujinimai nepriverstų tavęs atlikti schemos migracijų.
React sąsaja
Sąsajos pusėje useChatKit gauna konfigūraciją ir grąžina control objektą, kurį perduodi komponentui ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Kūrimo metu pakanka rezervuotos reikšmės; gamyboje
// naudok savo domeno raktą (žr. toliau)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Tiek sąsają, tiek /chatkit tiek iš to paties šaltinio: kūrimo metu tai tvarko tavo kūrimo įrankio proxy (starterio programa sukonfigūruoja Vite proxy nukreipti /chatkit į 8000 prievadą). Jei serveris yra kitame šaltinyje, aiškiai jį leisk, pavyzdžiui, naudodamas FastAPI CORSMiddleware.
Be React
„WordPress“ svetainė, „Rails“ programa ar statinis puslapis gali integruoti tą patį asistentą: žiniatinklio komponentas veikia tiesiogiai, kai tik užkraunamas CDN scenarijus.
<!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>
Kiekviena parinktis, kurią matysi kitose pamokose, abiem atvejais yra tokia pati: objektas, perduodamas useChatKit React aplinkoje arba setOptions žiniatinklio komponente.
Saugumas nuo pirmos dienos
Trys taisyklės, paimtos iš ChatKit gamybos vadovo, taikomos nuo prototipo kūrimo etapo:
- API raktas lieka serveryje. Jis neturi atsirasti sąsajos kode ar tavo saugykloje: skaityk jį iš aplinkos kintamojo arba paslapčių valdytojo.
- Autentifikuok kiekvieną užklausą į
/chatkit. SDK to nedaro: tavo programa turi patikrinti naudotojo sesiją arba žetoną, tada perduoti jo tapatybęserver.processkontekste (21 pamoka). Be to bet kas gali paleisti tavo agentą tavo lėšomis. - Registruok savo domenus. Prieš paleisdami gamyboje, deklaruok kiekvieną prieglobos vardą, kuris rodys ChatKit „OpenAI“ platformos puslapyje Domain allowlist, ir nukopijuok sugeneruotą raktą į
domainKey. Užkraunant ChatKit iframe patikrina šį raktą su „OpenAI“ ir atsisako rodyti, jei jo trūksta arba jis nesutampa.
Jei jau turi „Agent Builder“ darbo eigą
Esamos integracijos, prijungtos prie prieglobos darbo eigos, veikia iki „Agent Builder“ uždarymo. Jų principas skiriasi: tavo serveris sukuria ChatKit sesiją kviesdamas POST https://api.openai.com/v1/chatkit/sessions, su antrašte OpenAI-Beta: chatkit_beta=v1, darbo eigos ID ir user identifikatoriumi, unikaliu kiekvienam autentifikuotam naudotojui. Tada jis grąžina gautą client_secret sąsajai. Sąsajos pusėje api parinktis tada naudoja getClientSecret funkciją vietoj URL.
Nepradėk naujo projekto pagal šį modelį. Esamai integracijai eksportuok darbo eigą į Agents SDK kodą ir pereik prie savo ChatKit serverio iki 2026 m. lapkričio 30 d., laikydamasis Migrate from Agent Builder vadovo.
Svarbiausi punktai
- ChatKit yra paruošta integruoti pokalbių sąsaja; tavo serveris paleidžia agentą
- Bet kokiam naujam projektui: tavo nuosavas ChatKit serveris (
pip install openai-chatkit), surespondmetodu ir/chatkitgaliniu tašku; prieglobos „Agent Builder“ bus uždarytas 2026 m. lapkričio 30 d. - Sąsaja užkraunama iš „OpenAI“ CDN; React aplinkoje naudok
useChatKitir<ChatKit control={control} />iš@openai/chatkit-react - Saugykla išsaugo pokalbių gijas: atmintyje testavimui, duomenų bazėje gamyboje
- API raktas tik serveryje, autentifikuotas
/chatkit, registruoti domenaidomainKeygauti