> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thaliq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceptos clave

> Tenants, agentes, tools, instrucciones, conversaciones — el modelo mental de Thaliq

## Tenant

Un **tenant** es tu organizacion dentro de Thaliq. Todo esta aislado por tenant: agentes, tools, documentos, conversaciones, metricas y miembros.

Al registrarte se crea un tenant automaticamente y vos sos el `OWNER`. Despues podes invitar miembros con distintos roles desde el [Workspace > Team](/platform/team).

| Rol            | Permisos                                                                    |
| -------------- | --------------------------------------------------------------------------- |
| **Owner**      | Control total del tenant                                                    |
| **Admin**      | Configuracion, tools, miembros                                              |
| **Supervisor** | Dashboard + Inbox + Conversations + Usage. Asigna y reasigna conversaciones |
| **Agent**      | Atiende conversaciones humanas desde el Inbox (solo ve las asignadas)       |
| **Editor**     | Crear/editar tools, documentos, instrucciones                               |
| **Viewer**     | Solo lectura                                                                |

## Workspace

El **workspace** (`thaliq.com/workspace`) es la consola del tenant. Reune los espacios cross-agente:

| Seccion   | URL                    | Para que                                                   |
| --------- | ---------------------- | ---------------------------------------------------------- |
| Dashboard | `/workspace/dashboard` | Vision general y actividad reciente                        |
| Agents    | `/workspace/agents`    | Lista de agentes — punto de entrada al detalle de cada uno |
| Inbox     | `/workspace/inbox`     | Conversaciones con intervencion humana (HITL)              |
| Usage     | `/workspace/usage`     | Consumo, tokens, costos                                    |
| Settings  | `/workspace/settings`  | Plan, billing, perfil del tenant                           |
| Team      | `/workspace/team`      | Miembros e invitaciones                                    |
| API & SDK | `/workspace/api-sdk`   | Documentacion y herramientas de integracion                |

## Agentes

Un **agente** es una IA configurable que conversa con tus usuarios. Cada agente tiene su propio set de tools, documentos, instrucciones, workflows y credenciales — completamente aislado del resto del tenant.

Cada tenant puede tener varios agentes (cantidad segun [plan](/introduction/plans)). Uno de ellos esta marcado como **default** del tenant: las API keys sin agente especifico le rutean a el.

### Anatomia de un agente

Cada agente vive en `thaliq.com/agents/:agentId` y se configura por tabs:

| Tab               | Que hace                                                |
| ----------------- | ------------------------------------------------------- |
| **Overview**      | Metricas y actividad del agente                         |
| **Prompt**        | System prompt y compilacion (con preview de tokens)     |
| **Tools**         | HTTP, MCP, A2A — acciones que puede ejecutar            |
| **MCP**           | MCP Servers conectados a este agente                    |
| **RAG**           | Documentos que alimentan respuestas con tu informacion  |
| **Instructions**  | Reglas y acciones interactivas (HITL)                   |
| **Workflows**     | Formularios guiados multi-step                          |
| **Linked Agents** | Conexion A2A con otros agentes del tenant               |
| **Channels**      | Widget, SDK, WhatsApp, Telegram, Slack (soon)           |
| **Credentials**   | API keys y access keys de este agente                   |
| **Settings**      | Identidad, modelo, temperatura, idioma, session timeout |

### Routing automatico

Cada [API Key](/platform/credentials) puede asociarse a un agente especifico:

| Key           | Asociada a       | Comportamiento                                  |
| ------------- | ---------------- | ----------------------------------------------- |
| `tq_live_aaa` | Agente "Soporte" | Las requests con esta key van al agente Soporte |
| `tq_live_bbb` | Agente "Ventas"  | Las requests con esta key van al agente Ventas  |
| `tq_live_ccc` | (ninguno)        | Caen al agente **default** del tenant           |

**Override por request:** podes pasar `agentId` en el body (`POST /chat`) o como query param (`GET /stream`) para forzar un agente distinto al de la key.

```typescript theme={null}
// Widget asociado a un agente especifico
ThaliqWidget.init({
  apiKey: 'tq_live_xxx',  // si la key esta bindeada a un agente, se usa ese
  agentId: 'agent_uuid',  // override explicito (opcional)
});
```

## API Keys y Access Keys

Las **credenciales** autentican las peticiones desde tu integracion:

| Tipo           | Prefijo                 | Visibilidad                                   | Uso tipico                                 |
| -------------- | ----------------------- | --------------------------------------------- | ------------------------------------------ |
| **API Key**    | `tq_live_` / `tq_test_` | Solo se ve al crear (hash SHA-256 en backend) | SDK, integraciones server-side             |
| **Access Key** | `tq_ak_`                | Visible siempre desde el workspace            | Widget publico, snippets que viven en HTML |

Mas detalle en [Credentials](/platform/credentials).

## Tools

Las **tools** son acciones que el agente puede ejecutar durante una conversacion. Cuatro tipos:

<CardGroup cols={2}>
  <Card title="Nativas" icon="cube">
    Tools built-in de Thaliq (ej: buscar documentos RAG).
  </Card>

  <Card title="HTTP" icon="globe">
    Llaman a cualquier API REST que configures (tu API de productos, pedidos, etc.).
  </Card>

  <Card title="MCP" icon="server">
    Importadas desde MCP Servers, ideales para sistemas estandarizados.
  </Card>

  <Card title="A2A (Agent-to-Agent)" icon="git-merge">
    Otro agente del tenant aparece como una tool `ask_<slug>` invocable.
  </Card>
</CardGroup>

### Visibilidad de tools

Cada tool tiene `requiresAuth` que controla donde esta disponible:

| `requiresAuth` | Widget        | SDK / API  |
| -------------- | ------------- | ---------- |
| `false`        | Disponible    | Disponible |
| `true`         | No disponible | Disponible |

Esto permite que tools que requieren auth del usuario final ("ver mis pedidos") solo aparezcan via SDK con identidad de usuario.

## Instrucciones

Las **instrucciones** son reglas configurables que se compilan en el system prompt y pueden incluir **acciones interactivas** (Human-in-the-Loop).

### Triggers

| Trigger              | Cuando se aplica                       |
| -------------------- | -------------------------------------- |
| `ALWAYS`             | En cada conversacion                   |
| `CONVERSATION_START` | Solo al inicio                         |
| `INTENT`             | Cuando el usuario menciona cierto tema |
| `FALLBACK`           | Cuando el agente no sabe que hacer     |

### Acciones interactivas (Human-in-the-Loop)

| Tipo        | Descripcion                 |
| ----------- | --------------------------- |
| **Consent** | Checkbox + Aceptar/Rechazar |
| **Confirm** | Pregunta Si/No              |
| **Select**  | Elegir entre opciones       |
| **Form**    | Formulario con campos       |

Las acciones se renderizan **inline** dentro del mensaje del asistente (como un `MessagePart`), no como un mensaje aparte.

## Workflows

Un **workflow** es un formulario guiado multi-step. El agente conduce al usuario por pasos secuenciales (texto, email, telefono, fecha, select, tool\_call, display) hasta cerrar con una tool de submit.

Util para: agendamiento, alta de cliente, ticket de soporte estructurado, cotizacion guiada.

## Documentos (RAG)

El sistema **RAG** permite subir documentos para que el agente responda basandose en tu informacion:

1. Subes un documento (PDF, DOCX, TXT, Markdown)
2. Thaliq lo divide en chunks y genera embeddings con Voyage AI
3. Cuando el usuario pregunta algo relevante, el agente busca los chunks mas similares
4. Usa esa info como contexto para generar una respuesta precisa

Los documentos son **propios de cada agente** — el RAG del agente "Soporte" no es visible al agente "Ventas".

## Conversaciones

Cada interaccion crea una **conversacion** (thread) que mantiene contexto:

* Identificada por `conversationId`
* El widget la gestiona automaticamente
* **Session timeout** configurable por agente (default 30 min)
* Se persisten en DynamoDB con TTL segun el plan

## Canales

Cada agente puede activar varios canales en paralelo:

* **Widget** — chat embebible en sitios web (built-in, siempre disponible)
* **SDK** — libreria headless para apps con auth
* **WhatsApp Business** — atencion conversacional via WhatsApp
* **Telegram** — bot conectado al agente con setup guiado
* **Slack · Email · Voice** — en roadmap

Configuras cada canal desde la tab **Channels** del agente.

## Planes

Thaliq tiene cinco niveles de plan. Los limites estan en [Planes](/introduction/plans).