ChatKit: Panoramica e installazione
In questa pagina
Lezione riscritta il 3 novembre 2026. La versione precedente descriveva un’API che non esiste più: un oggetto
new ChatKit({ apiKey, agentId }), i componentiChatProvider,ChatWindoweMessageInput, un modulo@openai/chatkit/reacte uno scriptcdn.openai.com/chatkit/…. Questa lezione segue ora le guide ufficiali di OpenAI ChatKit, la SDK Pythonopenai-chatkit1.6.5 e@openai/chatkit-react1.6.1. Abbiamo eseguito il server di esempio in locale per verificare ogni passaggio. Nota: Agent Builder chiuderà il 30 novembre 2026; ChatKit rimarrà disponibile. Fonti: ChatKit · Integrazioni avanzate con ChatKit · Quickstart della SDK Python · App starter ufficiale.
Perché ChatKit
Hai costruito un agente con la SDK Agents. Funziona nel tuo terminale, ma nessun altro può usarlo. Per metterlo nelle mani dei tuoi utenti, hai bisogno di un’interfaccia di conversazione: costruire una buona UI di chat da zero è costoso. Devi gestire lo scorrimento, lo streaming dei messaggi, la ripresa della conversazione, gli allegati, la visualizzazione delle chiamate agli strumenti e la gestione degli errori di rete.
ChatKit è la risposta di OpenAI: un componente di conversazione che incorpori nel tuo prodotto e che gestisce l’intera esperienza utente. La documentazione ne evidenzia i widget interattivi, i suggerimenti iniziali, la visualizzazione delle chiamate agli strumenti, gli allegati e la visualizzazione del ragionamento dell’agente. Tu mantieni il controllo su ciò che conta: l’agente, i tuoi dati e le tue regole.
Due modi per alimentarlo
ChatKit è solo un’interfaccia. Ha bisogno di un server che riceva i messaggi, esegua l’agente e ritorni la risposta in streaming. OpenAI descrive due approcci:
| Percorso | Come funziona | A chi è rivolto |
|---|---|---|
| Il tuo server ChatKit (integrazione avanzata) | Il tuo server Python, usando la SDK openai-chatkit, riceve le richieste dall’UI ed esegue l’agente di tua scelta, come un agente della SDK Agents | Qualsiasi nuovo progetto: questo è il percorso raccomandato da OpenAI |
| Flusso di lavoro Agent Builder ospitato | OpenAI esegue un flusso di lavoro progettato in Agent Builder; il tuo server crea solo le sessioni | Integrazioni esistenti durante il periodo di transizione: Agent Builder chiuderà il 30 novembre 2026 |
Questo corso segue il primo percorso, l’unico con un futuro. Riassumiamo il secondo alla fine della lezione per chi deve mantenere un’integrazione esistente fino alla chiusura.
L’architettura a tre pezzi
Un’integrazione ChatKit si riduce a tre elementi. Distinguerli evita la maggior parte degli errori da principiante:
- ChatKit.js, il componente stesso: un web component
<openai-chatkit>che visualizza la conversazione in un iframe. Viene caricato dalla CDN di OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), non da npm: il pacchetto npm@openai/chatkitcontiene solo le sue definizioni di tipo. - Binding React,
@openai/chatkit-react, che espongono il componenteChatKite l’hookuseChatKit. Sono opzionali: senza React, controlli direttamente il web component. - Il tuo server ChatKit, un singolo endpoint HTTP, convenzionalmente
/chatkit, che riceve tutte le richieste dall’interfaccia. Un’istanzaChatKitServerle instrada, si affida a un store per persistere i thread di conversazione ed esegue il tuo agente.
La chiave API di OpenAI non lascia mai il server: l’interfaccia parla solo al tuo endpoint /chatkit.
Installazione
Lato interfaccia, installa i binding React e carica lo script ChatKit nella tua pagina:
npm install @openai/chatkit-react
<!-- Nell'<head> della tua pagina -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Lato server, installa la SDK Python di ChatKit (Python 3.10 o successivo), che include la SDK Agents, più un server web:
pip install openai-chatkit fastapi uvicorn
Il server minimale
Il server seguente segue il quickstart ufficiale. ChatKitServer richiede un solo metodo, respond, chiamato per ogni messaggio dell’utente. Ricarica gli ultimi elementi del thread, li converte in input per l’agente con simple_to_agent_input, esegue l’agente in modalità streaming e traduce quello stream in eventi ChatKit con 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 # store in-memory dall'app starter
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]:
# Gli ultimi 30 elementi del thread, ripristinati in ordine cronologico
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")
Eseguilo con OPENAI_API_KEY nel tuo ambiente: uvicorn main:app --port 8000.
Lo store merita due parole. ChatKit non memorizza nulla di per sé: thread, messaggi, widget e chiamate agli strumenti sono persistiti da una classe che ereda da chatkit.store.Store e implementa circa una dozzina di metodi (load_thread, save_thread, load_thread_items, add_thread_item…). Per iniziare, riutilizza il file memory_store.py dall’app starter ufficiale: mantiene tutto in memoria mentre il processo è in esecuzione. In produzione, sostituiscilo con un database. La documentazione consiglia di memorizzare gli oggetti come JSON così gli aggiornamenti della SDK non ti forzano a migrazioni dello schema.
L’interfaccia React
Lato interfaccia, useChatKit riceve la configurazione e restituisce un oggetto control, che passi al componente ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// In sviluppo, un valore segnaposto è sufficiente; in produzione,
// usa la tua chiave di dominio (vedi sotto)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Servi l’interfaccia e /chatkit dalla stessa origine: in sviluppo, il proxy del tuo strumento di build se ne occupa (l’app starter configura il proxy di Vite per reindirizzare /chatkit alla porta 8000). Se il server vive su un’origine diversa, consentilo esplicitamente, ad esempio con CORSMiddleware di FastAPI.
Senza React
Un sito WordPress, un’applicazione Rails o una pagina statica possono integrare lo stesso assistente: il web component funziona direttamente una volta caricato lo 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>
Ogni opzione che vedrai nelle lezioni seguenti ha la stessa forma in entrambi i casi: un oggetto passato a useChatKit in React, o a setOptions sul web component.
Sicurezza fin dal primo giorno
Tre regole, tratte dalla guida alla produzione di ChatKit, si applicano già dalla fase di prototipo:
- La chiave API rimane sul server. Non deve apparire nel codice dell’interfaccia né nel tuo repository: leggila da una variabile d’ambiente o da un gestore di segreti.
- Autentica ogni richiesta a
/chatkit. La SDK non se ne occupa: la tua applicazione deve verificare la sessione o il token dell’utente, poi passare la sua identità aserver.processnel contesto (lezione 21). Senza questo, chiunque può eseguire il tuo agente a tue spese. - Registra i tuoi domini. Prima di andare online, dichiara ogni hostname che mostrerà ChatKit sulla pagina Domain allowlist della piattaforma OpenAI e copia la chiave generata in
domainKey. Al caricamento, l’iframe di ChatKit verifica questa chiave con OpenAI e si rifiuta di visualizzarsi se manca o non corrisponde.
Se hai già un flusso di lavoro Agent Builder
Le integrazioni esistenti agganciate a un flusso di lavoro ospitato funzionano fino alla chiusura di Agent Builder. Il loro principio differisce: il tuo server crea una sessione ChatKit chiamando POST https://api.openai.com/v1/chatkit/sessions, con l’header OpenAI-Beta: chatkit_beta=v1, l’ID del flusso di lavoro e un identificatore user unico per ogni utente autenticato. Restituisce poi il client_secret ottenuto all’interfaccia. Lato interfaccia, l’opzione api prende allora una funzione getClientSecret invece di un URL.
Non avviare un nuovo progetto su questo modello. Per un’integrazione esistente, esporta il flusso di lavoro in codice Agents SDK e passa al tuo server ChatKit prima del 30 novembre 2026, seguendo la guida Migrate from Agent Builder.
Punti chiave
- ChatKit è un’interfaccia di conversazione pronta all’integrazione; il tuo server esegue l’agente
- Per qualsiasi nuovo progetto: il tuo server ChatKit (
pip install openai-chatkit), con un metodoresponde un endpoint/chatkit; l’Agent Builder ospitato chiuderà il 30 novembre 2026 - L’interfaccia si carica dalla CDN di OpenAI; in React, usa
useChatKite<ChatKit control={control} />da@openai/chatkit-react - Lo store persiste i thread di conversazione: in memoria per i test, in un database per la produzione
- Chiave API solo lato server,
/chatkitautenticato, domini registrati per ottenere ladomainKey