CrewAI, zespoly agentow i przeplywy zdarzen

CrewAI, zespoły agentów z podziałem ról

CrewAI opisuje pracę agentów tak, jak opisuje się zespół ludzi: każdy dostaje rolę, cel i zestaw narzędzi, a zadania rozdziela się między nich. To pythonowy framework na licencji MIT, stworzony w 2023 roku, z osobną platformą komercyjną do wdrożeń.

Dwa modele pracy, które trzeba rozróżnić

Framework daje dwa mechanizmy i wybór między nimi decyduje o tym, czy projekt będzie działał przewidywalnie.

Crews to zespoły agentów pracujących wspólnie nad zadaniem. Definiujesz role, cele i narzędzia, a podział pracy wynika z opisu ról. Sprawdza się tam, gdzie sposób dojścia do wyniku nie jest z góry znany, na przykład przy analizie tematu z wielu stron.

Flows to przepływy sterowane zdarzeniami, z jawnym stanem i kolejnością kroków. Ty decydujesz, co uruchamia co i jak dane przechodzą między etapami. Sprawdza się w procesach, których przebieg jest ustalony i musi być powtarzalny.

Framework powstał w 2023 roku i rozwinął się w projekt o dużej społeczności, z osobną platformą do wdrożeń używaną w firmach. Ma to znaczenie praktyczne przy wyborze: dokumentacji i przykładów jest sporo, a większość problemów, na które natrafisz, ktoś już opisał. Cena tego rozwoju to zmieniające się API między wersjami, więc przypnij wersję w pliku zależności zamiast instalować najnowszą przy każdym budowaniu.

Najczęstszy błąd początkujących polega na budowaniu zespołu agentów tam, gdzie wystarczy przepływ. Zespół kosztuje więcej, bo każdy agent to osobne wywołania modelu, i jest trudniejszy do zdiagnozowania, bo nie wiadomo, który podjął złą decyzję. Zacznij od przepływu i sięgnij po zespół, gdy kolejność kroków naprawdę zależy od danych.

Pierwszy zespół

pip install crewai crewai-tools
export OPENAI_API_KEY=...

from crewai import Agent, Task, Crew, Process

analityk = Agent(
    role="Analityk rynku",
    goal="Zebrac fakty o konkurencji w segmencie narzedzi do fakturowania",
    backstory="Pracujesz z danymi publicznymi i cytujesz zrodla przy kazdej liczbie.",
    verbose=True,
)

redaktor = Agent(
    role="Redaktor",
    goal="Napisac zwiezle podsumowanie dla zarzadu",
    backstory="Piszesz krotko, bez zargonu, zawsze zaczynasz od wniosku.",
)

zbieranie = Task(
    description="Znajdz piec konkurentow i opisz ich model cenowy.",
    expected_output="Lista pieciu firm z cenami i zrodlem dla kazdej.",
    agent=analityk,
)

podsumowanie = Task(
    description="Na podstawie zebranych danych napisz notatke na jedna strone.",
    expected_output="Notatka z wnioskiem w pierwszym akapicie.",
    agent=redaktor,
)

zespol = Crew(
    agents=[analityk, redaktor],
    tasks=[zbieranie, podsumowanie],
    process=Process.sequential,
)

print(zespol.kickoff())

Pole expected_output bywa pomijane, a jest najważniejsze w całej definicji. Bez niego agent sam ustala, co znaczy wykonane zadanie, i wyniki rozjeżdżają się między przebiegami. Opisz format wyjścia tak dokładnie, jak opisałbyś go człowiekowi, który robi to zadanie pierwszy raz.

Tryby pracy zespołu

Proces sekwencyjny wykonuje zadania po kolei, przekazując wynik jednego jako kontekst kolejnego. Jest przewidywalny i tani, bo liczba wywołań modelu odpowiada liczbie zadań.

Proces hierarchiczny dokłada agenta kierującego, który rozdziela zadania i weryfikuje wyniki. Daje lepsze efekty przy zadaniach niejednoznacznych, ale każde przekierowanie to dodatkowe wywołanie modelu, więc rachunek rośnie szybciej, niż wynikałoby z liczby agentów.

zespol = Crew(
    agents=[analityk, redaktor],
    tasks=[zbieranie, podsumowanie],
    process=Process.hierarchical,
    manager_llm="gpt-5",
)

Praktyczna wskazówka: model kierujący może być inny niż wykonawczy. Kierowanie wymaga rozumowania, wykonanie często nie, więc mocniejszy model na górze i tańszy w zadaniach potrafi obniżyć koszt o połowę bez straty jakości.

