Mastra AI: jak budować agentów AI w TypeScript

Mastra AI to otwartoźródłowy framework do budowy agentów AI w TypeScript, czyli w tym samym języku, w którym powstaje dziś duża część aplikacji webowych. Agent AI to program, w którym model językowy sam decyduje, jakie kroki wykonać i z jakich narzędzi skorzystać, żeby załatwić sprawę klienta albo pracownika. Mastra daje do tego gotowe klocki: narzędzia, pamięć, przepływy pracy, testy jakości i podgląd tego, co agent właściwie robi. Za projektem stoją twórcy Gatsby'ego, popularnego frameworka do budowy stron. Wersja 1.0 ukazała się 20 stycznia 2026 roku z zapowiedzią, że interfejs programistyczny jest już ustabilizowany. W tym samym ogłoszeniu autorzy podali ponad 300 tys. pobrań tygodniowo z rejestru npm i wymienili wśród firm używających Mastry produkcyjnie m.in. Replit, PayPal i Sanity.

Mastra AI w skrócie: framework do agentów w TypeScript

Mastra jest biblioteką, którą programista instaluje w projekcie Node.js, czyli w środowisku uruchamiającym kod JavaScript i TypeScript na serwerze. Nie jest gotowym chatbotem ani platformą do wyklikania. To zestaw elementów, z których zespół składa własne rozwiązanie, a kod i dane zostają u firmy. Z modelami językowymi Mastra łączy się przez wspólny interfejs. Model wskazuje się jednym napisem w formacie „dostawca/model", więc przejście z modelu OpenAI na Claude od Anthropic to zwykle zmiana jednej linijki i klucza dostępu. Zwykle, bo modele różnią się zachowaniem i po każdej zmianie agenta trzeba przetestować od nowa. Tak samo wygląda przejście na Gemini od Google. Licencja jest prosta, z jednym wyjątkiem. Rdzeń frameworka udostępniono na licencji Apache 2.0, która pozwala używać go komercyjnie bez opłat. Część funkcji dla dużych firm leży w osobnych katalogach na licencji Mastra Enterprise License: można je testować, ale do użycia produkcyjnego potrzebna jest płatna licencja.

AI długo kojarzyło się z Pythonem, w którym powstały pierwsze popularne biblioteki do pracy z modelami językowymi. Tymczasem sklepy, panele i systemy, z którymi agent ma współpracować, często działają na JavaScripcie i TypeScripcie, czyli JavaScripcie z kontrolą typów danych. W sierpniu 2025 roku TypeScript po raz pierwszy wyprzedził Pythona pod względem liczby osób rozwijających kod na GitHubie, a GitHub wiąże to m.in. z popularnością narzędzi AI. Agent napisany w tym samym języku co reszta systemu korzysta z tych samych typów danych, testów i ludzi. Nie trzeba utrzymywać osobnej usługi w Pythonie tylko po to, żeby sprawdzić status zamówienia. Te same zalety TypeScriptu, które pomagają w zwykłej aplikacji, chronią też przed błędami w kodzie agenta.

Wersja 0.1: instrukcje, model i pierwsza rozmowa w Studio

Pierwsza wersja asystenta sklepu składa się z nazwy, modelu i instrukcji. Instrukcje to opis roli i granic, który model dostaje przed każdą rozmową. W naszym przykładzie mówią, że asystent odpowiada klientom sklepu z częściami rowerowymi, pisze po polsku, nie obiecuje terminów dostawy i nie przyznaje rabatów. Pisanie takich instrukcji to w dużej mierze prompt engineering, czyli praca nad tym, jak sformułować polecenie, żeby model zachowywał się przewidywalnie.

Taki agent już działa. Mastra Studio, lokalny panel otwierany w przeglądarce pod adresem localhost:4111, pozwala z nim porozmawiać, poprawić instrukcje i od razu zobaczyć efekt. Odpowiedź może pojawiać się słowo po słowie, bo Mastra obsługuje strumieniowanie. Na tym etapie agent jest jednak tylko uprzejmym rozmówcą. Nie wie, co leży w magazynie ani gdzie jest paczka klienta. Zapytany o konkretne zamówienie, może zmyślić odpowiedź, która brzmi wiarygodnie. Druga wersja dostaje więc narzędzia.

Wersja 0.2: narzędzia, czyli dostęp do danych sklepu

Narzędzie to funkcja w kodzie, którą model może wywołać, gdy uzna, że jej potrzebuje. Ma nazwę, opis zrozumiały dla modelu i schemat danych wejściowych. Asystent sklepu dostaje dwa narzędzia: sprawdzenie statusu zamówienia i stanu magazynowego części. Oba łączą się z API sklepu, czyli interfejsem, przez który programy wymieniają dane. W kodzie takie narzędzie to kilkanaście linijek. Programista podaje identyfikator, opis w rodzaju „sprawdza status zamówienia po jego numerze", schemat danych wejściowych i funkcję, która pyta sklep o status. Schemat zapisuje się w bibliotece Zod, która sprawdza dane, zanim narzędzie się uruchomi. Gotowe narzędzie dopisuje się do listy narzędzi agenta i od tej chwili model sam decyduje, kiedy po nie sięgnąć.

