Multi-agent systemy AI w 2025: architektura, narzędzia, pułapki

Przez ostatnie dwa lata zbudowałem pięć systemów multi-agent dla różnych klientów — od lead generation platform po wewnętrzne narzędzia do analizy kodu. Każdy z nich wyglądał inaczej na diagramie, ale wzorce się powtarzały. Ten post jest o tych wzorcach.

Czym właściwie jest system multi-agent

Nie chodzi o pięć modeli LLM wołających się nawzajem bez końca. Chodzi o dekompozycję problemu na role:

• Planner — dostaje cel wysokopoziomowy, rozpisuje go na kroki
• Executor — wykonuje konkretne akcje (function calling, API, baza danych)
• Reviewer — krytykuje wynik Executora, każe poprawić lub akceptuje
• Researcher (opcjonalny) — dostarcza kontekst, dokumenty, snippet-y kodu

Dobrze zaprojektowany system multi-agent nie jest chatem. Ma stan, ma przepływ sterowania i ma sposób na zatrzymanie się, gdy zadanie jest zrobione lub gdy utknął w pętli.

Minimalna architektura działająca w produkcji

Najprostszy system, który da się utrzymywać w produkcji, to 2 agenty + pętla z limitem iteracji:

import openai
import json

MAX_ITERATIONS = 8

def run_agent_loop(task: str) -> str:
    state = {"task": task, "history": [], "iteration": 0}

    while state["iteration"] < MAX_ITERATIONS:
        state["iteration"] += 1

        # Planner: decyduje co dalej
        plan = call_planner(state)
        state["history"].append({"role": "planner", "content": plan})

        if plan["action"] == "DONE":
            return plan["final_answer"]

        if plan["action"] == "TOOL_CALL":
            # Executor: wykonuje konkretne wywołanie
            result = call_executor(plan["tool"], plan["args"])
            state["history"].append({"role": "executor", "content": result})

            # Reviewer: krytykuje
            critique = call_reviewer(state)
            state["history"].append({"role": "reviewer", "content": critique})

            if critique["approved"]:
                return critique["final_answer"]

    raise RuntimeError(f"Agent loop stuck after {MAX_ITERATIONS} iterations")

To jest szkielet — 30 linii, a obsługuje planowanie, wykonanie i walidację. Dodaj:

• persystencję (state do Redis/SQLite, nie do pamięci)
• observability (LangSmith albo własny logger z token counts)
• schema validation na każdym wyjściu (Pydantic / Zod)
• rate limiting (429 z OpenAI to nie wyjątek, to normalne)

I masz produkcyjny system.

Hermes-style orkiestracja: pattern, który sprawdza się w moich projektach

Wewnętrznie nazywam to Hermes-style od mojego głównego frameworka agentowego (Hermes Agent, na którym zresztą pracuję). Kluczowa idea: orkiestrator jest cienką warstwą nad deterministycznym kodem, nie nad kolejnym modelem LLM.

┌─────────────────────────────────────────────┐
│  Orchestrator (Python/TypeScript)           │
│  ───────────────────────────────            │
│  - wie co user chce                         │
│  - woła agentów w zadanej kolejności        │
│  - waliduje wyniki (Zod)                    │
│  - loguje wszystko                          │
└──────────┬──────────────────────────────────┘
           │
   ┌───────┼───────┐
   ▼       ▼       ▼
 Agent1  Agent2  Agent3
 (LLM)   (LLM)   (LLM)
   │       │       │
   ▼       ▼       ▼
 Tools   Tools   Tools

Orkiestrator nie jest LLM-em. To zwykły kod z if/else, pętlami, retry logic. Dopiero agenty wewnętrzne to LLM-y. To odwraca typowy błąd: ludzie robią orkiestratora w LLM-ie, a potem nie wiedzą dlaczego halucynuje na poziomie sterowania.

Narzędzia — kiedy co