Narzędzia i pamięć

Agent bez narzędzi potrafi tylko generować tekst. Narzędzia dają mu dostęp do wyszukiwania, plików, baz i własnych funkcji.

from crewai.tools import tool

@tool("Sprawdz stan magazynowy")
def stan_magazynowy(sku: str) -> str:
    """Zwraca liczbe sztuk dostepnych dla podanego SKU."""
    return magazyn.pobierz(sku)

analityk = Agent(role="...", goal="...", backstory="...", tools=[stan_magazynowy])

Opis narzędzia decyduje o tym, czy agent po nie sięgnie. Zdanie mówiące wprost, kiedy je wywołać, działa lepiej niż samo stwierdzenie, co ono robi.

Warto ograniczać zestaw narzędzi na agenta do tych, których faktycznie potrzebuje w swojej roli. Dziesięć narzędzi w jednym agencie oznacza dłuższy prompt przy każdym wywołaniu i częstsze pomyłki w wyborze, a rozdzielenie ich między dwie role zwykle poprawia wynik przy niższym koszcie.

Pamięć włącza się jednym parametrem, memory=True w definicji zespołu, ale jej budowa zmieniła się w linii 1.x. Dawne trzy osobne warstwy, krótkoterminowa, długoterminowa i pamięć bytów, zniknęły. Zastąpiła je jedna klasa Memory z zakresami układanymi w drzewo w rodzaju /projekt/alfa, przy czym model sam ustala zakres i wagę zapisywanego faktu, a wyszukiwanie łączy podobieństwo semantyczne, świeżość i ważność. Warto ją włączyć świadomie, bo zapis trwa między przebiegami i wraca pytanie o to, gdzie te dane leżą, a bez własnego modelu osadzeń pamięć sięga po text-embedding-3-large od OpenAI.

Ta domyślna zależność ma znaczenie dokładnie wtedy, gdy pytanie o miejsce składowania jest realne, bo każdy zapamiętywany fakt jedzie po wektor do zewnętrznego dostawcy. Alternatywą uruchamianą u siebie są osadzenia BGE, wydane na licencji pozwalającej na użycie komercyjne i pozbawione kosztu za token. Płacisz za to hostowaniem modelu i jedną pułapką przy przesiadce: wymiar wektora różni się od domyślnego, więc istniejący magazyn trzeba przeliczyć od nowa, a nie dopisać do niego nowe wpisy.

Flows, czyli kiedy potrzebna jest kolejność

Przepływy rozwiązują problem, którego zespół agentów nie rozwiązuje: powtarzalność. Krok uruchamia się w reakcji na zdarzenie, stan przechodzi jawnie między etapami, a Ty wiesz, co się wykona i w jakiej kolejności.

from crewai.flow.flow import Flow, start, listen

class ObslugaZgloszenia(Flow):
    @start()
    def sklasyfikuj(self):
        return {"kategoria": klasyfikator.uruchom(self.state.tresc)}

    @listen(sklasyfikuj)
    def przekaz(self, wynik):
        if wynik["kategoria"] == "reklamacja":
            return zespol_reklamacji.kickoff(inputs=wynik)
        return odpowiedz_automatyczna(wynik)

Ten układ pozwala mieszać oba podejścia. Przepływ odpowiada za sterowanie i decyduje, co się dzieje, a zespół agentów wykonuje ten fragment, w którym droga do wyniku nie jest z góry znana. To zwykle najlepszy kompromis między przewidywalnością a elastycznością.

Stan przepływu warto trzymać jawnie, w jednym obiekcie, zamiast rozsypywać go po zmiennych. Przy diagnozowaniu błędu odpowiedź na pytanie „z jakimi danymi wszedł ten krok" powinna zajmować sekundy, nie pół godziny czytania logów.

Przy dłuższych procesach dokładaj obsługę błędów na poziomie kroku. Wywołanie zewnętrznego API, które raz na sto razy zwróci błąd, bez obsługi zatrzyma cały przepływ i zostawi zadanie w stanie nieokreślonym.

Cennik

Framework jest darmowy na licencji MIT i uruchomisz go na własnym serwerze bez ograniczeń. Płatna jest platforma do wdrażania i monitorowania agentów.

