Ir al contenido principal
Español— Elegir un idioma
Menú

Integración avanzada en tu aplicación

Lección 21 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Qué falta después de la demostración
  2. Autentica cada petición
  3. Cada usuario tiene sus propias conversaciones
  4. Proporciona el contexto de tu aplicación al modelo
  5. Herramientas del lado del cliente
  6. Controla ChatKit desde tu aplicación
  7. Observa lo que ocurre
  8. Antes de pasar a producción
  9. Puntos clave

Lección reescrita el 3 de noviembre de 2026. La versión anterior se basaba en propiedades y eventos inventados (ChatProvider, modo «sidebar», persistencia basada en UI). Ahora sigue las guías del SDK de Python openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) y los tipos de @openai/chatkit-react 1.6.1: el código del servidor se ha ejecutado localmente y el código de React se ha verificado mediante compilación. Fuentes: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Qué falta después de la demostración

Las cuatro lecciones anteriores te proporcionan un asistente funcional. Para que viva en un producto real, necesita lo que separa una demostración de un servicio: saber quién está hablando, mostrar a cada usuario solo sus conversaciones, interactuar con el resto de la aplicación y ser observable. Esta lección cubre estos puntos uno por uno.

Autentica cada petición

El SDK no hace suposiciones sobre tu autenticación: te permite verificar al usuario y luego pasar su identidad a server.process dentro de un contexto de petición. Este contexto sigue a cada llamada: lo encontrarás en respond, en action, en el store y en las herramientas del agente.

En la parte de la interfaz, la opción api.fetch sustituye a la función fetch que utiliza ChatKit. Aquí es donde añades el token de sesión de tu aplicación:

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

export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      domainKey: 'local-dev',
      fetch: async (input, init) => {
        // Mantén las cabeceras establecidas por ChatKit y añade las tuyas
        const headers = new Headers(init?.headers);
        headers.set('Authorization', `Bearer ${await obtainToken()}`);
        return fetch(input, { ...init, headers });
      },
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

En el lado del servidor, una dependencia de FastAPI verifica el token y construye el contexto. El idioma de la interfaz llega en la cabecera Accept-Language, que ChatKit envía con cada petición:

from dataclasses import dataclass

from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse


@dataclass
class RequestContext:
    user_id: str
    locale: str


async def current_user(request: Request) -> str:
    token = request.headers.get("authorization", "").removeprefix("Bearer ")
    user_id = await verify_token(token)  # tu autenticación: sesión, JWT...
    if not user_id:
        raise HTTPException(status_code=401, detail="Unauthenticated")
    return user_id


app = FastAPI()


@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
    context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
    try:
        result = await server.process(await request.body(), context)
    except NotFoundError:
        raise HTTPException(status_code=404, detail="Not found")
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

Cada usuario tiene sus propias conversaciones

La autenticación no es suficiente: también necesitas autorización. Sin control, un usuario que adivine un ID de hilo podría leer la conversación de otra persona. El lugar correcto para este control es el store, por donde pasan todas las lecturas. En este ejemplo, cada hilo mantiene el nombre de su propietario en sus metadatos, algo que el SDK nunca transmite a la interfaz:

from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata

from memory_store import MemoryStore


class UserStore(MemoryStore):
    async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
        thread.metadata.setdefault("owner", context.user_id)
        await super().save_thread(thread, context)

    async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
        thread = await super().load_thread(thread_id, context)
        if thread.metadata.get("owner") != context.user_id:
            raise NotFoundError(f"Thread {thread_id} not found")  # no reveles que existe
        return thread

    async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
        page = await super().load_threads(limit, after, order, context)
        page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
        return page

El bloque try en el endpoint tiene sentido aquí: sin él, leer directamente el hilo de otro usuario terminaría en un error 500 en lugar de un 404; para una petición transmitida (streamed), como añadir un mensaje, el SDK interrumpe el flujo sin enviar nada. En producción, este filtrado ocurre en la propia consulta SQL (un WHERE owner = … también gestiona correctamente la paginación). Aplica la misma regla a los adjuntos. La documentación también te recuerda que debes decidir qué conservas y durante cuánto tiempo: los hilos contienen texto, archivos y resultados de herramientas, por lo que a menudo incluyen datos personales.

Proporciona el contexto de tu aplicación al modelo

El modelo no sabe nada sobre la página que está viendo el usuario, su suscripción o el documento abierto. La documentación propone tres formas de enseñárselo:

  • En cada petición, mediante cabeceras añadidas en api.fetch (X-Page, X-Plan…), que el servidor almacena en el contexto;
  • Bajo demanda, mediante una herramienta del servidor que lee ctx.context.request_context y recupera la información;
  • En el navegador, mediante una herramienta del lado del cliente, cuando la información solo existe allí (véase la siguiente sección).

Una precaución, extraída de la guía de producción: nunca construyas las instrucciones del sistema del modelo a partir de valores que provengan del usuario, ni siquiera indirectamente (título del hilo, asunto del ticket). Mantenlas fijas y pasa el contexto variable como datos.

Herramientas del lado del cliente

