Agenci i narzędzia AI

Agenci i narzędzia są definiowani w pliku .ironflock/ai-template.yml w repozytorium Twojej aplikacji.

Struktura agenta

Każdy klucz najwyższego poziomu definiuje agenta:


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

Pola agenta

Pole	Opis
`tool_description`	Instrukcje dla AI IronFlock określające, kiedy delegować do tego agenta. Nie odwołuj się tutaj do wewnętrznych narzędzi.
`system_prompt`	Definiuje rolę agenta, jego wiedzę, dostępne narzędzia i oczekiwany format odpowiedzi.
`main`	`true` = widoczny dla AI IronFlock. `false` = sub-agent, osiągalny wyłącznie przez delegowanie.
`data_access`	Opcjonalne. `true` daje temu agentowi dostęp SQL tylko do odczytu do tabel danych własnej aplikacji, przez wbudowane narzędzia `get_schema` i `execute_sql`. Nigdy do danych innej aplikacji.
`file_access`	Opcjonalne. `true` daje temu agentowi dostęp tylko do odczytu do plików zapisanych przez własną aplikację, przez wbudowane narzędzia `list_app_files` i `read_app_file`. Przeszukuje ścieżki plików, a nie ich zawartość, i nie odczytuje plików PDF ani innych formatów binarnych.
`log_access`	Opcjonalne. `true` daje temu agentowi dostęp tylko do odczytu do logów kontenerów własnej aplikacji, przez wbudowane narzędzie `get_app_logs`. Nigdy do logów innej aplikacji i tylko na urządzeniach, które użytkownik i tak może zobaczyć.
`web_search`	Opcjonalne. `true` daje temu agentowi wbudowane narzędzie `web_search`, które przeszukuje publiczny internet i zwraca podsumowaną odpowiedź z linkami do źródeł — do kart katalogowych, kodów błędów lub wszystkiego, na co dane Twojej aplikacji nie odpowiadają. Zapytanie trafia do zewnętrznego dostawcy wyszukiwania, więc określ w `system_prompt`, czego agent może szukać.
`max_context_tokens`	Limit tokenów na żądanie (~1,3 tokena na słowo).
`messages_after_summary`	Liczba ostatnich wiadomości zachowywanych bez podsumowania w historii rozmowy.
`max_iterations`	Maksymalna liczba rund wywołań narzędzi, zanim agent się zatrzyma. Zapobiega nieskończonym pętlom.
`effort`	Opcjonalne. Ile rozumowania model przeznacza na turę: `low`, `medium` lub `high` (domyślnie).

effort wymienia jakość odpowiedzi na szybkość i koszt. Niższe poziomy sprawiają, że każda runda wywołań narzędzi jest szybsza i tańsza; high jest tym, czego platforma używa przy pominiętym polu. Wybieraj poziom na podstawie pomiaru, a nie domysłu: uruchom typowe zadania swojego agenta na każdym poziomie i zostaw najniższy, który wciąż wykonuje każde zadanie poprawnie.

Typy narzędzi

Narzędzia oparte na tematach WAMP

Te narzędzia wywołują procedurę WAMP zarejestrowaną przez kod brzegowy:


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

Temat WAMP musi być zarejestrowany przez komponent brzegowy Twojej aplikacji. Wartości zwracane powinny być czytelnym tekstem lub danymi strukturalnymi, które AI potrafi zinterpretować.

Narzędzia delegujące

Te narzędzia delegują do innego agenta zdefiniowanego w tym samym pliku:


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

Typy parametrów

Typ	Opis
`string`	Tekst
`number`	Wartość liczbowa
`boolean`	Prawda/fałsz
`object`	Strukturalny obiekt JSON
`array`	Lista wartości

Sub-agenci i delegowanie

W złożonych domenach podziel integrację AI na kilku wyspecjalizowanych agentów. Sub-agenci zajmują się wąskimi zadaniami, a agent główny nimi zarządza.

Agent główny a sub-agent

Właściwość	Agent główny (`main: true`)	Sub-agent (`main: false`)
Widoczność	Zarejestrowany w AI IronFlock	Ukryty przed AI IronFlock
Dostęp	Wywoływany bezpośrednio przez AI IronFlock	Osiągalny tylko przez delegowanie od innego agenta
Zastosowanie	Punkt wejścia dla AI Twojej aplikacji	Wyspecjalizowana wiedza dziedzinowa

Kiedy używać sub-agentów

Używaj sub-agentów, gdy:

Pojedynczy agent miałby zbyt wiele narzędzi (więcej niż 8–10)
Różne zadania wymagają różnych promptów systemowych lub wiedzy
Chcesz odizolować złożone przepływy pracy (np. konfigurację od monitorowania)
Potrzebujesz różnych limitów tokenów lub liczby iteracji dla różnych zadań

Przepływ delegowania


Użytkownik → AI IronFlock → Agent główny → Sub-agent → Narzędzie WAMP → Urządzenie brzegowe
                                          ↓
                                  Wynik wraca z powrotem

Agent główny decyduje, kiedy delegować, na podstawie swojego promptu systemowego i opisu narzędzia delegującego. Sub-agent działa niezależnie, korzysta z własnych narzędzi i zwraca wyniki agentowi głównemu, który podsumowuje je dla użytkownika.

Najlepsze praktyki

Pisanie opisów narzędzi

Pole tool_description jest przeznaczone dla AI IronFlock — to ono decyduje, kiedy Twój agent zostanie wywołany. Pisz je z perspektywy AI IronFlock:

Dobrze:


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.

Źle:


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

Nie odwołuj się do wewnętrznych narzędzi w tool_description — AI IronFlock nie musi o nich wiedzieć.

Pisanie promptów systemowych

system_prompt definiuje zachowanie Twojego agenta. Uwzględnij:

Rolę — czym agent jest i co wie.
Dostępne narzędzia — wymień każde narzędzie i kiedy go używać.
Format odpowiedzi — jak odpowiedzi powinny być ustrukturyzowane.
Ograniczenia — czego agent NIE powinien robić.


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.

Projektowanie narzędzi WAMP

Zwracaj czytelne dane — agent AI będzie interpretował wartości zwracane przez Twoje narzędzie. Zwracaj ustrukturyzowany tekst lub JSON, nie surowe dane binarne.
Dołączaj komunikaty o błędach — gdy narzędzie zawiedzie, zwróć opisowy komunikat, który AI może przekazać użytkownikowi.
Utrzymuj proste parametry — używaj typów prostych (string, number, boolean), gdy to możliwe. Złożone zagnieżdżone obiekty utrudniają AI konstruowanie poprawnych wywołań.
Oznaczaj parametry wymagane — zawsze ustawiaj required: true dla obowiązkowych danych wejściowych.

Dobór rozmiaru agenta

Ustawienie	Zalecenie
`max_context_tokens`	30 000 – 50 000 dla większości agentów
`messages_after_summary`	4 – 6 wiadomości
`max_iterations`	5 – 10 (zwiększ dla wieloetapowych przepływów pracy)

Wyższe wartości pozwalają na bardziej złożone interakcje, ale kosztują więcej tokenów. Zacznij zachowawczo i zwiększaj, jeśli agenci osiągają limity.

Testowanie agentów

Dodaj urządzenie testowe do swojej aplikacji.
Otwórz czat AI IronFlock.
Zadaj pytania, które powinny uruchomić Twojego agenta.
Sprawdź, czy AI poprawnie deleguje i czy Twoje narzędzia zwracają oczekiwane dane.
Przetestuj przypadki błędów — co się dzieje, gdy urządzenie jest offline lub narzędzie zwraca błąd?

Kompletny przykład


# 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