Identidad de usuario - Thaliq Docs

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

Campo	Requerido	Descripcion
`userId`	Si	ID del usuario en tu sistema
`email`	No	Email del usuario
`name`	No	Nombre del usuario
`token`	No	JWT/Bearer token (se envia como `Authorization: Bearer ...`)
`mcpTokens`	No	Tokens por MCP Server ID (se envian en `X-MCP-Tokens`)
`participantId`	No	ID de participante para tracking de conversaciones
`metadata`	No	Metadata 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);
    }
  }
}

​Identificar un usuario

​Campos

​Limpiar identidad

​Headers que se envian

​MCP Token Passthrough

​participantId

​Eventos

​Ejemplo completo

Identificar un usuario

Campos

Limpiar identidad

Headers que se envian

MCP Token Passthrough

participantId

Eventos

Ejemplo completo