Construye con el SDK TypeScript

Instalación

El paquete funciona en cualquier runtime con fetch y streams web: navegador, Node 18+, Bun, Deno y entornos edge.

npm install @talktokai/agents
# o con Bun
bun add @talktokai/agents

Uso en backend

Crea una instancia por agente y compártela entre requests. El cliente no guarda estado de conversación localmente; todo el contexto vive en el servidor.

import { Agent } from "@talktokai/agents";

const agent = new Agent({
  agentId: "mi-agente",
  apiKey: process.env.KAI_API_KEY,
});

const reply = await agent.sendMessage({
  userId: "cliente_123",
  profileName: "Ana",
  message: "¿Qué horarios manejan?",
});

console.log(reply.reply);

Uso seguro en navegador

Para visitantes anónimos usa publishableKey. Solo puede acuñar una sesión limitada a su propio usuario; el SDK la guarda en localStorage, la renueva antes de caducar y conserva el hilo después de recargar.

import { Agent } from "@talktokai/agents";

const agent = new Agent({
  agentId: "mi-agente",
  publishableKey: "pk_widget.SECRETO_PUBLICABLE",
});

// El SDK crea, persiste y renueva la sesión automáticamente.
const chat = await agent.me({ profileName: "Visitante" });
const reply = await chat.send("Quiero conocer sus servicios");

Si tu aplicación ya autentica usuarios, tu backend puede crear una sesión con modo assert y entregarla mediante sessionToken. El SDK nunca persiste este tipo de token porque su ciclo de vida le pertenece a tu backend.

Respuestas en streaming

stream() consume SSE y llama tus handlers cuando el agente entrega una parte o ejecuta una tool. Al finalizar devuelve el mismo AgentReply que sendMessage().

const reply = await agent.stream(
  { userId: "cliente_123", message: "Cotiza mi pedido" },
  {
    onMessage(part) {
      renderPart(part);
    },
    onTool(tool) {
      setActiveTool(tool.name, tool.status);
    },
  },
);

Una interfaz por conversación

agent.conversation(userId) fija la identidad para no repetirla en cada llamada. Puedes enviar, hacer streaming y recorrer el historial con paginación automática.

const chat = agent.conversation("cliente_123", {
  profileName: "Ana",
});

await chat.send("Hola");
await chat.stream("¿Abren el sábado?", { onMessage: appendBubble });

// Requiere el permiso conversations:read
for await (const message of chat.history()) {
  console.log(message);
}

Con una sesión, usa await agent.me(): toma la identidad firmada del token y evita que el frontend pueda cambiarla.

Integración con React

El entry point opcional incluye useChat, que maneja mensajes optimistas, la burbuja progresiva del agente, tools activas, cancelación y errores. React permanece como peer dependency opcional.

import { useChat } from "@talktokai/agents/react";

function Chat() {
  const { messages, send, isLoading, activeTool, stop } = useChat({
    agent,
    userId: "cliente_123",
  });

  // Renderiza messages y llama send(text) desde tu formulario.
}

Qué automatiza el SDK