Agentes y Herramientas de IA

Los agentes y herramientas se definen en el archivo .ironflock/ai-template.yml del repositorio de tu app.

Estructura de un agente

Cada clave de nivel superior define un agente:


my_agent:
    tool_description: |
        When to delegate to this agent and what context to provide.
        These are instructions for the IronFlock AI, not for your agent.
 
    system_prompt: |
        Define your agent's role, expertise, and guardrails.
        Describe when to use each tool and the expected output format.
 
    main: true
    max_context_tokens: 50000
    messages_after_summary: 6
    max_iterations: 10
    tools:
        my_tool:
            description: What this tool does and when to call it.
            topic: my_app.my_wamp_topic
            parameters:
                my_param:
                    type: string
                    description: What this parameter controls.
                    required: true

Campos del agente

Campo	Descripción
`tool_description`	Instrucciones para la IA de IronFlock sobre cuándo delegar a este agente. No hagas referencia a herramientas internas aquí.
`system_prompt`	Define el rol del agente, su experiencia, las herramientas disponibles y el formato de salida esperado.
`main`	`true` = visible para la IA de IronFlock. `false` = sub-agente, solo accesible mediante delegación.
`max_context_tokens`	Límite de tokens por solicitud (~1,3 tokens por palabra).
`messages_after_summary`	Número de mensajes recientes que se conservan sin resumir en el historial de conversación.
`max_iterations`	Número máximo de rondas de llamadas a herramientas antes de que el agente se detenga. Previene bucles infinitos.

Tipos de herramientas

Herramientas de topic WAMP

Estas herramientas llaman a un procedimiento WAMP registrado por tu código en el dispositivo:


tools:
    get_sensor_data:
        description: Retrieves the latest sensor readings from the device.
        topic: sensors.get_latest
        parameters:
            sensor_id:
                type: string
                description: The sensor to query.
                required: true

El topic WAMP debe estar registrado por el componente de borde de tu app. Los valores de retorno deben ser texto legible o datos estructurados que la IA pueda interpretar.

Herramientas de delegación

Estas herramientas delegan a otro agente definido en el mismo archivo:


tools:
    configure_machine:
        description: Handles complex machine configuration tasks.
        delegate: machine_expert

Tipos de parámetros

Tipo	Descripción
`string`	Entrada de texto
`number`	Valor numérico
`boolean`	Verdadero/falso
`object`	Objeto JSON estructurado
`array`	Lista de valores

Sub-agentes y delegación

Para dominios complejos, divide tu integración de IA en múltiples agentes especializados. Los sub-agentes manejan tareas enfocadas mientras el agente principal orquesta.

Agentes principales vs. sub-agentes

Propiedad	Agente principal (`main: true`)	Sub-agente (`main: false`)
Visibilidad	Registrado en la IA de IronFlock	Oculto para la IA de IronFlock
Acceso	Invocado directamente por la IA de IronFlock	Solo accesible mediante delegación desde otro agente
Caso de uso	Punto de entrada para la IA de tu app	Experiencia especializada en un dominio

Cuándo usar sub-agentes

Usa sub-agentes cuando:

Un solo agente tendría demasiadas herramientas (más de 8–10)
Diferentes tareas requieren diferentes system prompts o experiencia
Quieres aislar flujos de trabajo complejos (p. ej., configuración vs. monitoreo)
Necesitas diferentes límites de tokens o iteraciones para diferentes tareas

Flujo de delegación


User → IronFlock AI → Main Agent → Sub-Agent → WAMP Tool → Edge Device
                                  ↓
                           Result flows back

El agente principal decide cuándo delegar basándose en su system prompt y la descripción de la herramienta de delegación. El sub-agente se ejecuta de forma independiente, usa sus propias herramientas y devuelve los resultados al agente principal, que los resume para el usuario.

Buenas prácticas

Escribir descripciones de herramientas

El campo tool_description es para la IA de IronFlock — determina cuándo se invoca tu agente. Escríbelo desde la perspectiva de la IA de IronFlock:

