Saltearse al contenido
Nappai Documentation

MCP Agent

Bienvenido al componente MCP Agent, una herramienta esencial dentro de tu flujo de automatización en Nappai. Este agente actúa como tu asistente inteligente especializado en el Model Context Protocol (MCP), lo que significa que está diseñado para conectar la inteligencia de los modelos de lenguaje con herramientas externas y datos específicos de manera estructurada y segura.

Su propósito principal es recibir una pregunta o instrucción, consultar las herramientas disponibles (como bases de datos, APIs o servicios externos) mediante el protocolo MCP, y devolver una respuesta precisa y fundamentada. Es ideal para escenarios donde necesitas que la IA no solo “genere” texto, sino que “consulte” o “actúe” sobre datos en tiempo real.

¿Cómo funciona?

Internamente, el MCP Agent funciona como un intermediario inteligente. Cuando envías información a este componente, el sistema realiza los siguientes pasos:

  1. Procesamiento del Contexto: El agente toma tu mensaje y los datos adjuntos.
  2. Interacción con Herramientas: Utiliza el protocolo MCP para verificar qué herramientas están disponibles (por ejemplo, “Leer Base de Datos X” o “Buscar en Google”).
  3. Ejecución y Respuesta: Si es necesario, ejecuta esas herramientas de forma segura para recopilar información real y luego combina esos resultados con la inteligencia del modelo para redactar una respuesta final.

A diferencia de un chatbot genérico que solo responde con lo que sabe, este agente tiene la capacidad de “hacer” cosas a través de las herramientas conectadas, asegurando que la información que recibes sea actual y relevante.

Conexión y Credenciales

Este componente se integra nativamente con el ecosistema de automatización de Nappai. No requiere credenciales externas adicionales (como claves de API de terceros) que debas configurar manualmente fuera del panel, ya que la gestión de conexiones se realiza mediante la configuración de Herramientas MCP dentro del propio sistema.

Sin embargo, para que el agente funcione correctamente, asegúrate de haber configurado previamente las herramientas MCP en la sección de configuración de herramientas de tu panel de Nappai. El agente las “verá” automáticamente según la configuración que le proporciones en el campo MCP.

Entradas

Los siguientes campos están disponibles para configurar este componente. Cada campo te permite definir cómo interactúa el agente con el resto de tu flujo.

  • Input: El mensaje o pregunta principal que deseas que el agente procese. Aquí es donde escribes la instrucción o la duda que tienes.
  • Model: El modelo de lenguaje específico que utilizará el agente para pensar y responder. Es recomendable elegir modelos más potentes para tareas complejas que requieran razonamiento con herramientas.
  • MCP: Aquí seleccionas las herramientas disponibles para el agente. Puedes elegir un conjunto predefinido de herramientas (como acceso a bases de datos o APIs) que el agente podrá usar para obtener información.
  • Agent Name: El nombre que se asigna al agente cuando se utiliza como una herramienta dentro de otros flujos o procesos. Esto ayuda a identificar claramente quién está respondiendo.
  • Agent Description: Una descripción breve del agente. Útil cuando el agente se integra como parte de un sistema más grande, ayudando a otros procesos a entender qué hace este agente (por defecto: “Specialized agent that uses MCP to answer user questions accurately.”).
  • Use Memory: Una opción para habilitar o deshabilitar la memoria de conversación. Si está activado, el agente recordará el contexto de las preguntas anteriores dentro de esa sesión.
  • Memory Limit: Si activas la memoria, puedes definir cuántos mensajes recordar. Puedes usar -1 para memoria ilimitada en la sesión actual, o un número específico (ej. 5) para recordar solo los últimos 5 mensajes.
  • Memory ID: Un identificador opcional para la sesión de memoria. Si dejas este campo vacío, el sistema generará un ID único automáticamente para cada flujo. Si escribes un ID fijo, el agente recordará las conversaciones pasadas si reutilizas ese mismo ID.
  • System Prompt: Instrucciones adicionales que se añaden a las instrucciones internas del agente. Aquí puedes darle una “personalidad” específica o dar reglas extra (ej. “Responde siempre en tono formal” o “Usa solo datos de 2024”).

