Openai Chatkit

OpenAI ChatKit

Contexto

OpenAI ChatKit es un framework frontend para construir e integrar experiencias de chat AI personalizables en aplicaciones web. Proporciona componentes React pre-construidos para interfaces de chat con características como streaming de respuestas, adjuntos de archivos y gestión de conversaciones.

Paquetes

Instalación

# React (Frontend)
npm install @openai/chatkit-react

# Python (Backend avanzado)
pip install openai-chatkit

Reglas Críticas

• Siempre requiere un backend para autenticación y conexión con OpenAI APIs
• Nunca exponer API keys en el frontend - usar client_secret generado por el servidor
• Siempre manejar el streaming de respuestas correctamente
• Preferir la integración recomendada (Agent Builder) para setup rápido

Arquitectura

Integración Recomendada (Rápida)

1. Frontend: ChatKit React components
2. Backend: OpenAI Agent Builder hostea y escala
3. Tu servidor: Solo genera client_token para iniciar sesiones

Integración Avanzada (Control Total)

1. Frontend: ChatKit React components
2. Backend: Tu servidor con ChatKit Python SDK
3. Control completo sobre herramientas, lógica y almacenamiento

Procedimiento de Implementación

1. Setup del Agent Workflow

Crear un agent workflow en OpenAI Agent Builder que define el comportamiento del AI.

2. Backend - Generación de Token

from openai import OpenAI

client = OpenAI()

def create_chat_session(user_id: str):
    """Genera un client_secret para iniciar una sesión de chat."""
    response = client.beta.realtime.sessions.create(
        model="gpt-4o-realtime-preview",
        voice="verse",
        modalities=["text"]
    )
    return response.client_secret

3. Frontend - Renderizar ChatKit

import { ChatKit, useChatKit } from "@openai/chatkit-react";

interface ChatContainerProps {
  clientSecret: string;
}

function ChatContainer({ clientSecret }: ChatContainerProps) {
  const { config, events } = useChatKit({
    clientSecret,
    onMessage: (message) => {
      console.log("New message:", message);
    },
    onError: (error) => {
      console.error("Chat error:", error);
    },
  });

  return <ChatKit config={config} events={events} className="h-full w-full" />;
}

export default ChatContainer;

4. Streaming de Respuestas

import { ChatKit } from "@openai/chatkit-react";

function StreamingChat({ clientSecret }: { clientSecret: string }) {
  return (
    <ChatKit
      clientSecret={clientSecret}
      streamingEnabled={true}
      => console.log("Streaming started")}
      => console.log("Streaming ended")}
    />
  );
}

Características Principales

Ejemplo Completo

// app/chat/page.tsx (Next.js App Router)
"use client";

import { useEffect, useState } from "react";
import { ChatKit } from "@openai/chatkit-react";

export default function ChatPage() {
  const [clientSecret, setClientSecret] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function initChat() {
      try {
        // Obtener client_secret desde tu backend
        const response = await fetch("/api/chat/init", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
        });
        const { client_secret } = await response.json();
        setClientSecret(client_secret);
      } catch (error) {
        console.error("Failed to init chat:", error);
      } finally {
        setLoading(false);
      }
    }
    initChat();
  }, []);

  if (loading) {
    return (
      <div className="flex items-center justify-center h-screen">
        Loading...
      </div>
    );
  }

  if (!clientSecret) {
    return <div className="text-red-500">Failed to initialize chat</div>;
  }

  return (
    <div className="h-screen w-full">
      <ChatKit
        clientSecret={clientSecret}
        theme="dark"
        placeholder="Ask me anything..."
      />
    </div>
  );
}

Recursos

• GitHub - chatkit-js
• GitHub - Advanced Samples
• NPM - @openai/chatkit-react
• OpenAI Platform Docs