ChatKit: Pārskats un instalēšana
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versija aprakstīja API, kas vairs nepastāv: objektu
new ChatKit({ apiKey, agentId }), komponentusChatProvider,ChatWindowunMessageInput, moduli@openai/chatkit/reactun skriptucdn.openai.com/chatkit/…. Šī nodarbība tagad seko oficiālajiem OpenAI ChatKit ceļvežiem, Python SDKopenai-chatkit1.6.5 un@openai/chatkit-react1.6.1. Mēs palaidām piemēra serveri lokāli, lai pārbaudītu katru soli. Piezīme: Agent Builder tiks slēgts 2026. gada 30. novembrī; ChatKit paliek pieejams. Avoti: ChatKit · Paplašināta integrācija ar ChatKit · Python SDK ātrais sākums · Oficiālā sākuma lietotne.
Kāpēc ChatKit
Tu esi izveidojis aģentu, izmantojot Agents SDK. Tas darbojas tavā terminālī, un neviens cits to nevar izmantot. Lai nodotu to lietotāju rokās, tev ir nepieciešams sarunu interfeiss, un laba čata lietotāja interfeisa izveide no nulles ir dārga. Tev ir jāapstrādā ritināšana, ziņojumu straumēšana, sarunu atsākšana, pielikumi, rīku izsaukumu attēlošana un tīkla kļūdu apstrāde.
ChatKit ir OpenAI atbilde: sarunu komponents, ko iegulsti savā produktā un kas nodrošina visu lietotāja pieredzi. Dokumentācija izceļ tā interaktīvos logrīkus, sākuma ieteikumus, rīku izsaukumu attēlošanu, pielikumus un aģenta spriešanas vizualizāciju. Tu saglabā kontroli pār to, kas ir svarīgi: aģentu, saviem datiem un saviem noteikumiem.
Divi veidi, kā to darbināt
ChatKit ir tikai interfeiss. Tam ir nepieciešams serveris, kas saņem ziņojumus, palaiž aģentu un atgriež atbildi plūsmas režīmā. OpenAI apraksta divas pieejas:
| Ceļš | Kā tas darbojas | Kam tas paredzēts |
|---|---|---|
| Tavs paša ChatKit serveris (paplašināta integrācija) | Tavs Python serveris, izmantojot SDK openai-chatkit, saņem pieprasījumus no lietotāja interfeisa un palaiž tavu izvēlēto aģentu, piemēram, Agents SDK aģentu | Jebkuram jaunam projektam: šis ir OpenAI ieteicamais ceļš |
| Mitināta Agent Builder darbplūsma | OpenAI palaiž darbplūsmu, kas izveidota Agent Builder; tavs serveris tikai izveido sesijas | Esošām integrācijām pārejas periodā: Agent Builder tiks slēgts 2026. gada 30. novembrī |
Šis kurss seko pirmajam ceļam — vienīgajam, kuram ir nākotne. Otru mēs īsi apkopojam nodarbības beigās tiem, kam līdz slēgšanas brīdim jāuztur esoša integrācija.
Trīs daļu arhitektūra
ChatKit integrācija reducējas uz trim elementiem. To atšķiršana novērš lielāko daļu iesācēju kļūdu:
- ChatKit.js, pats komponents: tīmekļa komponents
<openai-chatkit>, kas iframe rāmī attēlo sarunu. Tas tiek ielādēts no OpenAI CDN (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), nevis no npm: npm pakotne@openai/chatkitsatur tikai tās tipu definīcijas. - React saistījumi,
@openai/chatkit-react, kas eksponē komponentuChatKitun āķiuseChatKit. Tie ir opcionāli: bez React tu vari vadīt tīmekļa komponentu tieši. - Tavs ChatKit serveris, viens HTTP galapunkts, parasti
/chatkit, kas saņem visus pieprasījumus no interfeisa. InstancesChatKitServertos maršrutē, paļaujas uz krātuvi (store), lai saglabātu sarunu pavedienus, un palaiž tavu aģentu.
OpenAI API atslēga nekad neatstāj serveri: interfeiss sazinās tikai ar tavu /chatkit galapunktu.
Instalēšana
Interfeisa pusē instalē React saistījumus un ielādē ChatKit skriptu savā lapā:
npm install @openai/chatkit-react
<!-- Savas lapas <head> sadaļā -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Servera pusē instalē ChatKit Python SDK (Python 3.10 vai jaunāka versija), kas iekļauj Agents SDK, kā arī tīmekļa serveri:
pip install openai-chatkit fastapi uvicorn
Minimālais serveris
Zemāk esošais serveris seko oficiālajam ātrajam sākumam. ChatKitServer prasa tikai vienu metodi, respond, ko izsauc katram lietotāja ziņojumam. Tā atkārtoti ielādē jaunākos pavediena elementus, konvertē tos par aģenta ievadi, izmantojot simple_to_agent_input, palaiž aģentu straumēšanas režīmā un pārvērš šo plūsmu ChatKit notikumos, izmantojot 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 # iekšējās atmiņas krātuve no sākuma lietotnes
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]:
# Pēdējie 30 pavediena elementi, atjaunoti hronoloģiskā secībā
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")
Palaid to ar OPENAI_API_KEY savā vidē: uvicorn main:app --port 8000.
Par krātuvi (store) vērts teikt pāris vārdus. ChatKit pats neko neglabā: pavedienus, ziņojumus, logrīkus un rīku izsaukumus saglabā klase, kas mantota no chatkit.store.Store un ievieš aptuveni duci metožu (load_thread, save_thread, load_thread_items, add_thread_item…). Lai sāktu, atkārtoti izmanto failu memory_store.py no oficiālās sākuma lietotnes: tas glabā visu operatīvajā atmiņā, kamēr process darbojas. Ražošanas vidē aizstāj to ar datubāzi. Dokumentācija iesaka objektus glabāt kā JSON, lai SDK atjauninājumi tev neuzspiestu shēmas migrācijas.
React interfeiss
Interfeisa pusē useChatKit saņem konfigurāciju un atgriež objektu control, ko nodod komponentam ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Izstrādes vidē pietiek ar rezervētu vērtību; ražošanā
// izmanto savu domēna atslēgu (skatīt zemāk)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Apkalpo interfeisu un /chatkit no viena un tā paša avota: izstrādes vidē to nodrošina tava būves rīka starpniekserveris (sākuma lietotnē Vite starpniekserveris ir konfigurēts novirzīt /chatkit uz portu 8000). Ja serveris atrodas citā avotā, atļauj to tieši, piemēram, izmantojot FastAPI CORSMiddleware.
Bez React
WordPress vietne, Rails lietotne vai statiska lapa var integrēt to pašu asistentu: tīmekļa komponents darbojas tieši, tiklīdz CDN skripts ir ielādēts.
<!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>
Katrai opcijai, ko redzēsi turpmākajās nodarbībās, ir vienāda forma abos gadījumos: objekts, kas padots useChatKit React vidē vai setOptions tīmekļa komponentam.
Drošība no pirmās dienas
Trīs noteikumi, kas izriet no ChatKit ražošanas ceļveža, attiecas jau no prototipa posma:
- API atslēga paliek serverī. Tai nav jāparādās interfeisa kodā vai tavā repozitorijā: lasi to no vides mainīgā vai noslēpumu pārvaldnieka.
- Autentificē katru pieprasījumu uz
/chatkit. SDK to neapstrādā: tavai lietotnei ir jāpārbauda lietotāja sesija vai žetons un pēc tam jānodod tā identitāteserver.processkontekstā (21. nodarbība). Bez tā ikviens varēs darbināt tavu aģentu uz taviem izdevumiem. - Reģistrē savus domēnus. Pirms došanās tiešsaistē deklarē katru resursdatora nosaukumu, kurā tiks attēlots ChatKit, OpenAI platformas lapā Domain allowlist un nokopē ģenerēto atslēgu uz
domainKey. Ielādes brīdī ChatKit iframe rāmis pārbauda šo atslēgu pie OpenAI un atsakās attēloties, ja tā trūkst vai nesakrīt.
Ja tev jau ir Agent Builder darbplūsma
Esošas integrācijas, kas piesaistītas mitinātai darbplūsmai, darbojas līdz Agent Builder slēgšanai. To princips atšķiras: tavs serveris izveido ChatKit sesiju, izsaucot POST https://api.openai.com/v1/chatkit/sessions, ar galveni OpenAI-Beta: chatkit_beta=v1, darbplūsmas ID un user identifikatoru, kas ir unikāls katram autentificētam lietotājam. Tad tas atgriež iegūto client_secret interfeisam. Interfeisa pusē opcija api tad pieņem funkciju getClientSecret URL vietā.
Nesāc jaunus projektus, balstoties uz šo modeli. Esošai integrācijai eksportē darbplūsmu uz Agents SDK kodu un pārej uz savu ChatKit serveri pirms 2026. gada 30. novembra, sekojot ceļvedim Migrate from Agent Builder.
Galvenās atziņas
- ChatKit ir gatavs integrēšanai sarunu interfeiss; tavu aģentu darbina tavs serveris
- Jebkuram jaunam projektam: tavs paša ChatKit serveris (
pip install openai-chatkit) ar metodirespondun galapunktu/chatkit; mitinātais Agent Builder tiks slēgts 2026. gada 30. novembrī - Interfeiss tiek ielādēts no OpenAI CDN; React vidē izmanto
useChatKitun<ChatKit control={control} />no@openai/chatkit-react - Krātuve saglabā sarunu pavedienus: testēšanai operatīvajā atmiņā, ražošanā datubāzē
- API atslēga tikai servera pusē, autentificēts
/chatkit, reģistrēti domēni, lai iegūtudomainKey