Skip to main content
El SDK permite identificar al usuario actual de tu aplicacion. Esto habilita:
  • Tools protegidas: Tools con requiresAuth: true solo estan disponibles con usuario identificado
  • MCP Token Passthrough: Tokens del usuario se envian a MCP Servers para ejecutar acciones en su nombre
  • Tracking por usuario: Metricas en la plataforma muestran actividad por usuario
  • Feedback vinculado: Feedback de mensajes se asocia al usuario

​
Identificar un usuario

Llama a identify() cuando el usuario hace login en tu app: 
thaliq.identify({
  userId: 'usr_123',
  email: 'maria@empresa.com',
  name: 'Maria Garcia',
  token: 'jwt_del_usuario',        // Bearer token (passthrough para MCP)
  mcpTokens: {                      // Tokens especificos por MCP server
    'crm-server': 'token_crm',
    'erp-server': 'token_erp',
  },
});

​
Campos

CampoRequeridoDescripcion
userIdSiID del usuario en tu sistema
emailNoEmail del usuario
nameNoNombre del usuario
tokenNoJWT/Bearer token (se envia como Authorization: Bearer ...)
mcpTokensNoTokens por MCP Server ID (se envian en X-MCP-Tokens)
participantIdNoID de participante para tracking de conversaciones
metadataNoMetadata adicional (key-value)

​
Limpiar identidad

Llama a reset() cuando el usuario hace logout: 
thaliq.reset();
Esto limpia la identidad, los headers asociados y el estado de conversaciones.

​
Headers que se envian

Cuando un usuario esta identificado, el SDK incluye automaticamente estos headers: 
X-API-Key: tq_live_xxx                      (siempre)
X-Integration-Type: sdk                      (siempre)
X-User-Id: usr_123                          (de identify)
X-Participant-Id: part_456                  (de identify, si hay participantId)
Authorization: Bearer jwt_del_usuario       (de identify, si hay token)
X-MCP-Tokens: {"crm-server":"token_crm"}   (de identify, si hay mcpTokens)

​
MCP Token Passthrough

Los tokens en mcpTokens se envian al backend, que los rutea al MCP Server correspondiente. Esto permite que el MCP Server ejecute acciones en nombre del usuario sin que Thaliq almacene credenciales. 
// El usuario tiene acceso a dos MCP servers
thaliq.identify({
  userId: 'usr_123',
  mcpTokens: {
    'server-financiero': 'eyJhb...',  // Token para el server financiero
    'server-crm': 'sk-xxx',          // Token para el CRM
  },
});

// El agente puede ejecutar tools de ambos servers
const stream = thaliq.agent.stream('Consulta mi saldo y mis tickets abiertos');

​
participantId

El campo participantId se usa para identificar al participante en conversaciones. Es util cuando un mismo userId puede tener multiples sesiones o dispositivos: 
thaliq.identify({
  userId: 'usr_123',
  participantId: `sdk:usr_123`,  // Formato: "sdk:{userId}"
});
El backend usa participantId como clave en el GSI de DynamoDB para recuperar conversaciones del participante. Si no se envia, se genera automaticamente como sdk:{userId}.

​
Eventos

El SDK emite eventos cuando se identifica o limpia un usuario: 
thaliq.on('identify', (userId) => {
  console.log(`Usuario identificado: ${userId}`);
});

thaliq.on('reset', () => {
  console.log('Identidad limpiada');
});

​
Ejemplo completo

import { Thaliq } from '@thaliq/sdk';

const thaliq = new Thaliq({ apiKey: 'tq_live_xxx' });

// Login de tu app
function onUserLogin(user: { id: string; jwt: string; mcpToken: string }) {
  thaliq.identify({
    userId: user.id,
    token: user.jwt,
    mcpTokens: {
      'mi-api': user.mcpToken,
    },
  });
}

// Logout de tu app
function onUserLogout() {
  thaliq.reset();
}

// El agente ahora puede ejecutar tools protegidas
async function askAgent(question: string) {
  const stream = thaliq.agent.stream(question);
  for await (const event of stream) {
    if (event.type === 'content.delta') {
      process.stdout.write(event.delta);
    }
  }
}