| Framework | Kiedy używać | Kiedy NIE używać | |-----------|--------------|-------------------| | Własny kod (OpenAI function calling) | 1-3 agentów, prototyp, MVP | Powyżej 5 agentów, potrzebujesz grafu stanów | | LangGraph | 4+ agentów, złożony graf, persystencja | Prosty sekwencyjny pipeline — overengineering | | autogen (Microsoft) | Konwersacyjne agenty, research, eksploracja | Produkcja wymagająca niskiej latencji i niskich kosztów | | CrewAI | Role-based agenty (jak załoga), content creation | Kiedy potrzebujesz precyzyjnej kontroli przepływu | | LlamaIndex Agents | RAG-heavy workflow (agenty czytają dokumenty) | Głównie function calling, bez RAG |

Moja rekomendacja: zacznij od własnego kodu. Frameworki dają 30% oszczędności czasu na starcie, ale 200% więcej bólu przy debugowaniu produkcyjnym, gdy wersja LangChain się zmieni i wszystko się sypie.

Pięć pułapek, które widziałem u klientów

1. Brak limitu iteracji

Agent wchodzi w pętlę: Planner mówi "wykonaj X", Executor zwraca błąd, Planner mówi "spróbuj X ponownie", Executor zwraca ten sam błąd. Po 200 iteracjach masz $47 rachunek za OpenAI i timeout na Cloudflare. Zawsze ustawiaj MAX_ITERATIONS. Ja domyślnie 8.

2. Brak schema validation

Agent zwraca "wygląda dobrze" zamiast JSON-a. Parser rzuca wyjątek. Kod się sypie. Każdy output agenta musi być walidowany (Pydantic w Pythonie, Zod w TypeScript). Bez tego nie wiesz czy błąd jest w agencie, w prompcie, w parserze, czy w danych.

3. Za dużo agentów od początku

Klient chce "chatbota, który robi research, pisze raporty, zarządza kalendarzem i rezerwuje loty". To są cztery różne produkty, nie jeden. Zacznij od jednego agenta robiącego jedną rzecz dobrze. Dodawaj drugiego tylko gdy user naprawdę potrzebuje obu capabilities jednocześnie.

4. Brak obserwowalności

System multi-agent w produkcji bez logów to czarna skrzynka. Gdy user mówi "to nie zadziałało", nie masz pojęcia dlaczego. Minimum:

• Każde wywołanie LLM: timestamp, model, prompt, output, token count, latency
• Każda decyzja orkiestratora: dlaczego wywołał agenta X, a nie Y
• Każdy tool call: input, output, czas wykonania

Bez tego nie debugujesz, tylko zgadujesz.

5. Halucynacje kaskadujące

Agent A halucynuje, że user chce X. Agent B bierze to za pewnik. Agent C buduje na tym. Żaden z trzech nie wie, że A się mylił. Rozwiązanie: Reviewer agent (wzorzec above) albo grounding w danych — agent musi cytować źródło, inaczej jego odpowiedź jest odrzucana.

Kiedy multi-agent NIE ma sensu

Bądźmy szczerzy. W 60% przypadków, gdzie ludzie wdrażają multi-agent, wystarczyłby:

• Dobry prompt + jeden model GPT-4o
• Function calling do 3-4 narzędzi
• RAG z dobrym retrievalem

Multi-agent ma sens, gdy:

• Zadanie naturalnie dzieli się na role (research → plan → execute → review)
• Pojedynczy agent regularnie przekracza kontekst (długa historia rozmowy)
• Potrzebujesz różnych modeli do różnych zadań (np. GPT-4o do planowania, GPT-4o-mini do prostych klasyfikacji — oszczędność 80% kosztów)
• Masz wymaganie audytowalności (każdy krok ma swojego agenta = osobny log)

Jeśli żaden z tych punktów nie pasuje — nie buduj multi-agenta. Zostań przy jednym agencie z function calling. To jest mniej "impressive", ale 10x łatwiejsze w utrzymaniu.

Co dalej

W kolejnych postach rozwinę konkretne tematy:

• OpenAI API w praktyce: function calling, embeddings, RAG — kod produkcyjny, nie hello world
• GEO vs SEO — jak pisać content, żeby AI go cytowało
• Wyszukiwarki AI a Google — co zmieniło się w algorytmach w 2025

Jeśli budujesz system multi-agent i utknąłeś — napisz do mnie. Pomagam z architekturą, code review i debuggingiem produkcyjnym.