AI Ajanları & Araçları

Ajanlar ve araçlar, uygulama deponuzdaki .ironflock/ai-template.yml dosyasında tanımlanır.

Ajan Yapısı

Her üst düzey anahtar bir ajan tanımlar:


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

Ajan Alanları

Alan	Açıklama
`tool_description`	IronFlock AI için bu ajana ne zaman yetki devredeceğine dair talimatlar. Burada dahili araçlara atıfta bulunmayın.
`system_prompt`	Ajanın rolünü, uzmanlığını, kullanılabilir araçları ve beklenen çıktı formatını tanımlar.
`main`	`true` = IronFlock AI’ya görünür. `false` = alt ajan, yalnızca yetkilendirme yoluyla erişilebilir.
`max_context_tokens`	İstek başına token sınırı (~kelime başına 1,3 token).
`messages_after_summary`	Konusma geçmişinde özetlenmemiş olarak tutulan son mesaj sayısı.
`max_iterations`	Ajanın durmadan önce gerçekleştirebileceği maksimum araç çağrısı turu. Sonsuz döngüleri önler.

Araç Türleri

WAMP Topic Araçları

Bu araçlar, edge kodunuz tarafından kaydedilen bir WAMP procedürü çağırır:


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 topic’i, uygulamanızın edge bileşeni tarafından kaydedilmiş olmalıdır. Dönüş değerleri, AI’nın yorumlayabileceği okunabilir metin veya yapılandırılmış veri olmalıdır.

Yetkilendirme Araçları

Bu araçlar, aynı dosyada tanımlanan başka bir ajana yetki devreder:


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

Parametre Türleri

Tür	Açıklama
`string`	Metin girdişi
`number`	Sayısal değer
`boolean`	Doğru/yanlış
`object`	Yapılandırılmış JSON nesnesi
`array`	Değer listesi

Alt Ajanlar & Yetkilendirme

Karmaşık alan adları için AI entegrasyonunuzu birden fazla uzmanlaşmış ajana bölün. Alt ajanlar odaklı görevleri üstlenirken ana ajan yönetimi üstlenir.

Ana ve Alt Ajanlar

Özellik	Ana Ajan (`main: true`)	Alt Ajan (`main: false`)
Görünürlük	IronFlock AI’ya kayıtlı	IronFlock AI’dan gizli
Erişim	IronFlock AI tarafından doğrudan çağırılır	Yalnızca başka bir ajandan yetkilendirme yoluyla erişilebilir
Kullanım senaryosu	Uygulamanızın AI’si için giriş noktası	Uzmanlaşmış alan uzmanlığı

Alt Ajan Ne Zaman Kullanılır

Alt ajan kullanın:

Tek bir ajan çok fazla araça sahip olduğunda (8–10’dan fazla)
Farklı görevler farklı system prompt’lar veya uzmanlık gerektirdiğinde
Karmaşık iş akışlarını izole etmek istediğinizde (örn. yapılandırma ile izleme)
Farklı görevler için farklı token limitleri veya yineleme sayılarına ihtiyaç duyduğunuzda

Yetkilendirme Akışı


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

Ana ajan, system prompt’una ve yetkilendirme aracının açıklamasına dayanarak ne zaman yetki devredeceğine karar verir. Alt ajan bağımsız çalışır, kendi araçlarını kullanır ve sonuçları kullanıcı için özetleyerek ana ajana geri iletir.

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.

tool_description’da dahili araçlara atıfta bulunmayın — IronFlock AI’nın bunları bilmesine gerek yoktur.

System Prompt Yazma

system_prompt, ajanınızın davranışını tanımlar. Şunları ekleyin:

Rol — Ajanın ne olduğu ve ne bildiği.
Kullanılabilir araçlar — Her aracı ve ne zaman kullanılacağını listeleyin.
Çıktı formatı — Yanıtların nasıl yapılandırılacağı.
Sınırlamalar — Ajanın YAPMAMASI gerekenler.


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 Araç Tasarımı

Okunabilir veri döndürün — AI ajanı, aracınızın dönüş değerlerini yorumlayacaktır. Ham ikili veri değil, yapılandırılmış metin veya JSON döndürün.
Hata mesajları ekleyin — Bir araç başarısız olduğunda, AI’nın kullanıcıya iletebileceği açıklayıcı bir hata mesajı döndürün.
Parametreleri basit tutun — Mümkün olduğunda ilkel türler (string, number, boolean) kullanın. Karmaşık iç içe nesneler, AI’nın doğru çağrılar oluşturmasını zorlaştırır.
Zorunlu parametreleri işaretleyin — Zorunlu girdiler için her zaman required: true ayarlayın.

Ajan Boyutlandırma

Ayar	Öneri
`max_context_tokens`	Çoğu ajan için 30.000 – 50.000
`messages_after_summary`	4 – 6 mesaj
`max_iterations`	5 – 10 (çok adımlı iş akışları için artırın)

Yüksek değerler daha karmaşık etkileşimlere olanak tanır ancak daha fazla token harcar. Muhafazakâr başlayın ve ajanlar limitlere ulaşırsa artırın.

Ajanları Test Etme

Uygulamanıza bir test cihazı ekleyin.
IronFlock AI sohbetini açın.
Ajanınızı tetiklemesi gereken sorular sorun.
AI’nın doğru şekilde yetki devredip devretmediğini ve araçlarınızın beklenen veriyi döndürüp döndürmediğini doğrulayın.
Hata durumlarını test edin — bir cihaz çevrimdışı olduğunda veya bir araç hata döndürdüğünde ne olur?

Tam Örnek


# 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