Alguna información solo vive en el navegador: una selección en un editor, el estado de un lienzo, un borrador no guardado. Una herramienta del lado del cliente permite al modelo solicitarlas a mitad de turno: tu servidor pausa el agente, ChatKit ejecuta tu función en el navegador y luego devuelve el resultado al servidor, que reanuda la ejecución.

En el lado del servidor, la herramienta solo realiza la petición y el agente se detiene en ella:

from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall


@function_tool(description_override="Lee el texto que el usuario ha seleccionado en la página.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
    ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})


assistant = Agent[AgentContext](
    name="Writing Assistant",
    instructions="Ayuda al usuario a mejorar el texto que seleccione.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

En el lado de la interfaz, onClientTool recibe la petición; el nombre debe coincidir y el objeto devuelto va al servidor:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Solo puede ejecutarse una herramienta del lado del cliente por turno. Y cuando no esperas una respuesta, prefiere un efecto: el servidor emite un ClientEffectEvent(name="refresh_cart", data={...}), desde respond, action o una herramienta mediante ctx.context.stream(...), y la interfaz lo recibe en onEffect sin interrumpir la respuesta. Los efectos no se registran en el hilo.

Controla ChatKit desde tu aplicación

useChatKit devuelve, además de control, métodos para comandar la interfaz desde el resto de tu código:

MétodoEfecto
sendUserMessage({ text })Envía un mensaje como si el usuario lo hubiera escrito
setComposerValue({ text })Rellena previamente el área de entrada sin enviar
setThreadId(id)Abre un hilo existente, o uno nuevo con null
focusComposer()Coloca el cursor en el área de entrada
showHistory(), hideHistory()Abre o cierra el historial de conversaciones
sendCustomAction(action)Envía una acción al servidor (Lección 20)
fetchUpdates()Recarga el hilo desde el servidor

Un botón «Preguntar al asistente» en una ficha de producto se convierte en una línea de código:

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

export function ProductSheet({ product }: { product: string }) {
  const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });

  return (
    <>
      <button onClick={() => chatkit.sendUserMessage({ text: `Is the ${product} product compatible with my equipment?` })}>
        Ask the assistant
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

La opción initialThread abre un hilo específico al montar el componente, por ejemplo, el que el usuario dejó abierto; con null (el valor predeterminado), ChatKit muestra la pantalla de inicio.

Observa lo que ocurre

ChatKit emite eventos: listo (onReady), inicio y fin de respuesta (onResponseStart, onResponseEnd), cambio de hilo (onThreadChange), registros (onLog) y errores (onError). En React, estas son opciones para useChatKit:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onThreadChange: ({ threadId }) => rememberLastThread(threadId),
  onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
  onLog: ({ name }) => sendTelemetry({ name: name }),
});

La guía de producción insiste en un punto: estos eventos pueden contener datos personales y texto de mensajes. No envíes todo el contenido a tu herramienta de seguimiento: extrae los campos útiles (nombre del evento, ID del hilo, código de error). En el lado del servidor, registra cada petición a /chatkit, las llamadas al store y al modelo, y los errores de las herramientas, con el ID de usuario y de hilo, para que puedas correlacionar ambos lados.

Para herramientas lentas, mantén informado al usuario: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) muestra un progreso inmediato, que es sustituido por el resto de la respuesta y nunca se registra en el hilo.

Antes de pasar a producción

La lista de comprobación, extraída de la guía oficial:

  • Dominios: cada nombre de host de producción está listado en la página Domain allowlist de la plataforma de OpenAI, y su clave está en domainKey;
  • Autenticación y autorización: cada petición a /chatkit está autenticada, los hilos y adjuntos se filtran por usuario;
  • Secretos: la clave de API y las credenciales internas están en variables de entorno o en un gestor de secretos, nunca en el repositorio;
  • Entradas: los mensajes, archivos, cargas útiles de acciones y resultados de herramientas se tratan como no fiables y se validan antes de llegar a tus sistemas;
  • Datos personales: periodo de retención decidido y aplicado en el store, cifrado en reposo, sin datos innecesarios en los metadatos;
  • Idioma: el idioma de Accept-Language dirige las respuestas del agente y los mensajes de tus herramientas;
  • Seguimiento: eventos de interfaz y registros del servidor recopilados, sin contenido sensible.

Puntos clave

  • La identidad del usuario pasa mediante api.fetch en el lado de la interfaz y luego a través del contexto de server.process, que la propaga a todas partes
  • La autorización ocurre en el store: cada hilo pertenece a un usuario y el hilo de otro usuario aparece como «no encontrado»
  • El contexto de la aplicación llega mediante cabeceras, herramientas del servidor o herramientas del lado del cliente (onClientTool + StopAtTools); los efectos (onEffect) sirven cuando no se espera respuesta
  • Los métodos de useChatKit (sendUserMessage, setThreadId, setComposerValue…) comandan ChatKit desde el resto de la aplicación
  • Los eventos (onError, onLog…) alimentan tu seguimiento, sin copiar datos personales en él; la lista de comprobación de producción cubre dominios, derechos, secretos, entradas y datos