Agentes e Ferramentas de IA

Agentes e ferramentas são definidos no arquivo .ironflock/ai-template.yml no repositório do seu app.

Estrutura do Agente

Cada chave de nível superior define um 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 do Agente

Campo	Descrição
`tool_description`	Instruções para a IA do IronFlock sobre quando delegar a este agente. Não faça referência a ferramentas internas aqui.
`system_prompt`	Define o papel do agente, sua especialidade, as ferramentas disponíveis e o formato de saída esperado.
`main`	`true` = visível para a IA do IronFlock. `false` = subagente, acessível apenas por delegação.
`data_access`	Opcional. `true` dá a este agente acesso SQL somente leitura às tabelas de dados do próprio app, pelas ferramentas integradas `get_schema` e `execute_sql`. Nunca aos dados de outro app.
`file_access`	Opcional. `true` dá a este agente acesso somente leitura aos arquivos armazenados do próprio app, pelas ferramentas integradas `list_app_files` e `read_app_file`. A busca é feita nos caminhos, não no conteúdo, e PDFs e outros formatos binários não podem ser lidos.
`log_access`	Opcional. `true` dá a este agente acesso somente leitura à saída de log dos contêineres do próprio app, pela ferramenta integrada `get_app_logs`. Nunca os logs de outro app, e apenas nos dispositivos que o usuário já pode ver.
`web_search`	Opcional. `true` dá a este agente a ferramenta integrada `web_search`, que pesquisa a internet pública e devolve uma resposta resumida com links para as fontes — para fichas técnicas, códigos de erro ou tudo o que os dados do próprio app não conseguem responder. A consulta é enviada a um fornecedor de pesquisa externo, por isso indique no `system_prompt` o que o agente pode pesquisar.
`max_context_tokens`	Limite de tokens por requisição (~1,3 token por palavra).
`messages_after_summary`	Número de mensagens recentes mantidas sem resumo no histórico da conversa.
`max_iterations`	Número máximo de rodadas de chamadas de ferramentas antes de o agente parar. Evita laços infinitos.
`effort`	Opcional. Quanto raciocínio o modelo gasta por turno: `low`, `medium` ou `high` (o padrão).

effort troca qualidade de resposta por velocidade e custo. Níveis mais baixos tornam cada rodada de chamadas de ferramentas mais rápida e barata; high é o que a plataforma usa quando o campo é omitido. Escolha o nível por medição, não por suposição: execute as tarefas típicas do seu agente em cada nível e fique com o mais baixo que ainda acerta todas elas.

Tipos de Ferramentas

Ferramentas de Tópico WAMP

Estas ferramentas chamam um procedimento WAMP registrado pelo seu código de borda:


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

O tópico WAMP precisa ser registrado pelo componente de borda do seu app. Os valores retornados devem ser texto legível ou dados estruturados que a IA consiga interpretar.

Ferramentas de Delegação

Estas ferramentas delegam a outro agente definido no mesmo arquivo:


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

Tipos de Parâmetros

Tipo	Descrição
`string`	Entrada de texto
`number`	Valor numérico
`boolean`	Verdadeiro/falso
`object`	Objeto JSON estruturado
`array`	Lista de valores

Subagentes e Delegação

Para domínios complexos, divida sua integração de IA em vários agentes especializados. Os subagentes cuidam de tarefas focadas enquanto o agente principal orquestra.

Agente Principal vs. Subagente

Propriedade	Agente Principal (`main: true`)	Subagente (`main: false`)
Visibilidade	Registrado na IA do IronFlock	Oculto da IA do IronFlock
Acesso	Invocado diretamente pela IA do IronFlock	Acessível apenas por delegação de outro agente
Caso de uso	Ponto de entrada da IA do seu app	Especialidade de domínio

Quando Usar Subagentes

Use subagentes quando:

Um único agente teria ferramentas demais (mais de 8–10)
Tarefas diferentes exigem prompts de sistema ou especialidades diferentes
Você quer isolar fluxos de trabalho complexos (por exemplo, configuração vs. monitoramento)
Você precisa de limites de tokens ou de iterações diferentes para tarefas diferentes

Fluxo de Delegação


Usuário → IA IronFlock → Agente Principal → Subagente → Ferramenta WAMP → Dispositivo de Borda
                                           ↓
                                   O resultado retorna

O agente principal decide quando delegar com base em seu prompt de sistema e na descrição da ferramenta de delegação. O subagente executa de forma independente, usa suas próprias ferramentas e devolve os resultados ao agente principal, que os resume para o usuário.

Boas Práticas

Escrevendo Descrições de Ferramentas

O campo tool_description é para a IA do IronFlock — é ele que determina quando seu agente é invocado. Escreva-o da perspectiva da IA do IronFlock:

Bom:


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.

Ruim:


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

Não cite ferramentas internas em tool_description — a IA do IronFlock não precisa saber delas.

Escrevendo Prompts de Sistema

O system_prompt define o comportamento do seu agente. Inclua:

Papel — o que o agente é e o que ele sabe.
Ferramentas disponíveis — liste cada ferramenta e quando usá-la.
Formato de saída — como as respostas devem ser estruturadas.
Limites — o que o agente NÃO deve fazer.


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.

Projeto de Ferramentas WAMP

Retorne dados legíveis — o agente de IA vai interpretar os valores retornados pela sua ferramenta. Retorne texto estruturado ou JSON, não dados binários brutos.
Inclua mensagens de erro — quando uma ferramenta falhar, retorne uma mensagem descritiva que a IA possa repassar ao usuário.
Mantenha os parâmetros simples — use tipos primitivos (string, number, boolean) sempre que possível. Objetos aninhados complexos dificultam que a IA construa chamadas corretas.
Marque os parâmetros obrigatórios — sempre defina required: true para entradas obrigatórias.

Dimensionamento do Agente

Configuração	Recomendação
`max_context_tokens`	30.000 – 50.000 para a maioria dos agentes
`messages_after_summary`	4 – 6 mensagens
`max_iterations`	5 – 10 (aumente para fluxos de várias etapas)

Valores mais altos permitem interações mais complexas, mas custam mais tokens. Comece conservador e aumente se os agentes atingirem os limites.

Testando Agentes

Adicione um dispositivo de teste ao seu app.
Abra o chat da IA do IronFlock.
Faça perguntas que devem acionar seu agente.
Verifique se a IA delega corretamente e se suas ferramentas retornam os dados esperados.
Teste casos de erro — o que acontece quando um dispositivo está offline ou uma ferramenta retorna erro?

Exemplo 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