Salidas

El componente MCP Agent produce dos tipos principales de resultados que puedes usar en los siguientes pasos de tu flujo:

  • Response: La respuesta de texto generada por el agente. Este es el resultado principal que normalmente deseas enviar a otro componente (como un nodo de Email o una respuesta en un chatbot).
  • Agent: La representación completa del agente. Este valor suele usarse si necesitas pasar el propio agente como una herramienta para ser usado por otro componente posterior en el flujo.

Ejemplo de Respuesta JSON

A continuación, se muestra un ejemplo de cómo se ve la salida (Response) cuando el agente procesa una consulta exitosamente. Este JSON representa los metadatos y el contenido que puedes mapear en el siguiente nodo. json { “status”: “success”, “agent_name”: “mcp_agent”, “response_text”: “He consultado la base de datos de ventas. El producto más vendido este mes es el ‘Plan Pro’, con 150 unidades. ¿Necesitas detalles específicos de los clientes?”, “tools_used”: [ “database_query_v1” ], “model_used”: “gpt-4-turbo” }

Conectividad

Este componente suele conectarse lógicamente de las siguientes maneras en un flujo de trabajo:

  1. Entrada desde Mensajes de Usuario: Se conecta frecuentemente después de un nodo de “Trigger de Chat” o “Email Parser” para recibir la pregunta del usuario.
  2. Salida a Acciones de Respuesta: Su salida Response suele ir conectada a nodos de “Enviar Email”, “Publicar en Slack” o “Responder en Webhook”.
  3. Conexión con Herramientas (MCP): Aunque el usuario no configura esto manualmente en cada nodo, el agente “conecta” internamente con las herramientas MCP definidas en el sistema Nappai para ejecutar consultas externas.

Ejemplo de Uso

Imagina que estás creando un asistente de soporte para una empresa.

  1. Paso 1: Un usuario envía un mensaje: “¿Cuál es el estado del pedido #12345?”
  2. Paso 2: Conectas este mensaje al campo Input del MCP Agent.
  3. Paso 3: En el campo MCP, seleccionas la herramienta Database_Tool que permite consultar pedidos.
  4. Paso 4: El agente consulta la base de datos, obtiene el estado “En tránsito” y responde.
  5. Paso 5: El campo Response del agente se conecta a un nodo de “Enviar WhatsApp”, que envía automáticamente la respuesta al usuario.

Consejos y Mejores Prácticas

  • Usa System Prompt para definir el tono: Si quieres que el agente sea más amigable o más técnico, utilízalo en el campo System Prompt para darle esa “personalidad” sin cambiar el código.
  • Gestiona la memoria con cuidado: Si tus flujos son de larga duración, deshabilita el Memory o limita el Memory Limit para evitar que el agente se quede sin contexto o exceda los límites de tokens de tu modelo.
  • Nombre claro: Asegúrate de que el Agent Name sea descriptivo (ej. “Soporte_Tecnico_Agent”) para facilitar el mantenimiento de tus flujos.

Consideraciones de Seguridad

  • Acceso a Datos: Recuerda que al utilizar herramientas MCP, el agente tendrá acceso a los datos vinculados a esas herramientas. Asegúrate de que las herramientas conectadas tengan los permisos adecuados y limitados a lo necesario.
  • Entradas del Usuario: Como el agente procesa texto libre en el campo Input, es buena práctica validar que las entradas no contengan intentos de inyección de prompts (instrucciones maliciosas) en el nivel de la aplicación.
  • Modo de Desarrollo: Este componente está configurado actualmente en modo de desarrollo (is_development = True). Esto es seguro para pruebas, pero asegúrate de revisar la documentación oficial de Nappai para actualizaciones de producción o cambios en el comportamiento en entornos finales.