Correcto:


tool_description: |
    Delegate to this agent when the user asks about OPC UA devices,
    PLC configuration, or industrial network scanning. Provide the
    device name or network information if available.

Incorrecto:


tool_description: |
    I am an OPC UA expert that can scan networks and configure PLCs.
    My tools include network_scan and read_catalog.

No hagas referencia a herramientas internas en tool_description — la IA de IronFlock no necesita conocerlas.

Escribir system prompts

El system_prompt define el comportamiento de tu agente. Incluye:

Rol — Qué es el agente y qué sabe.
Herramientas disponibles — Lista cada herramienta y cuándo usarla.
Formato de salida — Cómo deben estructurarse las respuestas.
Límites — Qué NO debe hacer el agente.


system_prompt: |
    You are a sensor data specialist for industrial temperature monitoring.
 
    Available tools:
    - get_reading: Use when asked for current sensor values
    - get_history: Use when asked about trends or historical data
    - set_threshold: Use when asked to configure alert limits
 
    Always include measurement units in responses.
    Never modify sensor thresholds without explicit user confirmation.
    If a sensor is not responding, suggest checking the device connection.

Diseño de herramientas WAMP

Devuelve datos legibles — El agente de IA interpretará los valores de retorno de tu herramienta. Devuelve texto estructurado o JSON, no datos binarios crudos.
Incluye mensajes de error — Cuando una herramienta falla, devuelve un mensaje de error descriptivo que la IA pueda transmitir al usuario.
Mantén los parámetros simples — Usa tipos primitivos (string, number, boolean) cuando sea posible. Los objetos anidados complejos dificultan que la IA construya llamadas correctas.
Marca los parámetros obligatorios — Siempre establece required: true para las entradas obligatorias.

Dimensionamiento de agentes

Configuración	Recomendación
`max_context_tokens`	30.000 – 50.000 para la mayoría de los agentes
`messages_after_summary`	4 – 6 mensajes
`max_iterations`	5 – 10 (aumentar para flujos de trabajo de múltiples pasos)

Los valores más altos permiten interacciones más complejas pero consumen más tokens. Comienza de forma conservadora y aumenta si los agentes alcanzan los límites.

Probar agentes

Agrega un dispositivo de prueba a tu app.
Abre el chat de IA de IronFlock.
Haz preguntas que deberían activar tu agente.
Verifica que la IA delegue correctamente y que tus herramientas devuelvan los datos esperados.
Prueba casos de error — ¿qué sucede cuando un dispositivo está desconectado o una herramienta devuelve un error?

Ejemplo completo


# Main agent - visible to IronFlock AI
factory_agent:
    main: true
    tool_description: |
        Delegate to this agent for factory automation tasks,
        including machine configuration and production monitoring.
 
    system_prompt: |
        You are a factory automation assistant. You can monitor
        production lines and configure machines.
 
        For complex machine configuration, delegate to the
        machine_config_agent using the configure_machine tool.
 
    tools:
        get_production_stats:
            description: Get current production statistics.
            topic: factory.stats
            parameters:
                line_id:
                    type: string
                    required: true
 
        configure_machine:
            description: Handles complex machine setup and configuration.
            delegate: machine_config_agent
 
# Sub-agent - only reachable via delegation
machine_config_agent:
    main: false
    system_prompt: |
        You are a machine configuration specialist. You can read
        machine parameters, update settings, and validate configurations.
 
        Always verify the current state before making changes.
        Confirm changes with the user before applying.
 
    tools:
        read_config:
            description: Read current machine configuration.
            topic: machines.read_config
            parameters:
                machine_id:
                    type: string
                    required: true
 
        write_config:
            description: Apply new configuration to a machine.
            topic: machines.write_config
            parameters:
                machine_id:
                    type: string
                    required: true
                config:
                    type: object
                    description: Configuration key-value pairs to apply.
                    required: true