ChatKit: visión general e instalación
En esta página
Lección reescrita el 3 de noviembre de 2026. La versión anterior describía una API que ya no existe: un objeto
new ChatKit({ apiKey, agentId }), los componentesChatProvider,ChatWindowyMessageInput, un módulo@openai/chatkit/reacty un scriptcdn.openai.com/chatkit/…. Esta lección sigue ahora las guías oficiales de OpenAI ChatKit, el SDK de Pythonopenai-chatkit1.6.5 y@openai/chatkit-react1.6.1. Hemos ejecutado el servidor de ejemplo localmente para verificar cada paso. Nota: Agent Builder se apagará el 30 de noviembre de 2026; ChatKit seguirá disponible. Fuentes: ChatKit · Integraciones avanzadas con ChatKit · Inicio rápido del SDK de Python · Aplicación de inicio oficial.
Por qué ChatKit
Has creado un agente con el Agents SDK. Se ejecuta en tu terminal y nadie más puede usarlo. Para ponerlo en manos de tus usuarios, necesitas una interfaz de conversación; y construir una buena interfaz de chat desde cero es costoso. Tienes que gestionar el desplazamiento, la transmisión de mensajes, la reanudación de conversaciones, los archivos adjuntos, la visualización de llamadas a herramientas y el manejo de errores de red.
ChatKit es la respuesta de OpenAI: un componente de conversación que incrustas en tu producto y que gestiona toda la experiencia de usuario. La documentación destaca sus widgets interactivos, sugerencias de inicio, visualización de llamadas a herramientas, archivos adjuntos y visualización del razonamiento del agente. Tú mantienes el control de lo importante: el agente, tus datos y tus reglas.
Dos formas de impulsarlo
ChatKit es solo una interfaz. Necesita un servidor que reciba mensajes, ejecute el agente y devuelva la respuesta en flujo continuo. OpenAI describe dos enfoques:
| Vía | Cómo funciona | Para quién es |
|---|---|---|
| Tu propio servidor ChatKit (integración avanzada) | Tu servidor Python, usando el SDK openai-chatkit, recibe peticiones de la interfaz y ejecuta el agente que elijas, como un agente del Agents SDK | Cualquier proyecto nuevo: esta es la vía que recomienda OpenAI |
| Flujo de trabajo alojado de Agent Builder | OpenAI ejecuta un flujo de trabajo diseñado en Agent Builder; tu servidor solo crea sesiones | Integraciones existentes durante el periodo de transición: Agent Builder se apaga el 30 de noviembre de 2026 |
Este curso sigue la primera vía, la única con futuro. Resumimos la segunda al final de la lección para quienes necesiten mantener una integración existente hasta el apagado.
La arquitectura de tres piezas
Una integración de ChatKit se reduce a tres elementos. Distinguirlos evita la mayoría de los errores de principiante:
- ChatKit.js, el componente en sí: un componente web
<openai-chatkit>que muestra la conversación en un iframe. Se carga desde la CDN de OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), no desde npm: el paquete npm@openai/chatkitcontiene solo sus definiciones de tipo. - Enlaces para React,
@openai/chatkit-react, que exponen el componenteChatKity el ganchouseChatKit. Son opcionales: sin React, controlas el componente web directamente. - Tu servidor ChatKit, un único punto final HTTP, convencionalmente
/chatkit, que recibe todas las peticiones de la interfaz. Una instancia deChatKitServerlas enruta, se apoya en un almacén (store) para persistir los hilos de conversación y ejecuta tu agente.
La clave de API de OpenAI nunca sale del servidor: la interfaz solo habla con tu punto final /chatkit.
Instalación
En el lado de la interfaz, instala los enlaces para React y carga el script de ChatKit en tu página:
npm install @openai/chatkit-react
<!-- En el <head> de tu página -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
En el lado del servidor, instala el SDK de Python de ChatKit (Python 3.10 o posterior), que incluye el Agents SDK, junto con un servidor web:
pip install openai-chatkit fastapi uvicorn
El servidor mínimo
El servidor siguiente sigue el inicio rápido oficial. ChatKitServer requiere solo un método, respond, llamado por cada mensaje de usuario. Recarga los últimos elementos del hilo, los convierte en entrada para el agente con simple_to_agent_input, ejecuta el agente en modo de transmisión y traduce ese flujo en eventos de 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 # almacén en memoria de la aplicación de inicio
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]:
# Los últimos 30 elementos del hilo, restaurados en orden cronológico
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")
Ejecútalo con OPENAI_API_KEY en tu entorno: uvicorn main:app --port 8000.
El almacén (store) merece dos palabras. ChatKit no almacena nada por sí mismo: los hilos, mensajes, widgets y llamadas a herramientas son persistidos por una clase que hereda de chatkit.store.Store e implementa about una docena de métodos (load_thread, save_thread, load_thread_items, add_thread_item…). Para empezar, reutiliza el archivo memory_store.py de la aplicación de inicio oficial: mantiene todo en memoria mientras el proceso se ejecuta. En producción, sustitúyelo por una base de datos. La documentación recomienda almacenar los objetos como JSON para que las actualizaciones del SDK no te obliguen a realizar migraciones de esquema.
La interfaz en React
En el lado de la interfaz, useChatKit recibe la configuración y devuelve un objeto control, que pasas al componente ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// En desarrollo, un valor provisional es suficiente; en producción,
// usa tu clave de dominio (ver más abajo)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Sirve la interfaz y /chatkit desde el mismo origen: en desarrollo, el proxy de tu herramienta de compilación se encarga de esto (la aplicación de inicio configura el proxy de Vite para redirigir /chatkit al puerto 8000). Si el servidor vive en un origen diferente, permítelo explícitamente, por ejemplo con CORSMiddleware de FastAPI.
Sin React
Un sitio de WordPress, una aplicación Rails o una página estática pueden integrar el mismo asistente: el componente web funciona directamente una vez cargado el script de la 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>
Cada opción que verás en las siguientes lecciones tiene la misma forma en ambos casos: un objeto pasado a useChatKit en React, o a setOptions en el componente web.
Seguridad desde el primer día
Tres reglas, extraídas de la guía de producción de ChatKit, se aplican desde la fase de prototipo:
- La clave de API permanece en el servidor. No debe aparecer en el código de la interfaz ni en tu repositorio: léela desde una variable de entorno o un gestor de secretos.
- Autentica cada petición a
/chatkit. El SDK no se encarga de esto: tu aplicación debe verificar la sesión o el token del usuario y luego pasar su identidad aserver.processen el contexto (lección 21). Sin esto, cualquiera puede ejecutar tu agente a tu costa. - Registra tus dominios. Antes de salir a producción, declara cada nombre de host que mostrará ChatKit en la página Lista de dominios permitidos de la plataforma de OpenAI, y copia la clave generada en
domainKey. Al cargar, el iframe de ChatKit verifica esta clave con OpenAI y se niega a mostrarse si falta o no coincide.
Si ya tienes un flujo de trabajo de Agent Builder
Las integraciones existentes enganchadas a un flujo de trabajo alojado funcionan hasta que se apague Agent Builder. Su principio difiere: tu servidor crea una sesión de ChatKit llamando a POST https://api.openai.com/v1/chatkit/sessions, con la cabecera OpenAI-Beta: chatkit_beta=v1, el ID del flujo de trabajo y un identificador user único para cada usuario autenticado. Luego devuelve el client_secret obtenido a la interfaz. En el lado de la interfaz, la opción api toma entonces una función getClientSecret en lugar de una URL.
No inicies un nuevo proyecto con este modelo. Para una integración existente, exporta el flujo de trabajo a código del Agents SDK y cámbiate a tu propio servidor ChatKit antes del 30 de noviembre de 2026, siguiendo la guía Migrar desde Agent Builder.
Puntos clave
- ChatKit es una interfaz de conversación lista para integrar; tu servidor ejecuta el agente
- Para cualquier proyecto nuevo: tu propio servidor ChatKit (
pip install openai-chatkit), con un métodorespondy un punto final/chatkit; el Agent Builder alojado se apaga el 30 de noviembre de 2026 - La interfaz se carga desde la CDN de OpenAI; en React, usa
useChatKity<ChatKit control={control} />de@openai/chatkit-react - El almacén (store) persiste los hilos de conversación: en memoria para pruebas, en una base de datos para producción
- Clave de API solo en el servidor,
/chatkitautenticado, dominios registrados para obtener ladomainKey