AI Agent

1. Visión General

El componente AI Agent (ai-agent) ejecuta un agente de inteligencia artificial dentro del flujo, capaz de razonar sobre una o más tareas, decidir qué hacer y, si es necesario, usar otros componentes de la plataforma como "herramientas" durante la ejecución. Es adecuado cuando el flujo necesita una etapa que interprete lenguaje natural, tome decisiones más flexibles o combine varias subtareas con el apoyo de un modelo de lenguaje (LLM).

Úsalo cuando la lógica no puede resolverse solo con reglas fijas (Choice, ForEach, etc.) y se beneficia de la flexibilidad de un modelo de IA — por ejemplo, interpretar un pedido en texto libre, resumir documentos, u orquestar múltiples subtareas que dependen del contexto. No lo uses para lógica determinista simple, donde los componentes tradicionales son más predecibles, más baratos y más rápidos.

Soporta cualquier modelo de lenguaje compatible con la URL configurada (permite apuntar a proveedores personalizados/compatibles, a través del campo modelUrl), además del modelo por defecto del proveedor.

2. Prerrequisitos

Una clave de API (apiKey) válida para el proveedor del modelo de IA elegido.
Conocimiento del identificador exacto del modelo a usar (model).
Si se usa un proveedor personalizado o compatible (no el por defecto), es necesario conocer la URL base de ese servicio (modelUrl).
Al menos una tarea (tasks) definida con nombre, descripción e instrucción.

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
`apiKey`	Sí	Expresión	Clave de autenticación usada para acceder al modelo de IA.	Una expresión que busca la clave en una variable segura
`model`	Sí	Texto	Identificador del modelo de IA a usar.	`"gpt-4o"`
`modelUrl`	No	Texto	URL base personalizada del proveedor del modelo, usada cuando no se utiliza el endpoint por defecto (por ejemplo, un proveedor compatible autoalojado). Si no se informa, usa el valor por defecto del proveedor del modelo.	`"https://mi-proveedor.ejemplo.com/v1"`

4. Configuración / Operaciones Soportadas

El AI Agent tiene una única operación: ejecutar el agente con un prompt de entrada y devolver la respuesta generada.

Configuración del agente (definida una vez, al iniciar el flujo)

Campo	Obligatorio	Tipo	Descripción	Ejemplo
`name`	Sí	Texto	Nombre del agente.	`"AgenteAtencion"`
`description`	Sí	Texto	Descripción del rol del agente, usada internamente para orientar su comportamiento.	`"Agente responsable de atender dudas de clientes"`
`taskOrchestration`	Sí	Texto: `SEQUENTIAL`, `PARALLEL`, `LOOP` o `DYNAMIC`	Define cómo se ejecutarán las tareas configuradas: en secuencia, en paralelo, en bucle, o de forma dinámica (el propio agente decide el orden y delega las tareas). Un valor no reconocido cae automáticamente en `SEQUENTIAL`.	`"DYNAMIC"`
`tasks`	Sí	Lista de objetos	Lista de tareas que el agente puede ejecutar (ver tabla abajo). No puede estar vacía.	Ver ejemplo práctico
`instructionPlanTasks`	No	Texto	Instrucciones adicionales sobre cómo coordinar las tareas, usadas solo en el modo `DYNAMIC`. Valor por defecto: vacío.	`"Prioriza tareas relacionadas con pagos"`
`temperature`	No	Texto (número decimal)	Controla la creatividad/aleatoriedad de las respuestas del modelo. Valor por defecto: `"0.7"`. Cuanto más cerca de 0, más determinista; cuanto más cerca de 1, más creativo.	`"0.3"`
`memoryType`	No	Texto: `NO_MEMORY` o `IN_LOCAL_MEMORY`	Define si el agente recuerda conversaciones anteriores del mismo usuario. `NO_MEMORY` (por defecto): cada ejecución es aislada. `IN_LOCAL_MEMORY`: mantiene el historial en memoria durante la sesión.	`"IN_LOCAL_MEMORY"`
`sessionTimeoutMinutes`	No	Texto (número)	Tiempo, en minutos, que una sesión de memoria permanece activa sin uso. Valor por defecto: `"30"`.	`"60"`
`maxMessages`	No	Texto (número)	Número máximo de mensajes mantenidos en el historial de la sesión. Valor por defecto: `"0"` (sin límite definido en el ejemplo por defecto).	`"20"`
`maxOutputTokens`	No	Texto (número)	Límite de tamaño de la respuesta generada por el modelo, en tokens. Valor por defecto: `"4192"`.	`"2000"`
`returnTokens`	No	Texto ("true"/"false")	Si es `true`, incluye información de consumo de tokens en el monitoreo de la ejecución. Valor por defecto: `"false"`.	`"true"`

