Agentes IA — Cómo combinar los nodos

Esta página explica la lógica de uso: cómo se conectan las piezas y qué pasa en cada caso. Si venís de la visión general, acá bajamos al detalle práctico.

Dos tipos de conexión

En un agente modular conviven dos clases de conexión y es clave no confundirlas:

1. Flujo de datos — las flechas normales izquierda → derecha. Es el camino que recorre la ejecución del workflow. El AI Agent entra por su puerto izquierdo y sale por el derecho, como cualquier nodo.

2. Conexión de rol — desde la salida de un sub-nodo (cerebro/tool/RAG/skill) hacia uno de los puertos del borde inferior del agente. Esto no ejecuta el sub-nodo en el flujo: solo declara que esa pieza forma parte del agente.

Los sub-nodos no corren en el flujo

Un cerebro, una tool o una skill conectados a un puerto de rol no se ejecutan por sí solos. Son proveedores de configuración: el orquestador los lee y los usa. Por eso no necesitan (ni reciben) un nextModule hacia el agente.

Armar un agente paso a paso

1. Poné el orquestador en el flujo. Arrastrá AI Agent (orquestador) al canvas y conectá al Start (u otro nodo) su puerto de entrada izquierdo, y su salida derecha hacia donde siga el flujo.

2. Conectá un cerebro. Arrastrá Agent: Cerebro (LLM), elegí proveedor + modelo + credencial, y tirá una conexión desde su salida hasta el puerto brain (morado) del agente. Es obligatorio: sin cerebro el agente no puede razonar.

3. Agregá tools (opcional). Por cada capacidad, arrastrá Agent: Herramienta (tool), completá tool_name + tool_description + tool_schema, elegí qué ejecuta (node / workflow / registered) y conectá su salida al puerto tools (azul). Repetí por cada tool.

4. Agregá RAG (opcional). Arrastrá Agent: RAG (recuperar), configurá namespace + embeddings, y conectá su salida al puerto rag (ámbar). El agente consultará esa base antes de responder.

5. Agregá skills (opcional). Arrastrá Agent: Skill, describí cuándo aplica y qué instrucciones/tools habilita, y conectá su salida al puerto skills (rosa).

6. Guardá. Al guardar, Floogos convierte el grafo: cada conexión de rol se traduce en attach_to + role dentro de la config del sub-nodo. Ya podés ejecutar.

Qué hace el orquestador con cada pieza

Puerto	Cardinalidad	Qué hace el agente
brain	exactamente 1	Elige el proveedor/modelo y hace las llamadas al LLM.
tools	0..N	Arma el schema de funciones que le ofrece al LLM; ejecuta la que el LLM pida.
rag	0..N	Antes de responder, recupera fragmentos relevantes y los inyecta como contexto.
skills	0..N	Evalúa cuáles activar según el pedido; inyecta su prompt y habilita sus tools.

El bucle de ejecución

Cuando el agente corre, hace esto:

1. userInput = input configurado  ó  data del nodo anterior
2. systemPrompt = system_prompt
   + (si hay skills relevantes)  sus prompt_fragment
   + (si hay RAG)                los top_k fragmentos recuperados
3. tools = schema de las tools conectadas (filtradas por gating de skills)
4. respuesta = LLM(systemPrompt, userInput, tools)
5. mientras la respuesta pida tools y iteración < max_iterations:
       ejecutar cada tool  →  devolver resultados al LLM  →  nueva respuesta
6. devolver respuesta.content

Orden de precedencia del input

El agente toma como entrada, en este orden: el campo input (si lo completaste, admite plantillas como {{@NodoAnterior.data.mensaje}}), si está vacío usa data.input, luego data.message, y si nada de eso existe, el data completo serializado.

Reglas y buenas prácticas

• Un cerebro y solo uno. El puerto brain reemplaza la conexión anterior si conectás otra. Es a propósito.
• Descripciones de tools que se entiendan. El LLM decide qué tool usar leyendo su tool_description. Una descripción vaga = tool que no se usa (o se usa mal).
• Definí el tool_schema para las tools con parámetros. Sin schema, el LLM no sabe qué argumentos mandar.
• RAG: mismo modelo y namespace al indexar y al recuperar. Es el error más común (ver problemas).
• Skills para acotar, no para todo. Usalas cuando tengas comportamientos que solo aplican a ciertos pedidos y no querés inflar el prompt base ni exponer tools de más.
• max_iterations según la complejidad. Tareas con encadenamiento de varias tools necesitan más vueltas; subilo si el agente “se queda corto”.

Próximo paso

Poné todo junto con los ejemplos y recetas.

Y si prefieres no partir de cero, usa la Biblioteca de agentes: kits ya conectados que se insertan en el lienzo.