Ir al contenido
Floogos

Agentes IA — Problemas frecuentes y soluciones

Guía de troubleshooting. Cada caso describe el síntoma, la causa y cómo configurarlo para resolverlo.

”El agente no tiene un cerebro conectado”

Sección titulada «”El agente no tiene un cerebro conectado”»

Síntoma: el agente falla de entrada con ese mensaje y no responde.

Causa: no hay ningún Cerebro (LLM) conectado al puerto brain, o el sub-nodo quedó sin attach_to/role.

Solución:

  • Verificá que arrastraste la salida del cerebro hasta el puerto brain (el morado, abajo del agente), no a otro puerto.
  • Si lo configuraste a mano, confirmá que el cerebro tenga role = brain y attach_to = el alias exacto del agente (ej. aiAgent_1).
  • Recordá: un solo cerebro. Si conectaste dos, el último reemplaza al anterior.

La tool nunca se ejecuta

Sección titulada «La tool nunca se ejecuta»

Síntoma: el agente responde, pero ignora la herramienta aunque el pedido la amerita.

Causas y soluciones:

  1. Descripción pobre. El LLM decide usar una tool leyendo su tool_description. Si es vaga, no la usa. → Escribí una descripción explícita: qué hace y cuándo usarla.

  2. La tool está gated por una skill. Si el tool_name figura en el enables_tools de una skill, solo aparece cuando esa skill se activa. → O activás la skill (con sus keywords), o sacás la tool del enables_tools.

  3. max_iterations muy bajo. Si la tarea encadena varias tools, el bucle puede cortarse antes. → Subí max_iterations en el agente.

  4. Falta el tool_schema. Sin schema, el LLM no sabe qué argumentos pasar y puede evitar la tool. → Definí el schema JSON de los parámetros.

La tool se ejecuta pero da error

Sección titulada «La tool se ejecuta pero da error»

Síntoma: en el trace ves el error Nodo 'X' no encontrado o un error del nodo ejecutado.

Causas y soluciones:

  • node_type mal escrito. Debe ser el tipo real del nodo (ej. el nodo CSV es csvparce, no csvRead). → Verificá el nombre exacto en la paleta o en la lista de módulos.
  • Faltan datos base del nodo. Algunos nodos necesitan config fija (credenciales, endpoint…). → Cargala en node_config (JSON). Se combina con los argumentos que decide el LLM.
  • Credencial del nodo-tool. Si el nodo ejecutado necesita credencial (ej. un ERP), pasá su id en node_config.

RAG devuelve resultados vacíos o irrelevantes

Sección titulada «RAG devuelve resultados vacíos o irrelevantes»

Síntoma: el agente no encuentra el contexto, responde genérico o “no tengo esa información”.

Causa #1 — namespace distinto. Indexaste en un namespace y recuperás desde otro. → Usá exactamente el mismo namespace en RAG (indexar) y RAG (recuperar).

Causa #2 — modelo de embeddings distinto. Los embeddings de indexación y de consulta deben venir del mismo modelo; si no, los vectores no son comparables. → Igualá provider + model en ambos nodos (ej. openai / text-embedding-3-small en los dos).

Causa #3 — nunca se indexó. El workflow de ingesta no corrió, o corrió sin datos. → Ejecutá primero la ingesta y confirmá que hubo indexed > 0 en su salida.

Causa #4 — top_k muy bajo o chunks muy grandes. → Subí top_k, o bajá chunk_size en la ingesta para fragmentos más específicos.

La skill no se activa (o se activa siempre)

Sección titulada «La skill no se activa (o se activa siempre)»

Síntoma: la skill no aplica cuando debería, o al revés.

Causa: la activación depende de que el pedido del usuario coincida con las keywords o con palabras de la description.

Solución:

  • Si no se activa: agregá keywords más representativas (CSV) del vocabulario real del usuario.
  • Si se activa de más: acotá las keywords y hacé la description más específica.
  • Recordá que las tools en enables_tools quedan ocultas hasta que la skill se activa — si esa tool tiene que estar siempre, no la pongas en una skill.

Error de credenciales / 401 / modelo no encontrado

Sección titulada «Error de credenciales / 401 / modelo no encontrado»

Síntoma: el cerebro falla al llamar al LLM.

Soluciones:

  • Confirmá que la credentials_id del cerebro corresponde al provider elegido (una key de OpenAI no sirve para Anthropic).
  • Verificá que el model exista para ese proveedor (ej. gpt-4o, claude-sonnet-5, mistral-large-latest).
  • Para LLM local: la credencial local debe tener la base URL correcta y el servidor (Ollama/vLLM) tiene que estar levantado y con el modelo cargado.

Los sub-nodos “corren solos” o aparecen en el flujo

Sección titulada «Los sub-nodos “corren solos” o aparecen en el flujo»

Síntoma: parece que el cerebro/tool/skill se ejecuta por su cuenta.

Causa: se conectaron como flujo de datos (flecha a los puertos izquierdo/derecho) en vez de al puerto de rol (borde inferior).

Solución: borrá esa conexión y arrastrá la salida del sub-nodo al puerto de rol correspondiente del agente. Los sub-nodos de rol no deben tener flechas de flujo hacia el agente; el orquestador los consume, no los ejecuta en la secuencia.

El agente “se queda corto” en tareas complejas

Sección titulada «El agente “se queda corto” en tareas complejas»

Síntoma: deja tareas a medias cuando requieren varios pasos con tools.

Solución:

  • Subí max_iterations (cada vuelta = una ronda de tool calls).
  • Dividí capacidades grandes en tools más chicas y bien descritas.
  • Considerá una tool de tipo workflow que encapsule un proceso multi-paso en una sola llamada.

Volver al principio

Sección titulada «Volver al principio»