Cada ítem de la lista `tasks`

Campo	Obligatorio	Tipo	Descripción	Ejemplo
`name`	Sí	Texto	Nombre de la tarea (en el modo `DYNAMIC`, corresponde al nombre del agente que la ejecuta).	`"resumirDocumento"`
`description`	Sí	Texto	Descripción de lo que hace la tarea.	`"Resume el contenido de un documento"`
`instruction`	Sí	Texto	Instrucción detallada de cómo debe ejecutarse la tarea (el "prompt" de la tarea).	`"Lee el texto enviado y produce un resumen de hasta 5 líneas"`
`outputKey`	No	Texto	Nombre de la clave donde se guarda el resultado de esa tarea, para ser referenciado por otras tareas.	`"resumen"`
`componentTools`	No	Lista de objetos	Componentes de la plataforma que el agente puede usar como herramientas durante esa tarea. Cada ítem define una descripción del componente, una descripción del cuerpo esperado, y la configuración del componente en sí.	Un componente de búsqueda en base de datos puesto a disposición como herramienta

Entrada de ejecución (en cada llamada al agente durante el flujo)

Campo	Obligatorio	Tipo	Descripción	Ejemplo
`prompt`	Sí	Expresión	Texto/pregunta enviado al agente en esta ejecución.	`"¿Cuál es el estado del pedido 123?"`
`userId`	No	Expresión	Identificador del usuario, usado para mantener memoria por usuario cuando `memoryType` está activado. Si no se informa, usa el nombre del paso como identificador.	`"cliente-456"`
`files`	No	Expresión (JSON)	Lista de archivos a enviar junto con el prompt (por ejemplo, para tareas multimodales). Cada ítem necesita `name` (nombre de la propiedad del mensaje donde está el archivo) y `mimeType` (tipo del archivo).	`[{"name": "comprobante", "mimeType": "application/pdf"}]`

Comportamiento en caso de error: si algún campo obligatorio no se informa (nombre, modelo, clave de API, descripción, orquestación, tareas), el flujo falla ya al iniciar, antes de procesar cualquier ejecución. Si prompt no se informa en una ejecución, esa ejecución falla. Si un archivo referenciado en files no existe en el mensaje, la ejecución falla.

5. Ejemplos Prácticos

Ejemplo simple: un agente único, con orquestación SEQUENTIAL y una sola tarea llamada "responderDuda", configurado para responder preguntas de clientes en texto libre. En cada ejecución, el flujo envía el texto de la pregunta del cliente en el campo prompt y recibe la respuesta generada por el agente.

Configuración del componente (definida una vez, al iniciar el flujo):

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "AgenteAtencion",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agente responsable de atender dudas de clientes",
    "taskOrchestration": "SEQUENTIAL",
    "tasks": [
      {
        "name": "responderDuda",
        "description": "Responde dudas generales de clientes",
        "instruction": "Responde de forma clara y educada a la pregunta del cliente"
      }
    ]
  }
}

Entrada (en cada ejecución, dentro del flujo):

{
  "pergunta": "¿Cuál es el plazo de entrega para el CP 01310-000?"
}

En esa ejecución, el campo prompt del componente se configura apuntando al texto de la pregunta:

{
  "prompt": "{$.body.pergunta}"
}

Respuesta:

{
  "pergunta": "¿Cuál es el plazo de entrega para el CP 01310-000?",
  "response": "El plazo estimado de entrega para ese código postal es de 3 a 5 días hábiles."
}

Ejemplo avanzado: un agente con orquestación DYNAMIC y tres tareas ("consultarPedido", "consultarStock", "generarRespuesta"), cada una con su propia instrucción. La tarea "consultarPedido" tiene una herramienta configurada en componentTools que apunta a un componente de consulta a un sistema interno. El agente recibe un prompt en lenguaje natural (por ejemplo, "¿cuándo va a llegar mi pedido 123?"), decide por sí solo qué tareas ejecutar y en qué orden, usando la herramienta configurada cuando sea necesario, y devuelve la respuesta final consolidada. En este escenario, también se envía un archivo (files) con el comprobante de compra del cliente, para que el agente lo considere en el análisis.