Warto rozumieć, za co dokładnie liczone są uruchomienia na platformie. Jedno uruchomienie to jeden przebieg procesu, niezależnie od tego, ilu agentów w nim uczestniczy. Cennik ma dwa poziomy i nic pomiędzy: plan Basic z pięćdziesięcioma uruchomieniami miesięcznie oraz Enterprise wyceniany indywidualnie. Pośredniego planu z abonamentem miesięcznym w cenniku nie ma, więc pierwszym progiem po wyczerpaniu darmowego limitu jest rozmowa handlowa. Ważniejsze jest to, co dzieje się po przekroczeniu limitu: na planie Basic pięćdziesiąt uruchomień jest zarazem sufitem twardym, bo doładowań na tym poziomie nie kupisz, a liczba automatyzacji jest ograniczona do dwóch. Dopiero Enterprise dostaje pulę dobieraną pod konkretny proces i doładowanie ponad nią. Przy automatyzacji reagującej na każde zgłoszenie klienta sensowniej postawić framework na własnej infrastrukturze, gdzie limitu nie ma, i zbudować monitoring po swojej stronie.

Rachunek za tokeny jest osobny i to on zwykle dominuje. Zespół czterech agentów z pamięcią potrafi wykonać kilkanaście wywołań modelu na jedno zadanie, więc koszt jednego przebiegu policz przed uruchomieniem procesu na stałe. Przy dużym wolumenie różnica między modelem droższym a tańszym w rolach pomocniczych liczy się w setkach dolarów miesięcznie.

Jak pisać role, żeby agent robił to, co trzeba

Opis roli jest w tym frameworku odpowiednikiem promptu systemowego i to on decyduje o jakości wyniku bardziej niż wybór modelu. Trzy elementy dają największą różnicę.

Zakres kompetencji, czyli czym agent się zajmuje i czym nie. Zdanie „zajmujesz się wyłącznie danymi finansowymi, pytania o marketing przekazujesz dalej" zapobiega sytuacji, w której agent odpowiada na wszystko po trochu.

Sposób pracy, czyli jak ma dochodzić do wyniku. „Przy każdej liczbie podajesz źródło" albo „zanim odpowiesz, sprawdzasz aktualność danych" zmienia zachowanie mocniej niż dopisanie kolejnego przymiotnika do opisu roli.

Ograniczenia wypisane wprost. Modele lepiej reagują na jasne granice niż na ogólne zachęty do ostrożności. „Nie zgadujesz cen, gdy nie znajdziesz źródła, tylko piszesz, że brak danych" działa, „bądź dokładny" nie.

analityk = Agent(
    role="Analityk cen",
    goal="Ustalic aktualne ceny konkurencji z podaniem zrodla",
    backstory=(
        "Pracujesz wylacznie na danych publicznych. Przy kazdej cenie podajesz adres strony "
        "i date sprawdzenia. Gdy nie znajdziesz ceny, piszesz 'brak danych' zamiast szacowac. "
        "Nie komentujesz strategii ani jakosci produktow."
    ),
    max_iter=8,
)

Parametr ograniczający liczbę obrotów wart jest ustawienia od początku. Bez niego agent, który nie potrafi domknąć zadania, będzie próbował aż do wyczerpania limitu domyślnego, a każda próba kosztuje.

Opisy zadań traktuj tak samo poważnie jak opisy ról. Zadanie sformułowane jako „przeanalizuj rynek" da wynik przypadkowy, bo nie wiadomo, kiedy jest skończone. Zadanie z wypisanym formatem wyjścia i liczbą pozycji daje wynik powtarzalny.

CrewAI kontra alternatywy

Te narzędzia da się też łączyć. Przepływ w n8n może wywołać zespół agentów przez własne API, a graf w LangGraph obsłużyć fragment wymagający zatrzymania na akceptacji.

Wybór zależy od tego, czy proces daje się opisać jako zespół z rolami, czy jako graf z warunkami. Przy pierwszym CrewAI dowozi wynik szybciej, przy drugim graf jest czytelniejszy i łatwiejszy do przetestowania.

Warto znać jeszcze dwa punkty odniesienia z tej samej rodziny. Agno stawia na lekkość i szybkość tworzenia agenta, więc bywa lepszy tam, gdzie zespół ról jest przerostem formy nad treścią. CAMEL wyrósł z badań nad rozmową agentów między sobą i przydaje się, gdy interesuje Cię symulacja albo generowanie danych, a nie dowiezienie zadania produkcyjnego.

Jak sprawdzić, czy to działa

System agentowy bez pomiaru wygląda dobrze na demie i zawodzi na prawdziwych danych. Ocena rozpada się na trzy pytania i każde mierzy się inaczej.

