AI Agents & Tools

Agents and tools are defined in the .ironflock/ai-template.yml file in your app’s repository.

Agent Structure

Each top-level key defines an agent:


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

Agent Fields

Field	Description
`tool_description`	Instructions for the IronFlock AI on when to delegate to this agent. Do not reference internal tools here.
`system_prompt`	Defines the agent’s role, expertise, available tools, and expected output format.
`main`	`true` = visible to the IronFlock AI. `false` = sub-agent, only reachable via delegation.
`max_context_tokens`	Token limit per request (~1.3 tokens per word).
`messages_after_summary`	Number of recent messages kept unsummarized in conversation history.
`max_iterations`	Maximum tool-call rounds before the agent stops. Prevents infinite loops.

Tool Types

WAMP Topic Tools

These tools call a WAMP procedure registered by your edge code:


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

The WAMP topic must be registered by your app’s edge component. Return values should be readable text or structured data that the AI can interpret.

Delegation Tools

These tools delegate to another agent defined in the same file:


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

Parameter Types

Type	Description
`string`	Text input
`number`	Numeric value
`boolean`	True/false
`object`	Structured JSON object
`array`	List of values

Sub-Agents & Delegation

For complex domains, break your AI integration into multiple specialized agents. Sub-agents handle focused tasks while the main agent orchestrates.

Main vs. Sub-Agents

Property	Main Agent (`main: true`)	Sub-Agent (`main: false`)
Visibility	Registered with IronFlock AI	Hidden from IronFlock AI
Access	Directly invoked by the IronFlock AI	Only reachable via delegation from another agent
Use case	Entry point for your app’s AI	Specialized domain expertise

When to Use Sub-Agents

Use sub-agents when:

A single agent would have too many tools (more than 8–10)
Different tasks require different system prompts or expertise
You want to isolate complex workflows (e.g., configuration vs. monitoring)
You need different token limits or iteration counts for different tasks

Delegation Flow


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

The main agent decides when to delegate based on its system prompt and the delegation tool’s description. The sub-agent runs independently, uses its own tools, and returns results to the main agent, which summarizes them for the user.

Best Practices

Writing Tool Descriptions

The tool_description field is for the IronFlock AI — it determines when your agent is invoked. Write it from the perspective of the IronFlock AI:

Good:


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.

Bad:


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

Don’t reference internal tools in tool_description — the IronFlock AI doesn’t need to know about them.

Writing System Prompts

The system_prompt defines your agent’s behavior. Include:

Role — What the agent is and what it knows.
Available tools — List each tool and when to use it.
Output format — How responses should be structured.
Guardrails — What the agent should NOT do.


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.

WAMP Tool Design

Return readable data — The AI agent will interpret your tool’s return values. Return structured text or JSON, not raw binary data.
Include error messages — When a tool fails, return a descriptive error message the AI can relay to the user.
Keep parameters simple — Use primitive types (string, number, boolean) when possible. Complex nested objects make it harder for the AI to construct correct calls.
Mark required parameters — Always set required: true for mandatory inputs.

Agent Sizing

Setting	Recommendation
`max_context_tokens`	30,000 – 50,000 for most agents
`messages_after_summary`	4 – 6 messages
`max_iterations`	5 – 10 (increase for multi-step workflows)

Higher values allow more complex interactions but cost more tokens. Start conservative and increase if agents hit limits.

Testing Agents

Add a test device to your app.
Open the IronFlock AI chat.
Ask questions that should trigger your agent.
Verify that the AI correctly delegates and your tools return expected data.
Test error cases — what happens when a device is offline or a tool returns an error?

Complete Example


# 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