Ta decyzja opiera się wyłącznie na opisie. Jeśli opis jest mętny, model wywoła narzędzie nie wtedy, kiedy trzeba, albo wcale. W praktyce przy narzędziach więcej czasu zajmują nazewnictwo i opisy niż samo połączenie z API.

Narzędzia nie zawsze trzeba pisać od zera. Mastra obsługuje MCP, otwarty protokół, przez który agenci korzystają z narzędzi udostępnianych przez inne systemy. Działa to w obie strony: agent może używać cudzych serwerów MCP, a firma może wystawić własnego agenta jako serwer MCP. Dokumentacja zaznacza przy tym, że wyniki narzędzi należy traktować jak niezweryfikowane dane, a nie polecenia.

Wersja 0.3: pamięć rozmowy i klienta

Klient pisze rano, że ma rower szosowy z napędem 11-rzędowym, a po południu pyta o kasetę. Bez pamięci asystent zapyta o rower drugi raz. Mastra ma kilka rodzajów pamięci, które można łączyć:

• historia wiadomości - ostatnie wiadomości z wątku, w wersji 1.0 domyślnie dziesięć,
• pamięć robocza - uporządkowane fakty o kliencie, na przykład model roweru albo preferowana forma dostawy, zachowywane między rozmowami,
• przypominanie semantyczne - wyszukiwanie starszych wiadomości po znaczeniu, a nie po słowach; w wersji 1.0 domyślnie wyłączone,
• pamięć obserwacyjna - agenci działający w tle, którzy streszczają długą historię, żeby nie zapychała kontekstu modelu.

Pamięć trzeba gdzieś zapisać. Mastra obsługuje ponad dwadzieścia baz i usług, w tym PostgreSQL, MongoDB i Redis. Najprościej użyć bazy, którą aplikacja i tak już ma. Każda zapamiętana informacja to dane klienta przechowywane przez firmę. Przy wdrożeniach chatbotów AI ustalamy, które dane mogą trafić do modelu, co maskujemy i jak długo przechowujemy rozmowy. Przy agencie z pamięcią roboczą to pytanie trzeba zadać jeszcze wcześniej, bo agent zapamiętuje fakty sam.

Wersja 0.4: wiedza z dokumentów, czyli RAG

Pytanie „czy ta kaseta pasuje do mojej przerzutki?" wymaga wiedzy, której nie ma w bazie zamówień. Jest w tabelach kompatybilności producentów, instrukcjach w PDF i opisach produktów. Tu przydaje się RAG, czyli technika, w której agent przed odpowiedzią wyszukuje pasujące fragmenty dokumentów i odpowiada na ich podstawie. Mastra dzieli dokumenty na fragmenty, zamienia je na embeddingi, czyli liczbowe reprezentacje znaczenia tekstu, i zapisuje w bazie wektorowej. Przy pytaniu klienta wyszukuje kilka najbardziej podobnych fragmentów i przekazuje je modelowi. Tak działa wyszukiwanie oparte na embeddingach: podobieństwo liczy się dla znaczenia, a nie dla pojedynczych słów.

Bazę wektorową można postawić na tym samym PostgreSQL z rozszerzeniem pgvector albo użyć osobnej usługi, takiej jak Pinecone czy Qdrant. Jakość odpowiedzi zależy tu bardziej od dokumentów niż od frameworka. Nieaktualna tabela kompatybilności da złą odpowiedź niezależnie od modelu. W chatbocie, który przygotowaliśmy dla BlueApart, bazę wiedzy edytuje zespół klienta. Sklep rowerowy też potrzebuje osoby, która odpowiada za aktualność tabel i instrukcji.

Wersja 0.5: workflow i akceptacja człowieka przy zwrotach

Zwrot towaru to inny rodzaj zadania niż odpowiedź na pytanie. Kroki są znane: sprawdzić zamówienie i termin na zwrot, przygotować zgłoszenie, wygenerować etykietę. Nie ma sensu, żeby model za każdym razem sam wymyślał tę kolejność. Do takich zadań Mastra ma workflowy, czyli przepływy pracy z ustalonymi z góry krokami. Kroki łączy się w kodzie jak klocki. Jedne wykonują się po kolei, inne równolegle, w rozgałęzieniu workflow wybiera ścieżkę według warunku, a pętla powtarza krok dla każdej pozycji, na przykład dla każdej części w zamówieniu. Krok może wywołać zwykły kod, narzędzie albo agenta. W praktyce agent zbiera od klienta dane w rozmowie, a workflow pilnuje procedury.

