Agente IA

Descripcion

Este modulo es el nodo principal para gestionar conversaciones con inteligencia artificial. Al recibir un mensaje del usuario, el modulo:

1. Obtiene o crea una sesion de agente vinculada al usuario (por external_id o session_id).
2. Cancela follow-ups pendientes cuando el usuario responde.
3. Agrega el mensaje del usuario al historial de la sesion.
4. Prepara herramientas (workflows, datastores, APIs) si estan habilitadas.
5. Llama al proveedor de IA seleccionado (OpenAI, Anthropic, Google, DeepSeek, Qwen o Llama/Groq) con el historial, system prompt y personalidad configurada.
6. Si el LLM solicita ejecutar herramientas (tool calls), las ejecuta y vuelve a llamar al LLM con los resultados para generar la respuesta final.
7. Guarda la respuesta del agente en la sesion y actualiza metricas (tokens, tiempos, contadores).
8. Extrae entidades de la conversacion y las almacena en memoria persistente.
9. Programa follow-ups automaticos si hay flujos configurados.
10. Opcionalmente simula una demora humana antes de devolver la respuesta.

Si ocurre un error y el fallback esta habilitado, retorna un mensaje de error configurable en lugar de fallar el flujo completo.

Configuracion

Parametro	Tipo	Requerido	Descripcion
agent_id	text	Si	Identificador unico del agente. Se usa para vincular sesiones y configuraciones.
brain_provider	select	Si	Proveedor de IA que usara el agente como cerebro. Opciones: openai, anthropic, google, deepseek, qwen, llama.
brain_model	aiModelSelector	Si	Modelo de IA a utilizar. Los modelos se cargan segun el proveedor seleccionado. Default: gpt-4o.
credentials_key	credentials	Si	Credenciales del proveedor de IA. Tipos soportados: openai, anthropic, google_ai, deepseek, qwen, llama.
system_prompt	textarea	No	Instrucciones base para el agente. Define su personalidad, conocimientos y comportamiento.
personality	select	No	Estilo de comunicacion del agente. Opciones: professional, friendly, formal, casual, empathetic, custom. Default: professional.
max_tokens	number	No	Limite de tokens para la respuesta del agente. Min: 50, Max: 4000. Default: 1000.
temperature	number	No	Creatividad de las respuestas (0=deterministico, 2=muy creativo). Default: 0.7.
enable_memory	boolean	No	Mantener memoria de la conversacion entre mensajes. Default: true.
memory_window	number	No	Numero de mensajes a mantener en contexto. Min: 5, Max: 100. Default: 20.
enable_tools	boolean	No	Permitir que el agente ejecute herramientas (workflows, datastores, APIs). Default: false.
tools	agentTools	No	Herramientas disponibles para el agente. Solo visible si enable_tools es true.
human_delay_enabled	boolean	No	Agregar pequenas demoras para simular escritura humana. Default: true.
human_delay_min_ms	number	No	Demora minima en milisegundos. Default: 500.
human_delay_max_ms	number	No	Demora maxima en milisegundos. Default: 3000.
error_message	textarea	No	Mensaje a mostrar cuando ocurre un error.
error_fallback_enabled	boolean	No	Continuar el flujo con mensaje de error en lugar de fallar completamente. Default: true.

Credenciales

Se requiere configurar credentials_key con las credenciales del proveedor de IA seleccionado. Los tipos de credenciales soportados son: openai, anthropic, google_ai, deepseek, qwen, llama. Las credenciales se obtienen de la tabla client_credentials por credential_key.

Salida

{
  "success": true,
  "response": "Texto de respuesta del agente",
  "session_id": "uuid-de-la-sesion",
  "session_status": "active",
  "message_count": 12,
  "tokens_used": {
    "prompt": 350,
    "completion": 120,
    "total": 470
  },
  "tool_calls": [
    { "name": "buscar_producto", "success": true }
  ],
  "execution_time_ms": 2340,
  "memory": {
    "entities": { "nombre": "Juan", "email": "juan@ejemplo.com" }
  }
}

Ejemplo de Uso

Caso basico

{
  "agent_id": "agente-ventas-01",
  "brain_provider": "openai",
  "brain_model": "gpt-4o",
  "credentials_key": "mi-clave-openai",
  "system_prompt": "Eres un asistente de ventas amable y profesional.",
  "personality": "friendly",
  "max_tokens": 1000,
  "temperature": 0.7,
  "enable_memory": true,
  "memory_window": 20
}

Datos de entrada esperados

El modulo espera recibir en inputData:

• message / text / content: El mensaje del usuario (requerido).
• external_id / user_id / from: Identificador externo del usuario.
• channel: Canal de comunicacion (default: “workflow”).
• session_id: ID de sesion existente (opcional).

API Utilizada

Depende del proveedor seleccionado:

• OpenAI: API de Chat Completions.
• Anthropic: API de Claude Messages.
• Google: API de Gemini generateContent.
• DeepSeek / Qwen / Llama (Groq): APIs compatibles con OpenAI.

Notas

• El agente gestiona sesiones persistentes en base de datos con historial completo de mensajes.
• La ventana de memoria (memory_window) controla cuantos mensajes se envian como contexto al LLM.
• Las herramientas se ejecutan secuencialmente; si alguna falla, el resultado de error se incluye en el contexto.
• La demora humana se calcula proporcionalmente a la longitud de la respuesta.
• Los follow-ups se programan automaticamente si existen flujos configurados para el agente.
• Cuando el fallback de error esta habilitado, el flujo continua con success: false y el mensaje de error configurado.

Nodos Relacionados

• AgentDecision - Decision del Agente
• AgentSendFollowUp - Enviar Seguimiento
• agentChat - Agente IA Conversacional