Główna przyczyna każdej awarii multi-agentowej
Zbudowałeś coś imponującego: pipeline multi-agentowy, który bada, analizuje, pisze i publikuje. Działa na testach. Pokazujesz to zespołowi. Wszyscy są pod wrażeniem. Potem wdrażasz to na produkcję i w ciągu 48 godzin robi coś, o co nikt nie prosił.
Twój agent analityczny pisze raporty. Twój agent piszący pobiera dane. Twój orkiestrator rozmawia bezpośrednio z użytkownikami. Wszystko jest technicznie funkcjonalne, a mimo to wszystko jest nie tak.
Główna przyczyna jest prawie zawsze ta sama: nikt nie powiedział agentom, kim są, co mogą robić, gdzie pasują ani jak powinny się zachowywać. Rozwiązaniem okazują się cztery proste pliki markdown, każdy odpowiadający na jedno konkretne pytanie.
Jeden duży prompt systemowy próbuje odpowiedzieć na cztery fundamentalnie różne pytania naraz. Rozwiązaniem jest dać każdemu pytaniu własny plik.
SKILL.md: Podręcznik szkoleń
Plik SKILL.md odpowiada na pytanie: "Jak właściwie to robię?"
Pomyśl o nim jak o dokumencie certyfikacyjnym. Jeśli zatrudniasz inżyniera danych, oczekujesz, że zna SQL. SKILL.md jest dowodem i punktem odniesienia dla tej wiedzy. Oto przykład dla agenta web scraping:
---
name: web-scraper
description: Ekstrahuje ustrukturyzowane dane ze stron internetowych
używając BeautifulSoup i Playwright.
---
## Kiedy używać tej umiejętności
- Użytkownik podaje URL i chce ustrukturyzowane dane
- Strona może być renderowana przez JS (użyj Playwright) lub statyczna
## Proces krok po kroku
1. Sprawdź, czy strona jest renderowana przez JS. Jeśli tak, użyj Playwright headless.
2. Preferuj semantyczne selektory: article, main, atrybuty role=.
Unikaj kruchych ścieżek CSS jak .div > span:nth-child(3).
3. Zwróć DataFrame pandas. Zapisz do /outputs/data.csv.
## Obsługa błędów
- 403 lub 429: Dodaj nagłówek User-Agent, poczekaj 2 sekundy, spróbuj ponownie.
- Puste wyniki: Zaloguj użyty selektor. Zaproponuj alternatywę.Najlepsze pliki SKILL.md nie opisują tylko scenariuszy bezbłędnych. Mówią agentowi dokładnie, co robić gdy coś pójdzie nie tak.
Najlepsza praktyka: jeden SKILL.md na capability. Nie łącz "scrapingu" i "zapytań do bazy danych" w jednym pliku. Utrzymuj umiejętności atomowe i wielokrotnego użytku.
Agent.md: Identyfikator pracownika
Agent.md odpowiada na pytanie: "Kim jestem i gdzie pasuję w systemie?"
To plik per-agent. Każdy agent ma dokładnie jeden. Jest krótki, rzadko więcej niż 30 linii, ponieważ nie próbuje niczego nauczyć agenta. Zakorzenía agenta w jego tożsamości:
## analyst-agent ### Kim jestem Jestem agentem analizy danych. Otrzymuję zbiory danych i pytania, i zwracam ustrukturyzowane słowniki AnalysisResult. ### Moje miejsce w systemie - Uruchamiany przez: orchestrator-agent - Przekazuję do: viz-agent i writer-agent - Nigdy nie komunikuję się bezpośrednio z użytkownikiem ### Czego NIE robię - Pisać raportów ani prozy (-> writer-agent) - Tworzyć wykresów ani wizualizacji (-> viz-agent) - Dawać rekomendacji biznesowych (-> przegląd ludzki)
Ta ostatnia sekcja, "Czego NIE robię", jest najważniejszą częścią każdego Agent.md. Złe zachowanie agenta prawie zawsze pochodzi z agenta wypełniającego lukę, która nigdy nie była wyraźnie zamknięta.
Najlepsza praktyka: utrzymuj Agent.md stabilny. Nie powinien prawie nigdy się zmieniać po napisaniu. Jeśli często go edytujesz, rola agenta nie jest jeszcze dobrze zdefiniowana.
AGENTS.md: Schemat organizacyjny
Jeśli Agent.md to identyfikator jednego pracownika, AGENTS.md to katalog firmowy. Odpowiada na pytanie: "Kim są wszyscy agenci i jak cały system jest połączony?"
To jeden plik w katalogu głównym projektu, nie w folderze żadnego konkretnego agenta. Daje każdemu agentowi model mentalny całego systemu, a nie tylko jego narożnika.
# Agenci systemowi ## orchestrator-agent Rola: Odbiera żądania użytkowników, kieruje zadania, agreguje wyniki Uruchamia: analyst-agent, writer-agent, viz-agent ## analyst-agent Rola: Odbiera zbiory danych, zwraca słowniki AnalysisResult Raportuje do: orchestrator-agent Przekazuje do: viz-agent, writer-agent ## writer-agent Rola: Przekształca analizę w ustrukturyzowane raporty prozą Raportuje do: orchestrator-agent Nigdy: dostęp do surowych danych, zewnętrzne wywołania API
Najlepsza praktyka: traktuj AGENTS.md jak diagram architektury. Utrzymuj go w katalogu głównym projektu, commituj do kontroli wersji i aktualizuj gdy dodajesz lub usuwasz agenta.
INSTRUCTIONS.md: Podręcznik pracownika
INSTRUCTIONS.md odpowiada na pytanie: "Jak powinienem się zachowywać krok po kroku podczas wykonywania pracy?"
To najbardziej operacyjny z czterech plików. Podczas gdy SKILL.md mówi "tak scrapujesz stronę," INSTRUCTIONS.md mówi "to jest dokładna sekwencja, którą wykonujesz za każdym razem gdy przychodzi zadanie":
## Instrukcje: Agent Analizy Danych ### Podstawowe zasady zachowania 1. Zawsze waliduj zbiór danych przed analizą. - Więcej niż 20% null w kolumnie? Ostrzeż użytkownika. - Niezgodności typów? Zgłoś błąd, nie zgaduj. 2. Nigdy nie wymyślaj statystyk. Jeśli obliczenie zwraca NaN lub błąd, powiedz to wprost. 3. Bądź zwięzły w podsumowaniach. Maksymalnie trzy zdania. ### Dokładny workflow 1. Załaduj zbiór danych. Zaloguj jego kształt i typy kolumn. 2. Przeprowadź kontrole jakości danych. 3. Odpowiedz na pytanie analityczne tylko kodem, nie zgaduj. 4. Wypełnij słownik AnalysisResult. 5. Natychmiast przekaż do downstream agenta. NIE pytaj użytkownika o potwierdzenie. ### Twarde ograniczenia - Nigdy nie czytaj plików poza /mnt/user-data/ - Nigdy nie wykonuj zewnętrznych wywołań HTTP
Ten eksplicytny numerowany workflow jest tym, co odróżnia dobre pliki INSTRUCTIONS.md od złych. Instrukcje prozą są interpretowane luźno. Numerowane kroki są wykonywane precyzyjnie.
Jak 4 pliki współpracują
Oto struktura folderów używana w każdym projekcie multi-agentowym:
repo/
├── AGENTS.md <- Mapa systemu. Kto istnieje. Jak są połączeni.
└── agents/
└── analyst/
├── Agent.md <- Jestem analyst-agent. Raportuję do orchestratora.
├── INSTRUCTIONS.md <- Krok 1: waliduj. Krok 2: oblicz. Nigdy nie wymyślaj.
└── skills/
└── SKILL.md <- Jak dokładnie przeprowadzić analizę pandas.Model mentalny: AGENTS.md to mapa miasta. Agent.md to adres twojego mieszkania. INSTRUCTIONS.md to twoja codzienna rutyna. SKILL.md to twój certyfikat zawodowy.
- AGENTS.md (mapa miasta): Bez tego agenci nie mają pojęcia, jak ich praca łączy się z resztą systemu.
- Agent.md (adres): Bez tego agenci dryfują w kierunku ról, które wydają się naturalne, ale nigdy nie były zamierzone.
- INSTRUCTIONS.md (rutyna): Bez tego agenci interpretują "wykonaj pracę" w niespójny, nieprzewidywalny sposób.
- SKILL.md (certyfikat): Bez tego agenci próbują capabilities bez żadnych wskazówek jak wykonać lub naprawić błędy.
Pliki, które zespoły pomijają
Większość zespołów pisze SKILL.md i INSTRUCTIONS.md dość naturalnie: wynikają z pracy nad prompt engineeringiem. Czego zespoły konsekwentnie pomijają to Agent.md i AGENTS.md, bo wydają się administracyjne.
"Wiemy kim są agenci" mówią zespoły. "Nie musimy tego dokumentować."
Ale agenci nie wiedzą tego co ty wiesz. Za każdym razem gdy zaczyna się nowa rozmowa, każdy agent zaczyna od nowa. Bez Agent.md twój agent analityczny nie wie, że jest analitykiem. Wie, że ma narzędzia pandas i jakieś instrukcje. Przy wystarczającej swobodzie, sam zdefiniuje swoją rolę.
- Dryf roli: Agenci stopniowo rozszerzają się na sąsiednie zadania, zacierając odpowiedzialności.
- Niezgodności formatu wyjściowego: Agent A produkuje coś, czego Agent B nie może przetworzyć.
- Awarie kaskadowe: Jeden agent robiący złą rzecz powoduje łańcuch błędów downstream.
- Koszty onboardingu: Każdy nowy inżynier musi odtworzyć cały system z promptów i logów.
Struktura czterech plików kosztuje około dwóch godzin do ustawienia dla nowego agenta. Błędy, które zapobiega, kosztują dni.
Podsumowanie
Systemy multi-agentowe nie zawodzą dlatego, że modele są złe, ale dlatego, że nikt nie dał agentom jasnej struktury organizacyjnej. Cztery pliki markdown rozwiązują to całkowicie: jeden dla mapy systemu, jeden dla tożsamości, jeden dla zachowania krok po kroku i jeden dla wielokrotnego użytku umiejętności.
Jeśli budujesz system z więcej niż dwoma agentami, dodaj te pliki zanim napiszesz jedną linię kodu agenta. Struktura, którą zdefiniujesz z góry, to struktura, w której twoi agenci będą działać.
Potrzebujesz ustrukturyzowanego systemu agentów AI dla swojej firmy?
TecAdRise buduje pipeline'y multi-agentowe z właściwą strukturą, jasnymi definicjami ról i architekturą gotową na produkcję.
Skontaktuj się