Czy wynik ma właściwy format. To najtańszy pomiar i najczęściej pomijany. Zbiór dwudziestu przebiegów i sprawdzenie, w ilu wynik da się sparsować albo przekazać dalej bez ręcznej poprawki, wyłapuje większość problemów z opisem zadania.

Czy wynik jest poprawny merytorycznie. Tu potrzebny jest zestaw przypadków z oczekiwaną odpowiedzią, przygotowany raz i uruchamiany po każdej zmianie roli, zadania albo modelu. Nie musi być duży, trzydzieści przypadków wystarcza, żeby zauważyć regresję.

Ile to kosztowało. Zsumuj wywołania modelu i tokeny na jeden przebieg, a potem pomnóż przez spodziewany wolumen. Ta liczba bywa najbardziej zaskakująca, bo zespół agentów zużywa wielokrotnie więcej niż pojedyncze wywołanie, a różnicy nie widać, dopóki proces działa na dziesięciu przypadkach.

Warto włączyć szczegółowe logowanie na etapie strojenia i wyłączyć je na produkcji. Zapis przebiegu z treścią promptów pokazuje, w którym miejscu agent zszedł z drogi, co przy dwóch współpracujących rolach bywa nieoczywiste. Na produkcji ten sam zapis to koszt miejsca i ryzyko, że w logach wylądują dane, których nie chcesz tam mieć.

Typowe błędy

Pierwszy to zbyt wielu agentów. Pięć ról w pierwszym projekcie prawie zawsze oznacza system, w którym nikt nie potrafi wskazać, który agent podjął złą decyzję. Zacznij od jednego, dołóż drugiego, gdy pierwszy wyraźnie nie nadąża.

Drugi to brak limitu iteracji. Agent, który nie potrafi domknąć zadania, potrafi krążyć do wyczerpania budżetu. Ustaw limit obrotów i traktuj jego przekroczenie jako błąd wymagający poprawy opisu zadania.

Trzeci to ogólne opisy ról. „Jesteś pomocnym asystentem" nie daje modelowi nic. Rola powinna zawierać zakres kompetencji, sposób pracy i wprost wypisane ograniczenia.

Czwarty to brak zestawu testowego. Zmiana opisu roli albo modelu potrafi poprawić trzy przypadki i zepsuć dwa, a bez listy porównawczej nikt tego nie zauważy do pierwszej skargi.

Piąty to trzymanie sekretów w opisach agentów. Wszystko, co wpiszesz w rolę albo w opis zadania, trafia do promptu i do logów wykonania.

FAQ

Czy CrewAI jest darmowy?

Framework jest otwarty na licencji MIT i darmowy także komercyjnie, bez limitu uruchomień na własnej infrastrukturze. Płatna jest platforma AMP do wdrażania i monitorowania, a jej cennik ma tylko dwa poziomy: plan Basic za 0 USD z 50 uruchomieniami miesięcznie, dwiema automatyzacjami i bez możliwości doładowania oraz plan Enterprise wyceniany indywidualnie. Planu pośredniego z kwotą abonamentu w cenniku nie ma.

CrewAI czy LangGraph?

CrewAI szybciej dowozi wynik, gdy zadanie da się opisać jako zespół z podziałem ról. LangGraph daje pełną kontrolę nad przepływem, trwały stan i możliwość zatrzymania procesu na akceptacji człowieka, więc lepiej pasuje do procesów biznesowych o ustalonym przebiegu.

Ile kosztuje jeden przebieg zespołu?

Zależy od liczby agentów, narzędzi i modelu. Zespół trzech agentów z pamięcią wykonuje zwykle od ośmiu do dwudziestu wywołań modelu na zadanie, więc przy modelu średniej klasy jeden przebieg to kilkanaście do kilkudziesięciu centów. Policz to na dziesięciu realnych przypadkach przed wdrożeniem.

Czy działa z modelami innymi niż OpenAI?

Tak, obsługuje modele różnych dostawców, w tym Claude i modele lokalne uruchomione przez Ollamę. Zmiana sprowadza się do wskazania innego modelu w konfiguracji agenta, przy czym opisy ról zwykle wymagają dostrojenia po zmianie.

Czy nadaje się do produkcji?

Tak, przy dwóch warunkach. Proces musi mieć limity iteracji i obsługę błędów, bo bez nich awaria kończy się cichym zatrzymaniem albo rachunkiem. Potrzebny jest też zestaw przypadków testowych uruchamiany po każdej zmianie promptu, ponieważ zachowanie agentów zmienia się w sposób trudny do zauważenia.

Dokumentacja stoi na docs.crewai.com, a kod źródłowy w repozytorium na GitHubie.