AIエージェント & ツール
エージェントとツールは、アプリのリポジトリ内の.ironflock/ai-template.ymlファイルで定義します。
エージェントの構造
各トップレベルキーがエージェントを定義します:
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エージェントのフィールド
| フィールド | 説明 |
|---|---|
tool_description | IronFlock AIに対して、いつこのエージェントに委任すべきかを指示します。内部ツールをここで参照しないでください。 |
system_prompt | エージェントの役割、専門知識、利用可能なツール、期待される出力形式を定義します。 |
main | true = IronFlock AIに表示されます。false = サブエージェントとして、委任経由でのみアクセス可能です。 |
max_context_tokens | リクエストあたりのトークン上限(1ワードあたり約1.3トークン)。 |
messages_after_summary | 会話履歴で要約されずに保持される直近のメッセージ数。 |
max_iterations | エージェントが停止するまでのツール呼び出しラウンドの最大数。無限ループを防止します。 |
ツールの種類
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: trueWAMPトピックはアプリのエッジコンポーネントによって登録されている必要があります。戻り値は、AIが解釈可能な読みやすいテキストまたは構造化データにしてください。
委任ツール
同じファイル内で定義された別のエージェントに委任するツールです:
tools:
configure_machine:
description: Handles complex machine configuration tasks.
delegate: machine_expertパラメータの型
| 型 | 説明 |
|---|---|
string | テキスト入力 |
number | 数値 |
boolean | 真/偽 |
object | 構造化JSONオブジェクト |
array | 値のリスト |
サブエージェントと委任
複雑なドメインでは、AI連携を複数の専門エージェントに分割します。サブエージェントが特定のタスクを処理し、メインエージェントがオーケストレーションを行います。
メインエージェントとサブエージェント
| プロパティ | メインエージェント(main: true) | サブエージェント(main: false) |
|---|---|---|
| 可視性 | IronFlock AIに登録 | IronFlock AIからは非表示 |
| アクセス | IronFlock AIから直接呼び出し | 他のエージェントからの委任でのみアクセス可能 |
| 用途 | アプリAIのエントリーポイント | 専門的なドメイン知識 |
サブエージェントを使用するタイミング
以下の場合にサブエージェントを使用してください:
- 1つのエージェントでは多すぎるツール(8~10個以上)がある場合
- タスクごとに異なるシステムプロンプトや専門知識が必要な場合
- 複雑なワークフローを分離したい場合(例:設定とモニタリング)
- タスクごとに異なるトークン制限やイテレーション数が必要な場合
委任フロー
ユーザー → IronFlock AI → メインエージェント → サブエージェント → WAMPツール → エッジデバイス
↓
結果が返されるメインエージェントは、自身のシステムプロンプトと委任ツールの説明に基づいて、委任するタイミングを決定します。サブエージェントは独立して実行され、独自のツールを使用し、結果をメインエージェントに返します。メインエージェントはそれをユーザー向けに要約します。
ベストプラクティス
ツール説明の書き方
tool_descriptionフィールドはIronFlock AI向けのものです。これにより、エージェントがいつ呼び出されるかが決まります。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はエージェントの動作を定義します。以下を含めてください:
- 役割 — エージェントが何であり、何を知っているか。
- 利用可能なツール — 各ツールとその使用タイミングを列挙。
- 出力形式 — レスポンスの構成方法。
- ガードレール — エージェントがやるべきでないこと。
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エージェントはツールの戻り値を解釈します。構造化テキストまたはJSONを返してください。生のバイナリデータは避けてください。
- エラーメッセージを含める — ツールが失敗した場合、AIがユーザーに伝えられる説明的なエラーメッセージを返してください。
- パラメータをシンプルに保つ — 可能な限りプリミティブ型(
string、number、boolean)を使用してください。複雑なネストされたオブジェクトは、AIが正しい呼び出しを構成することを難しくします。 - 必須パラメータをマークする — 必須の入力には必ず
required: trueを設定してください。
エージェントのサイジング
| 設定 | 推奨値 |
|---|---|
max_context_tokens | ほとんどのエージェントで30,000~50,000 |
messages_after_summary | 4~6メッセージ |
max_iterations | 5~10(マルチステップワークフローの場合は増加) |
値を大きくすると、より複雑なやり取りが可能になりますが、トークンコストが増加します。控えめに設定し、エージェントが上限に達した場合に増やしてください。
エージェントのテスト
- アプリにテストデバイスを追加します。
- IronFlock AIチャットを開きます。
- エージェントをトリガーするはずの質問をします。
- AIが正しく委任し、ツールが期待されるデータを返すことを確認します。
- エラーケースをテストします。デバイスがオフラインの場合やツールがエラーを返した場合はどうなりますか?
完全な例
# メインエージェント - 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
# サブエージェント - 委任でのみアクセス可能
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: trueLast updated on