[Intum Pomoc](https://intum.pl/pomoc.md) / [API](https://intum.pl/pomoc/noe/api.md)

# [Flota agentów](https://intum.pl/pomoc/noe/api/flota-agentow.md)

Panel `/noe/agent_fleet` zarządza agentami AI (np. Claude Code na różnych komputerach), które co
przebieg czytają **runbook** - instrukcję złożoną ze stron Markdown + Liquid, zaczynając od `main`.
Przypisanie łączy runbook z agentem (N:M) i nadaje rolę `worker` albo `lead`. Pauzę i stop da się
ustawić na flocie, runbooku, agencie i przypisaniu - obowiązuje najbardziej restrykcyjny.

**Autoryzacja:** `Authorization: Bearer TOKEN` (uprawnienie `noe/agent_fleet`)
**Content-Type:** `application/json; charset=utf-8`

## Jak zmieniać runbook

Agent co przebieg czyta stronę `main`, a pozostałe strony tylko wtedy, gdy pasuje ich opis „kiedy
czytać” (`when_to_read`). Do `main` system dokleja protokół floty (raporty, claimy, werdykty).
Id runbooka, strony albo agenta jest w adresie strony, na której jest użytkownik.

1. Pobierz runbook i jego strony: `GET /noe/agent_fleet/runbooks/:id.json` i `GET /noe/agent_fleet/runbooks/:id/pages.json`.
2. Zmieniaj strony przez `PATCH /noe/agent_fleet/runbooks/:id/pages/:page_id.json`, nowe przez
   `POST .../pages.json`. Każdy zapis tworzy wersję strony - poprzednią da się przywrócić w panelu.
3. Po zmianie sprawdź podgląd: `GET /noe/agent_fleet/runbooks/:id/preview.json?page_code=main&role=worker` -
   pole `warnings` musi być puste (błąd Liquid, link do nieistniejącej strony, strona niewidoczna dla roli).

Zasady:
- Zmieniaj tylko to, o co prosi użytkownik - reszta treści strony zostaje słowo w słowo.
- Strona `main` ma być krótka: cel, kolejne kroki i odnośniki `{{ page_urls.<kod> }}` do stron
  z detalami. Agent czyta ją przy każdym przebiegu - każde zdanie kosztuje tokeny.
- Nie wpisuj w treść tokenów, haseł ani kluczy - adres podstawia system (`{{ host }}`).
- Nie zmieniaj stanu całej floty (pauza / stop) bez wyraźnej prośby.
- Gdy strony każą agentowi wołać API innych modułów (zadania, alarmy, czat), sprawdź, czy
  `agent_privileges` runbooka ma potrzebne uprawnienia (`tasks`, `chat`, alarmy: `automation_incidents`,
  zmiany reguł SLA: `automation/escalation`, ...). Brakujące zaproponuj użytkownikowi, nie dopisuj bez
  pytania - to dostęp agenta do danych konta.

## API Endpoints

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| PATCH | `/noe/agent_fleet/status.json` | Stan całej floty: `status` = `active` / `paused` / `stopped` |
| GET | `/noe/agent_fleet/runbooks.json` | Lista runbooków |
| GET | `/noe/agent_fleet/runbooks/:id.json` | Runbook |
| POST | `/noe/agent_fleet/runbooks.json` | Nowy runbook (od razu ze stroną `main`) |
| PATCH | `/noe/agent_fleet/runbooks/:id.json` | Zmiana runbooka |
| DELETE | `/noe/agent_fleet/runbooks/:id.json` | Usunięcie runbooka |
| GET | `/noe/agent_fleet/library.json?kind=system\|account&q=` | Biblioteka szablonów: systemowe i runbooki konta udostępnione jako szablon |
| GET | `/noe/agent_fleet/library/:key.json` | Szablon z ustawieniami i stronami (`key` = kod systemowy albo `runbook-<id>`) |
| GET | `/noe/agent_fleet/library/:key.md?page_code=main` | Surowy markdown jednej strony szablonu |
| GET | `/noe/agent_fleet/runbooks/:id/template_changes.json` | Zmiany szablonu, z którego powstał runbook (per strona: `status`, `safe`) |
| POST | `/noe/agent_fleet/runbooks/:id/apply_template_changes.json` | Wprowadza zmiany bezpieczne (strony niezmieniane w runbooku) |
| POST | `/noe/agent_fleet/runbooks/:id/resolve_template_change.json` | Konflikt strony: `page_code`, `choice` = `theirs` (wersja szablonu) / `mine` (zostaw) |
| POST | `/noe/agent_fleet/runbooks/:id/wake.json` | Przebieg przy najbliższym checkinie (`role` opcjonalnie) |
| GET | `/noe/agent_fleet/runbooks/:id/preview.json?page_code=main&role=worker` | Strona tak, jak zobaczy ją agent, z listą `warnings` |
| GET | `/noe/agent_fleet/runbooks/:id/preview.md?page_code=main&role=worker` | To samo jako surowy markdown (`text/markdown`), bez `warnings` |
| GET | `/noe/agent_fleet/runbooks/:id/pages/:page_id/revisions.json` | Historia wersji strony |
| GET | `/noe/agent_fleet/runbooks/:id/pages/:page_id/revisions/:revision_id.md` | Treść jednej wersji jako surowy markdown |
| GET | `/noe/agent_fleet/runbooks/:id/pages.json` | Strony runbooka |
| GET | `/noe/agent_fleet/runbooks/:id/pages/:page_id.json` | Strona |
| POST | `/noe/agent_fleet/runbooks/:id/pages.json` | Nowa strona |
| PATCH | `/noe/agent_fleet/runbooks/:id/pages/:page_id.json` | Zmiana strony (zapisuje wersję) |
| DELETE | `/noe/agent_fleet/runbooks/:id/pages/:page_id.json` | Usunięcie strony (nie dotyczy `main`) |
| GET | `/noe/agent_fleet/agents.json` | Agenci |
| GET | `/noe/agent_fleet/agents/:id.json` | Agent |
| PATCH | `/noe/agent_fleet/agents/:id.json` | Zmiana nazwy / stanu agenta |
| GET | `/noe/agent_fleet/assignments.json?runbook_id=&agent_id=` | Przypisania |
| POST | `/noe/agent_fleet/assignments.json` | Nowe przypisanie |
| PATCH | `/noe/agent_fleet/assignments/:id.json` | Zmiana roli / stanu / interwału / priorytetu |
| DELETE | `/noe/agent_fleet/assignments/:id.json` | Usunięcie przypisania |
| GET | `/noe/agent_fleet/runs.json` | Przebiegi agentów |
| GET | `/noe/agent_fleet/runs/:id.json` | Przebieg ze zdarzeniami |
| GET | `/noe/agent_fleet/work_items.json` | Sprawy oceniane przez kilku agentów (głosowanie) |
| POST | `/noe/agent_fleet/work_items/:id/reopen.json` | Ponowne otwarcie rozstrzygniętej sprawy |
| GET | `/noe/agent_fleet/prompts.json` | Prompty floty (`protocol`, `start_loop`) |
| GET | `/noe/agent_fleet/prompts/:code/edit.md` | Bieżąca treść promptu jako markdown (`?version=default` - domyślna z Intum) |
| PATCH | `/noe/agent_fleet/prompts/:code.json` | Nadpisanie promptu (`prompt[content]`, pusta = domyślna) |

Zakładania agentów i obracania tokenów nie rób przez API - klucz startowy tokenu (ważny 10 minut)
pokazuje się tylko raz, w panelu, administratorowi. Token agenta jest w sejfie tokenów: agent pracuje
na krótkich JWT i sam je odświeża; rejestr wydań i blokada są na stronie tokenu w `/account/api_tokens`.

Każda zmiana runbooka, strony, agenta, przypisania, promptu i stanu floty (także przez API)
zapisuje się w aktywnościach konta: kto, kiedy i które pola zmienił (treść strony nie - jej
wersje są w historii strony). Historia: `GET /account/activities.json?module=noe`, dla obiektu
`?agent_fleet_runbook_id=ID` albo `?agent_fleet_agent_id=ID`. Tokenów tam nie ma.

## Runbook (`runbook[...]`)

| Pole | Opis |
|------|------|
| `name` | Nazwa |
| `code` | Kod w adresie stron dla agenta (`/noe/agent_fleet/r/<code>/main.md`), małe litery, cyfry, `-` i `_` |
| `description` | Opis dla ludzi |
| `status` | `active` / `paused` / `stopped` |
| `interval_minutes` | Co ile minut przebieg (1-1440) |
| `run_as_user_id` | Użytkownik, w imieniu którego agent działa w API (puste = właściciel agenta) |
| `claim_mode` | `single` (sprawę bierze jeden agent) albo `quorum` (ocenia kilku) |
| `claim_quorum` | Ilu agentów ocenia sprawę w trybie `quorum` (1-10) |
| `claim_ttl_minutes` | Po ilu minutach niezamknięty claim wygasa |
| `decision_by` | `verdict` (średnia ocen) albo `lead` (decyduje lider) |
| `enroll_enabled` | Agenci mogą dołączać sami komendą z tokenem dołączenia |
| `shared_as_template` | Runbook widoczny w bibliotece jako szablon dla innych w koncie (domyślnie `true`) |
| `agent_privileges` | Tablica uprawnień Intum dla tokenów agentów runbooka (`runbook[agent_privileges][]=tasks`), np. `tasks`, `users`, `automation`, `automation_incidents` (obsługa alarmów), `chat`. Pusta = tylko API floty. Agent przypisany do kilku runbooków dostaje sumę, nigdy więcej niż ma jego user. Można dodać tylko uprawnienie, które ma zapisujący (inaczej 422). Zmiana działa od razu, bez nowego tokena |

Runbook z szablonu: parametr `template` obok `runbook[...]` w `POST /noe/agent_fleet/runbooks.json` dodaje
strony szablonu (ustawienia `claim_mode`, `interval_minutes`, `agent_privileges` itd. podaj sam
w `runbook[...]` - podpowiada je `settings` z `GET /noe/agent_fleet/library/<kod>.json`). Kody:

| `template` | Do czego |
|------------|----------|
| `task_executor` | Gotowy: agent bierze zadania Organize w ustalonej kolejności, wykonuje i przekazuje osobie (`comment_and_assign`) |
| `task_handoff` | Gotowy, 2 agentów (`decision_by: lead`): lider zleca zadanie z instrukcją, wykonawca realizuje, lider oddaje wynik |
| `inalarm_handler` | Gotowy: obsługa alarmów inAlarm - sprawdzenie, informacja na czat, niegroźny alarm `acknowledge` (stop eskalacji), post mortem w wątku |
| `secret_number` | Gra do wypróbowania floty (`decision_by: lead`, `quorum` 2): lider koduje liczbę 1-100 w zadaniach ze słowem „zgadywanka” w tytule, dwóch wykonawców zgaduje, lider ujawnia liczbę i zamyka zadanie. Potrzebuje 1 agenta z rolą lider i 2 wykonawców |
| `single`, `queue`, `voting`, `lead_workers`, `inalert` | Szkielety do wypełnienia: jeden agent, kolejka, głosowanie (`quorum`), lider i wykonawcy, ocena alarmów przez 3 agentów |

Zamiast kodu systemowego `template` może być `runbook-<id>` - kopia stron runbooka z konta
udostępnionego jako szablon (lista: `GET /noe/agent_fleet/library.json`). Runbook pamięta źródło
(`source_template` / `source_runbook_id`). Gdy źródło się zmieni, nic nie zmienia się samo:
sprawdź `template_changes.json`, zmiany `safe: true` wprowadź `apply_template_changes`, a przy
`status: conflict` zapytaj użytkownika, którą wersję zostawić (`resolve_template_change`).
Synchronizowane są tylko strony, nie ustawienia.

W gotowych szablonach strona `config` (albo `notify` przy alarmach) ma miejsca `...` do uzupełnienia:
źródło zadań, kolejność, limit, user_id odbiorcy, id pokoju czatu.

## Strona (`runbook_page[...]`)

| Pole | Opis |
|------|------|
| `code` | Kod strony (`main` jest stała) |
| `title` | Tytuł |
| `when_to_read` | Kiedy agent ma czytać stronę - jedno zdanie, trafia do spisu stron w `main` |
| `audience` | `all`, `worker` albo `lead` - kto widzi stronę |
| `content` | Treść Markdown + Liquid (przy `kind` = `file`: treść pliku, bez Liquid) |
| `position` | Kolejność w spisie |
| `kind` | `prompt` (domyślnie, instrukcja dla agenta) albo `file` - plik na dysk agenta (skrypt, konfiguracja) |
| `file_name` | Przy `kind` = `file`: nazwa pliku (`A-Za-z0-9._-`, bez katalogów), unikalna w runbooku |

Zmienne Liquid w treści: `host`, `api_token`, `agent_name`, `agent_role`, `runbook_code`,
`runbook_name`, `runbook_version`, `run_id`, `claim_mode`, `claim_quorum`, `claim_ttl_minutes`,
`decision_by`, `page_urls.<kod>` (adres innej strony), `file_urls.<nazwa pliku>`, `files_url`
(manifest plików), `files_dir` (katalog plików u agenta), `install_url` (instalator runnera).

Pliki (`kind` = `file`) agent instaluje komendą `intum-fleet files <kod runbooka>` - runner sprawdza
sumy sha256 i każdą zmianę pokazuje człowiekowi do akceptacji. Kod strony `files` jest zarezerwowany.

`api_token` to bieżące krótkie JWT agenta - trafia wtedy do kontekstu modelu. W przykładach curl
lepiej pisać „z nagłówkiem autoryzacji z protokołu” (`-H @<plik z nagłówkiem>`), bez tej zmiennej.

## Przypisanie (`assignment[...]`)

| Pole | Opis |
|------|------|
| `runbook_id`, `agent_id` | Tylko przy tworzeniu |
| `role` | `worker` albo `lead` (lider grupy: rozstrzyga, gdy `decision_by` = `lead`) |
| `status` | `active` / `paused` |
| `interval_minutes` | Własny interwał (puste = z runbooka) |
| `priority` | Kolejność, gdy agent ma kilka runbooków (większy = ważniejszy) |