ChatKit: Επισκόπηση και Εγκατάσταση
Σε αυτήν τη σελίδα
Μάθημα ξαναγραμμένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση περιέγραφε ένα API που δεν υπάρχει πλέον: ένα αντικείμενο
new ChatKit({ apiKey, agentId }), τα componentsChatProvider,ChatWindowκαιMessageInput, ένα module@openai/chatkit/reactκαι ένα scriptcdn.openai.com/chatkit/…. Αυτό το μάθημα ακολουθεί πλέον τους επίσημους οδηγούς του OpenAI ChatKit, το Python SDKopenai-chatkit1.6.5 και το@openai/chatkit-react1.6.1. Εκτελέσαμε τον παραδειγματικό server τοπικά για να επαληθεύσουμε κάθε βήμα. Σημείωση: Το Agent Builder θα κλείσει στις 30 Νοεμβρίου 2026· το ChatKit παραμένει διαθέσιμο. Πηγές: ChatKit · Προχωρημένες ενσωματώσεις με το ChatKit · Γρήγορη εκκίνηση Python SDK · Επίσημη εφαρμογή εκκίνησης.
Γιατί το ChatKit
Έχετε δημιουργήσει έναν πράκτορα με το Agents SDK. Εκτελείται στο τερματικό σας και κανείς άλλος δεν μπορεί να τον χρησιμοποιήσει. Για να τον θέσετε στα χέρια των χρηστών σας, χρειάζεστε μια διεπαφή συνομιλίας—και η δημιουργία μιας καλής διεπαφής chat από το μηδέν είναι δαπανηρή. Πρέπει να διαχειριστείτε την κύλιση, τη ροή μηνυμάτων (streaming), την επανέναρξη συνομιλιών, τα συνημμένα, την εμφάνιση κλήσεων εργαλείων και τον χειρισμό σφαλμάτων δικτύου.
Το ChatKit είναι η απάντηση του OpenAI: ένα component συνομιλίας που ενσωματώνετε στο προϊόν σας και διαχειρίζεται ολόκληρη την εμπειρία χρήστη. Η τεκμηρίωση αναδεικνύει τα διαδραστικά widgets, τις προτάσεις έναρξης, την εμφάνιση κλήσεων εργαλείων, τα συνημμένα και την οπτικοποίηση της συλλογιστικής του πράκτορα. Εσείς διατηρείτε τον έλεγχο σε ό,τι έχει σημασία: τον πράκτορα, τα δεδομένα σας και τους κανόνες σας.
Δύο τρόποι τροφοδοσίας του
Το ChatKit είναι απλώς μια διεπαφή. Χρειάζεται έναν server που λαμβάνει μηνύματα, εκτελεί τον πράκτορα και επιστρέφει τη ροή της απάντησης. Το OpenAI περιγράφει δύο προσεγγίσεις:
| Διαδρομή | Πώς λειτουργεί | Για ποιον προορίζεται |
|---|---|---|
| Ο δικός σας server ChatKit (προχωρημένη ενσωμάτωση) | Ο Python server σας, χρησιμοποιώντας το SDK openai-chatkit, λαμβάνει αιτήματα από τη διεπαφή και εκτελεί τον πράκτορα της επιλογής σας, όπως έναν πράκτορα Agents SDK | Κάθε νέο έργο: αυτή είναι η διαδρομή που προτείνει το OpenAI |
| Ροή εργασίας Hosted Agent Builder | Το OpenAI εκτελεί μια ροή εργασίας σχεδιασμένη στο Agent Builder· ο server σας δημιουργεί μόνο συνεδρίες | Υφιστάμενες ενσωματώσεις κατά την περίοδο μετάβασης: το Agent Builder κλείνει στις 30 Νοεμβρίου 2026 |
Αυτό το μάθημα ακολουθεί την πρώτη διαδρομή—τη μοναδική με μέλλον. Συνοψίζουμε τη δεύτερη στο τέλος του μαθήματος για όσους χρειάζεται να συντηρήσουν μια υφιστάμενη ενσωμάτωση μέχρι την παύση λειτουργίας της.
Η αρχιτεκτονική τριών μερών
Μια ενσωμάτωση ChatKit ανάγεται σε τρία στοιχεία. Η διάκρισή τους αποφεύγει τα περισσότερα λάθη αρχαρίων:
- ChatKit.js, το ίδιο το component: ένα web component
<openai-chatkit>που εμφανίζει τη συνομιλία σε ένα iframe. Φορτώνεται από το CDN του OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), όχι από το npm: το πακέτο npm@openai/chatkitπεριέχει μόνο τους ορισμούς τύπων του. - Δεσμεύσεις React,
@openai/chatkit-react, που εκθέτουν το componentChatKitκαι το hookuseChatKit. Αυτά είναι προαιρετικά: χωρίς React, ελέγχετε απευθείας το web component. - Ο server ChatKit σας, ένα μοναδικό endpoint HTTP, συμβατικά το
/chatkit, που λαμβάνει όλα τα αιτήματα από τη διεπαφή. Μια παρουσίαChatKitServerτα δρομολογεί, βασίζεται σε μια αποθήκη (store) για την επιμονή των νημάτων συνομιλίας και εκτελεί τον πράκτορά σας.
Το κλειδί API του OpenAI δεν εγκαταλείπει ποτέ τον server: η διεπαφή μιλά μόνο στο endpoint /chatkit σας.
Εγκατάσταση
Στην πλευρά της διεπαφής, εγκαταστήστε τις δεσμεύσεις React και φορτώστε το script ChatKit στη σελίδα σας:
npm install @openai/chatkit-react
<!-- Στο <head> της σελίδας σας -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Στην πλευρά του server, εγκαταστήστε το Python SDK ChatKit (Python 3.10 ή νεότερη), το οποίο περιλαμβάνει το Agents SDK, καθώς και έναν web server:
pip install openai-chatkit fastapi uvicorn
Ο ελάχιστος server
Ο παρακάτω server ακολουθεί την επίσημη γρήγορη εκκίνηση. Το ChatKitServer απαιτεί μόνο μία μέθοδο, την respond, η οποία καλείται για κάθε μήνυμα χρήστη. Φορτώνει τα τελευταία στοιχεία του νήματος, τα μετατρέπει σε είσοδο πράκτορα με το simple_to_agent_input, εκτελεί τον πράκτορα σε λειτουργία ροής (streaming) και μεταφράζει αυτή τη ροή σε συμβάντα ChatKit με το 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 από την 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]:
# Τα τελευταία 30 στοιχεία του νήματος, αποκατεστημένα σε χρονολογική σειρά
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")
Εκτελέστε το με το OPENAI_API_KEY στο περιβάλλον σας: uvicorn main:app --port 8000.
Η αποθήκη (store) αξίζει δύο λόγια. Το ChatKit δεν αποθηκεύει τίποτα μόνο του: τα νήματα, τα μηνύματα, τα widgets και οι κλήσεις εργαλείων επιμένουν από μια κλάση που κληρονομεί από την chatkit.store.Store και υλοποιεί περίπου δώδεκα μεθόδους (load_thread, save_thread, load_thread_items, add_thread_item…). Για να ξεκινήσετε, επαναχρησιμοποιήστε το αρχείο memory_store.py από την επίσημη εφαρμογή εκκίνησης: διατηρεί τα πάντα στη μνήμη όσο η διαδικασία εκτελείται. Στην παραγωγή, αντικαταστήστε το με μια βάση δεδομένων. Η τεκμηρίωση προτείνει την αποθήκευση αντικειμένων ως JSON ώστε οι ενημερώσεις του SDK να μην σας επιβάλλουν μεταναστεύσεις σχήματος.
Η διεπαφή React
Στην πλευρά της διεπαφής, το useChatKit λαμβάνει τη διαμόρφωση και επιστρέφει ένα αντικείμενο control, το οποίο περνάτε στο component ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Στην ανάπτυξη, μια τιμή placeholder αρκεί· στην παραγωγή,
// χρησιμοποιήστε το κλειδί τομέα σας (δείτε παρακάτω)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Εξυπηρετήστε τη διεπαφή και το /chatkit από την ίδια προέλευση: στην ανάπτυξη, το proxy του εργαλείου δόμησής σας το χειρίζεται αυτό (η starter app διαμορφώνει το proxy του Vite για ανακατεύθυνση του /chatkit στη θύρα 8000). Αν ο server βρίσκεται σε διαφορετική προέλευση, επιτρέψτε το ρητά, για παράδειγμα με το CORSMiddleware του FastAPI.
Χωρίς React
Μια ιστοσελίδα WordPress, μια εφαρμογή Rails ή μια στατική σελίδα μπορούν να ενσωματώσουν τον ίδιο βοηθό: το web component λειτουργεί απευθείας μόλις φορτώσει το script CDN.
<!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>
Κάθε επιλογή που θα δείτε στα επόμενα μαθήματα έχει την ίδια μορφή και στις δύο περιπτώσεις: ένα αντικείμενο που περνιέται στο useChatKit στο React, ή στο setOptions στο web component.
Ασφάλεια από την πρώτη μέρα
Τρεις κανόνες, αντλημένοι από τον οδηγό παραγωγής του ChatKit, ισχύουν από το στάδιο του πρωτοτύπου:
- Το κλειδί API παραμένει στον server. Δεν πρέπει να εμφανίζεται στον κώδικα της διεπαφής ή στο αποθετήριό σας: διαβάστε το από μια μεταβλητή περιβάλλοντος ή έναν διαχειριστή μυστικών.
- Πιστοποιήστε κάθε αίτημα στο
/chatkit. Το SDK δεν το χειρίζεται αυτό: η εφαρμογή σας πρέπει να επαληθεύει τη συνεδρία ή το token του χρήστη και στη συνέχεια να περνά την ταυτότητά του στοserver.processστο πλαίσιο (μάθημα 21). Χωρίς αυτό, ο καθένας μπορεί να εκτελέσει τον πράκτορά σας με δικά σας έξοδα. - Καταχωρίστε τους τομείς σας. Πριν τη δημοσίευση, δηλώστε κάθε όνομα host που θα εμφανίζει το ChatKit στη σελίδα Domain allowlist της πλατφόρμας OpenAI και αντιγράψτε το παραγόμενο κλειδί στο
domainKey. Κατά τη φόρτωση, το iframe του ChatKit επαληθεύει αυτό το κλειδί με το OpenAI και αρνείται να εμφανιστεί αν λείπει ή δεν ταιριάζει.
Αν έχετε ήδη μια ροή εργασίας Agent Builder
Οι υφιστάμενες ενσωματώσεις συνδεδεμένες με μια φιλοξενούμενη ροή εργασίας λειτουργούν μέχρι να κλείσει το Agent Builder. Η αρχή τους διαφέρει: ο server σας δημιουργεί μια συνεδρία ChatKit καλώντας το POST https://api.openai.com/v1/chatkit/sessions, με την κεφαλίδα OpenAI-Beta: chatkit_beta=v1, το ID της ροής εργασίας και ένα αναγνωριστικό user μοναδικό για κάθε πιστοποιημένο χρήστη. Στη συνέχεια επιστρέφει το client_secret που αποκτήθηκε στη διεπαφή. Στην πλευρά της διεπαφής, η επιλογή api λαμβάνει τότε μια συνάρτηση getClientSecret αντί για ένα URL.
Μην ξεκινήσετε νέο έργο με αυτό το μοντέλο. Για μια υφιστάμενη ενσωμάτωση, εξάγετε τη ροή εργασίας σε κώδικα Agents SDK και μεταβείτε στον δικό σας server ChatKit πριν από τις 30 Νοεμβρίου 2026, ακολουθώντας τον οδηγό Migrate from Agent Builder.
Βασικά σημεία
- Το ChatKit είναι μια έτοιμη προς ενσωμάτωση διεπαφή συνομιλίας· ο server σας εκτελεί τον πράκτορα
- Για κάθε νέο έργο: ο δικός σας server ChatKit (
pip install openai-chatkit), με μια μέθοδοrespondκαι ένα endpoint/chatkit· το φιλοξενούμενο Agent Builder κλείνει στις 30 Νοεμβρίου 2026 - Η διεπαφή φορτώνεται από το CDN του OpenAI· στο React, χρησιμοποιήστε το
useChatKitκαι το<ChatKit control={control} />από το@openai/chatkit-react - Η αποθήκη (store) επιμένει τα νήματα συνομιλίας: στη μνήμη για δοκιμές, σε βάση δεδομένων για παραγωγή
- Κλειδί API μόνο στην πλευρά του server, πιστοποιημένο
/chatkit, καταχωρημένοι τομείς για απόκτηση τουdomainKey