Configuración del componente:

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "AgenteSoporte",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agente responsable de consultar pedidos y stock y responder al cliente",
    "taskOrchestration": "DYNAMIC",
    "tasks": [
      {
        "name": "consultarPedido",
        "description": "Consulta el estado de un pedido",
        "instruction": "Usa la herramienta de consulta de pedidos para buscar el estado por el número informado",
        "outputKey": "statusPedido",
        "componentTools": [
          {
            "componentDescription": "Consulta pedidos en el sistema interno",
            "bodyDescription": "Recibe el número del pedido y devuelve estado y previsión de entrega",
            "component": { "componentName": "http", "configurations": { "url": "https://api.interna.ejemplo.com/pedidos" } }
          }
        ]
      },
      {
        "name": "consultarStock",
        "description": "Consulta disponibilidad en stock",
        "instruction": "Verifica si el producto del pedido está disponible en stock"
      },
      {
        "name": "generarRespuesta",
        "description": "Arma la respuesta final para el cliente",
        "instruction": "Combina la información de pedido y stock en una respuesta clara para el cliente"
      }
    ]
  }
}

Entrada (ejecución):

{
  "pergunta": "¿cuándo va a llegar mi pedido 123?",
  "comprobante": "<archivo del comprobante de compra, provisto por un paso anterior>"
}

Campos de ejecución del componente:

{
  "prompt": "{$.body.pergunta}",
  "files": "[{\"name\": \"comprobante\", \"mimeType\": \"application/pdf\"}]"
}

Respuesta:

{
  "pergunta": "¿cuándo va a llegar mi pedido 123?",
  "response": "Tu pedido 123 está en camino y la previsión de entrega es el día 25/07."
}

6. Puntos de atención

Exige al menos una tarea configurada en tasks.
La memoria (IN_LOCAL_MEMORY) queda en memoria local de la aplicación; no se persiste en base de datos, así que se pierde si la aplicación se reinicia o la sesión expira.
El modo DYNAMIC depende de la capacidad del modelo de IA elegido para interpretar correctamente la coordinación entre tareas — la calidad del resultado varía según el modelo.
maxOutputTokens limita el tamaño de la respuesta generada.
Los archivos enviados en files deben estar disponibles en el mensaje como archivo, secuencia de bytes o texto.

7. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"Agent name is required" / "Agent model is required" / "ApiKey is required" / "Agent description is required" / "taskOrchestration is required"	Algún campo obligatorio de configuración del agente no fue completado.	Completar todos los campos obligatorios listados en la sección de configuración.
"Agent tasks are required"	El campo `tasks` está vacío o no fue informado.	Configurar al menos una tarea en `tasks`.
"Task name are required" / "Task description are required" / "Task instruction are required"	Una de las tareas en `tasks` no tiene `name`, `description` o `instruction`.	Completar todos los campos obligatorios de cada tarea.
"Prompt not found"	El campo `prompt` no fue informado en la ejecución.	Garantizar que el mensaje/expresión de `prompt` resuelva a un valor no vacío.
"Failed to parse 'files' as JSON array"	El valor resuelto de `files` no es un JSON de lista válido.	Verificar el formato de la expresión usada en `files`.
"File entry requires 'name'" / "File entry '[nombre]' requires 'mimeType'"	Un ítem de la lista `files` no tiene `name` o `mimeType`.	Completar ambos campos en cada ítem de `files`.
"File [nombre] not found inside the execution context."	El archivo referenciado en `files` no está presente en el mensaje con ese nombre.	Confirmar que un paso anterior del flujo puso el archivo a disposición con ese nombre exacto.
"Unsupported file type for [nombre]: [tipo]. Expected File, byte\[\] or String."	El valor de la propiedad referenciada en `files` no es un archivo, secuencia de bytes ni texto.	Garantizar que el dato provisto en el mensaje esté en uno de los formatos soportados.

1. Visión General​

2. Prerrequisitos​

3. Autenticación y Conexión​

4. Configuración / Operaciones Soportadas​

Configuración del agente (definida una vez, al iniciar el flujo)​

Cada ítem de la lista tasks​

Entrada de ejecución (en cada llamada al agente durante el flujo)​

5. Ejemplos Prácticos​

6. Puntos de atención​

7. Errores Comunes y Troubleshooting​