AI 智能体与工具

智能体和工具在应用仓库的 .ironflock/ai-template.yml 文件中定义。

Agent 结构

每个顶级键定义一个 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 字段

字段	说明
`tool_description`	告诉 IronFlock AI 何时将任务委派给此 Agent 的说明。请勿在此处引用内部工具。
`system_prompt`	定义 Agent 的角色、专业知识、可用工具和预期输出格式。
`main`	`true` = 对 IronFlock AI 可见。`false` = 子 Agent，只能通过委派访问。
`max_context_tokens`	每次请求的 Token 上限（约 1.3 个 Token 对应一个英文单词）。
`messages_after_summary`	对话历史中保留的最近未摘要消息数量。
`max_iterations`	Agent 停止前的最大工具调用轮次，用于防止无限循环。

工具类型

WAMP 主题工具

这些工具调用由您的边缘代码注册的 WAMP 过程：


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

WAMP 主题必须由您应用的边缘组件注册。返回值应为可读文本或 AI 可以解读的结构化数据。

委派工具

这些工具将任务委派给同一文件中定义的另一个 Agent：


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

参数类型

类型	说明
`string`	文本输入
`number`	数值
`boolean`	布尔值（真/假）
`object`	结构化 JSON 对象
`array`	值列表

子 Agent 与委派

对于复杂领域，可将 AI 集成拆分为多个专用 Agent。子 Agent 处理专项任务，而主 Agent 负责编排。

主 Agent 与子 Agent

属性	主 Agent (`main: true`)	子 Agent (`main: false`)
可见性	注册到 IronFlock AI	对 IronFlock AI 不可见
访问方式	由 IronFlock AI 直接调用	仅可通过其他 Agent 的委派访问
使用场景	应用 AI 的入口点	专业化的领域能力

何时使用子 Agent

适用于以下场景：

单个 Agent 的工具过多（超过 8–10 个）
不同任务需要不同的系统提示词或专业知识
需要隔离复杂工作流（例如配置 vs. 监控）
不同任务需要不同的 Token 上限或迭代次数

委派流程


用户 → IronFlock AI → 主 Agent → 子 Agent → WAMP 工具 → 边缘设备
                                  ↓
                           结果逐层返回

主 Agent 根据其系统提示词和委派工具的描述决定何时委派。子 Agent 独立运行，使用自己的工具，并将结果返回给主 Agent，由主 Agent 为用户汇总。

最佳实践

编写工具描述

tool_description 字段面向 IronFlock AI——它决定了您的 Agent 何时被调用。请以 IronFlock AI 的视角来编写：

好的写法：


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.

不好的写法：


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

不要在 tool_description 中引用内部工具——IronFlock AI 不需要了解这些信息。

编写系统提示词

system_prompt 定义 Agent 的行为。应包含：

角色 — Agent 是什么，它了解什么。
可用工具 — 列出每个工具及其使用场景。
输出格式 — 响应应如何组织。
防护规则 — Agent 不应做什么。


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 工具设计

返回可读数据 — AI Agent 会解读工具的返回值。请返回结构化文本或 JSON，而非原始二进制数据。
包含错误消息 — 当工具失败时，返回描述性错误消息，以便 AI 转达给用户。
保持参数简单 — 尽可能使用基本类型（string、number、boolean）。复杂的嵌套对象会增加 AI 构造正确调用的难度。
标记必填参数 — 始终为必填输入设置 required: true。

Agent 规模配置

设置	建议
`max_context_tokens`	大多数 Agent 使用 30,000 – 50,000
`messages_after_summary`	4 – 6 条消息
`max_iterations`	5 – 10（多步工作流可适当增加）

更高的值允许更复杂的交互，但会消耗更多 Token。建议从保守值开始，当 Agent 达到限制时再增加。

测试 Agent

为您的应用添加一个测试设备。
打开 IronFlock AI 聊天。
提问应触发您 Agent 的问题。
验证 AI 是否正确委派，以及您的工具是否返回预期数据。
测试错误场景——当设备离线或工具返回错误时会发生什么？

完整示例


# 主 Agent - 对 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
 
# 子 Agent - 仅可通过委派访问
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