Najważniejsza jest możliwość wstrzymania. Workflow może zatrzymać się w połowie, zapisać stan i czekać na decyzję człowieka. W sklepie rowerowym zwrot powyżej ustalonej kwoty trafia do pracownika, który klika „zatwierdź" albo „odrzuć", a workflow rusza dalej od miejsca, w którym stanął. Stan jest zapisany w bazie, więc przerwa może trwać godzinę albo dwa dni, a restart serwera nie gubi zgłoszenia.

To nie jest ostrożność na wyrost. Gartner przewiduje, że do końca 2027 roku ponad 40% projektów opartych na agentach AI zostanie przerwanych, a jako przyczyny wskazuje rosnące koszty, niejasną wartość biznesową i niewystarczającą kontrolę ryzyka. Akceptacja człowieka tam, gdzie agent wydaje pieniądze albo zmienia dane, to najprostsza forma takiej kontroli.

Wersja 0.6: oceny jakości, ślady i koszty

Agenta nie da się przetestować jak formularza, bo na to samo pytanie potrafi odpowiedzieć na dwa sposoby. Mastra ma do tego scorery, czyli automatyczne oceny odpowiedzi w skali od 0 do 1. Część z nich ocenia inny model językowy, na przykład trafność odpowiedzi względem pytania. Inne to proste reguły: czy agent wywołał narzędzie do statusu zamówienia, zanim podał termin dostawy. Oceny mogą działać na żywo, na wybranym odsetku rozmów, albo przed każdym wdrożeniem, jako część testów oprogramowania. W tym wariancie zestaw typowych pytań klientów działa jak test regresji: jeśli po zmianie instrukcji agent zaczyna mylić statusy, zmiana nie trafia do klientów.

Mastra zapisuje każdy przebieg agenta, wywołanie modelu i użycie narzędzia jako ślad z danymi wejściowymi, wynikiem, liczbą tokenów i czasem. Ślady można oglądać w Studio albo wysyłać do zewnętrznych narzędzi, takich jak Langfuse, Datadog czy dowolna platforma zgodna z OpenTelemetry. Tokeny to jednostki tekstu, za które płaci się dostawcy modelu, więc ślady służą też do kontroli kosztów.

Wersja 1.0: wdrożenie obok istniejącej aplikacji

Gotowego agenta trzeba gdzieś uruchomić. Mastra może działać jako samodzielny serwer API postawiony na maszynie wirtualnej, w kontenerze Docker albo w chmurze AWS. Od wersji 1.0 Mastrę można też wpiąć w istniejący serwer aplikacji napisany w Express, Fastify, Hono albo Koa. Agent działa wtedy w tym samym procesie co reszta aplikacji i może korzystać z jej mechanizmów, na przykład logowania użytkowników. Są też gotowe paczki wdrożeniowe dla platform Vercel, Netlify i Cloudflare, przydatne, gdy reszta aplikacji już tam działa. Niezależnie od miejsca agent powinien trafiać na produkcję tą samą ścieżką co reszta kodu, przez CI/CD. Zmiana instrukcji to też zmiana w kodzie i przechodzi przez te same oceny.

Agent może też być po prostu kolejnym modułem aplikacji, którą firma już ma. Dla sklepu Kwant zbudowaliśmy frontend w Next.js i TypeScripcie, a panel treści połączony z ChatGPT automatycznie generuje tam wpisy na bloga. W platformie edukacyjnej do nauki programowania zaplecze w Node.js tworzy przez API ChatGPT fiszki i quizy z wybranych tagów. W obu przypadkach model dostaje zadanie i zwraca tekst. Gdyby funkcja miała sama sięgać po dane, pamiętać użytkownika i czekać na akceptację, byłby to dobry moment na framework taki jak Mastra.

Kiedy Mastra, a kiedy inne narzędzie

Mastra nie jest jedyną drogą do agenta. Zespół, który pisze w Pythonie, ma do dyspozycji LangGraph i resztę ekosystemu LangChain. Prostsze automatyzacje da się złożyć w narzędziach wizualnych, takich jak Dify czy n8n. Nie każdy projekt potrzebuje frameworka w kodzie.

Mastra ma sens, gdy:

• zespół i aplikacja już pracują w TypeScripcie, na przykład w Next.js albo Node.js,
• agent ma korzystać z kilku narzędzi i systemów firmy, a nie tylko generować tekst,
• część procesu wymaga stałej procedury albo akceptacji człowieka,
• jakość odpowiedzi trzeba mierzyć i porównywać między wersjami,
• firma chce zachować kod i dane u siebie, bez zamkniętej platformy.