Configura el retrieval de tu agente en 5 minutos con Claix Retrieve

Qué es el RAG agéntico y cómo encaja el retrieval SQL

RAG significa que un modelo utiliza información recuperada de una fuente externa para elaborar una respuesta. No implica necesariamente documentos, embeddings o una base de datos vectorial.

Cuando un agente decide llamar a una herramienta para recuperar información, hablamos de un enfoque agéntico. Esa herramienta puede buscar documentos, consultar un índice o ejecutar una consulta SQL controlada. “Agéntico” describe cómo se activa la recuperación; “vectorial” describe una técnica para encontrar resultados. No son sinónimos.

Claix Retrieve encaja como una herramienta de acceso a datos relacionales. Si tu agente necesita conocer cuántas reservas hay mañana o qué pedidos siguen pendientes, puede consultar los datos actuales de tu base de datos en lugar de depender de una copia indexada. Claix no requiere copiar tus tablas a un vector store para realizar ese retrieval. Una descripción precisa sería “retrieval SQL controlado para agentes de IA”. Puede formar parte de una arquitectura de RAG agéntico, sin obligarte a montar un pipeline de embeddings.

Cuándo utilizar Claix Retrieve

Claix Retrieve resulta especialmente relevante cuando las respuestas dependen de registros estructurados que ya existen en una base de datos SQL. Un agente de soporte puede consultar el estado de un pedido. Un asistente de operaciones puede preguntar por reservas confirmadas. Un workflow puede necesitar un número o un booleano para decidir el siguiente paso.

Los formatos tipados incluyen cadenas, enteros, booleanos, fechas, timestamps, JSON y determinadas listas. En modo bruto, Claix devuelve las filas de la consulta en lugar de transformarlas en un valor razonado. Para búsquedas semánticas sobre grandes colecciones de texto, un índice vectorial puede seguir siendo adecuado. Para estados, importes, fechas, recuentos y registros actuales que ya viven en SQL, el retrieval directo puede evitar una capa de indexación innecesaria.

Qué necesitas antes de empezar

Prepara una cuenta de Claix, una API key y una conexión de base de datos con permisos de solo lectura. También conviene elegir una primera pregunta concreta, por ejemplo “¿Cuántos pedidos hay confirmados?”. Claix indica compatibilidad con bases SQL, incluidos Postgres, MySQL, MariaDB y entornos compatibles con Postgres, como Supabase. Antes de conectar, comprueba qué tablas necesitas y qué columnas no deberían estar disponibles para el agente.

Paso 1. Conecta la base de datos y revisa el Data Map

Al conectar la base de datos, Claix prepara un Data Map con tablas, descripciones y relaciones que puedes revisar y editar. No te limites a confirmar nombres técnicos. Una columna llamada status puede representar el estado de pago, de envío o de validación interna. El objetivo es una representación útil de tu base de datos, no solo una lista de tablas. La conexión debe utilizar un rol de solo lectura: Claix Retrieve está diseñado para consultar datos, no para ejecutar escrituras.

Paso 2. Crea una ruta con un propósito concreto

En Claix, una ruta define una capacidad de retrieval. Incluye las tablas y columnas que puede utilizar, junto con una guía de reglas y vocabulario de negocio. El agente no necesita acceso indiscriminado a la base de datos. Puedes construir capacidades concretas y reutilizarlas en distintos agentes.

Paso 3. Crea el agente y elige cómo debe responder

El agente de Retrieve es la identidad que utilizará esas rutas. Configuras su nombre, descripción, instrucciones de negocio, rutas asociadas y modo de respuesta. Este agente no sustituye necesariamente al asistente que ya estás construyendo: es el punto de entrada a los datos que tu aplicación, workflow o agente principal puede consultar.

En modo razonado, cada pregunta debe indicar el formato requerido. Si faltan datos o no es seguro producir el tipo solicitado, la documentación contempla una respuesta null.

Paso 4. Conecta Claix mediante MCP

MCP permite que un cliente compatible descubra y utilice las herramientas de Claix sin que tengas que escribir una integración REST específica para cada operación. El servidor MCP de Claix está en https://claix.dev/mcp. Para retrieval, la herramienta documentada es claix.retrieve.ask. También hay herramientas para crear y modificar rutas y agentes. En Cursor, la documentación ofrece esta configuración:

{
  "mcpServers": {
    "claix": {
      "url": "https://claix.dev/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

El formato depende del cliente MCP. Utiliza el mecanismo de credenciales de tu herramienta y evita guardar API keys en repositorios compartidos. Defines el acceso en Claix y expones esa capacidad al entorno en el que ya trabajas. MCP facilita la conexión. El control de acceso sigue dependiendo del rol de base de datos, de las rutas y de la configuración del agente.

Paso 5. Haz una primera consulta y revisa su traza

Una integración no está terminada cuando la herramienta aparece en el cliente. Está lista para seguir probándose cuando puedes hacer una pregunta, comprobar la respuesta y revisar cómo se obtuvo. También puedes probar Retrieve mediante REST:

curl -X POST "https://claix.dev/retrieve/soporte-pedidos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [
      {
        "question": "¿Cuántos pedidos hay en estado confirmado?",
        "format": "int"
      }
    ]
  }'

Sustituye soporte-pedidos por el slug de un agente activo de tu cuenta. El agente debe tener al menos una ruta activa con una definición publicada. La respuesta incluye las preguntas, los resultados y un log_id. Puedes enviar hasta cinco preguntas por petición. Prueba también preguntas que no deberían poder responderse.

Por qué esta arquitectura es low-code

La parte low-code de Claix está en la definición y gestión del retrieval: conexión, Data Map, rutas, agentes y formatos de respuesta. Eso no significa que una aplicación de producción deje de necesitar código. Seguirás gestionando autenticación, secretos, errores y cómo tu producto usa los resultados. Lo que cambia es la infraestructura específica de retrieval que tienes que construir.

Qué comprobar antes de pasar a producción

Revisa si las rutas exponen solo la información necesaria, si los términos de negocio están bien definidos y si las respuestas tienen el formato que espera tu aplicación. Comprueba preguntas ambiguas, preguntas sin datos y peticiones fuera del perímetro. Si utilizas tu propia clave de modelo, pruébala en el Sandbox. Para restricciones por usuario o tenant, no des por hecho que permitir una tabla resuelve toda la autorización.

Empieza por una pregunta que tu agente necesite responder

No necesitas comenzar conectando todo tu negocio. Elige una pregunta útil, conecta la base de datos con un rol de solo lectura y crea una ruta pequeña. Cuando esa primera consulta funcione y puedas revisar su traza, amplía el perímetro solo si el caso de uso lo necesita. Empieza en https://www.claix.dev/es y consulta la documentación de MCP en https://www.claix.dev/es/documentation/mcp.