Skip to Content
IoT アプリ開発AIエージェント & ツール

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_descriptionIronFlock AIに対して、いつこのエージェントに委任すべきかを指示します。内部ツールをここで参照しないでください。
system_promptエージェントの役割、専門知識、利用可能なツール、期待される出力形式を定義します。
maintrue = 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: true

WAMPトピックはアプリのエッジコンポーネントによって登録されている必要があります。戻り値は、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はエージェントの動作を定義します。以下を含めてください:

  1. 役割 — エージェントが何であり、何を知っているか。
  2. 利用可能なツール — 各ツールとその使用タイミングを列挙。
  3. 出力形式 — レスポンスの構成方法。
  4. ガードレール — エージェントがやるべきでないこと。
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がユーザーに伝えられる説明的なエラーメッセージを返してください。
  • パラメータをシンプルに保つ — 可能な限りプリミティブ型(stringnumberboolean)を使用してください。複雑なネストされたオブジェクトは、AIが正しい呼び出しを構成することを難しくします。
  • 必須パラメータをマークする — 必須の入力には必ずrequired: trueを設定してください。

エージェントのサイジング

設定推奨値
max_context_tokensほとんどのエージェントで30,000~50,000
messages_after_summary4~6メッセージ
max_iterations5~10(マルチステップワークフローの場合は増加)

値を大きくすると、より複雑なやり取りが可能になりますが、トークンコストが増加します。控えめに設定し、エージェントが上限に達した場合に増やしてください。

エージェントのテスト

  1. アプリにテストデバイスを追加します。
  2. IronFlock AIチャットを開きます。
  3. エージェントをトリガーするはずの質問をします。
  4. AIが正しく委任し、ツールが期待されるデータを返すことを確認します。
  5. エラーケースをテストします。デバイスがオフラインの場合やツールがエラーを返した場合はどうなりますか?

完全な例

# メインエージェント - 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: true
Last updated on