Jak nauczyć się tworzenia agentów AI od podstaw

Sześciostopniowa ścieżka

Aby nauczyć się tworzenia agentów AI od podstaw, należy przejść przez sześć etapów w określonej kolejności: koncepcje, pierwsza pętla, narzędzia, pamięć, projektowanie pętli oraz bezpieczeństwo. Każdy etap kończy się zbudowaniem konkretnego elementu. Pomijanie etapów jest najczęstszą przyczyną braku postępów, ponieważ frameworki ukrywają dokładnie te mechanizmy, które należy zrozumieć.

Agent AI to pętla wokół modelu językowego, który posiada uprawnienia do wywoływania narzędzi. To zdanie stanowi istotę całego zagadnienia. Wszystko, co następuje później, to szczegóły dotyczące zawartości pętli, zakresu dostępu narzędzi oraz sposobów przerwania pętli w przypadku wystąpienia błędu. Jeśli potrafisz wyjaśnić działanie pętli innej osobie, oznacza to, że opanowałeś materiał. Jeśli potrafisz jedynie wymienić nazwy frameworków, nie opanowałeś go.

Poniższy plan zakłada naukę poprzez budowanie. Przeczytaj etap, zbuduj mały projekt, celowo go zepsuj, a następnie przejdź dalej. Etap, który został tylko przeczytany, jest etapem niewykonanym.

Czego faktycznie potrzeba przed etapem 1

Lista rzeczywistych wymagań wstępnych jest krótka i krótsza, niż sugeruje większość stron kursów.

• Umiejętność czytania i pisania w Python lub TypeScript na poziomie pięćdziesięcioliniowego skryptu.
• Swoboda w pracy z powłoką Linux: instalacja pakietu, edycja pliku, odczyt logów.
• Posiadanie klucza API do hostowanego modelu lub maszyny zdolnej do uruchomienia modelu lokalnego.

To cała lista. Nie jest wymagana teoria uczenia maszynowego ani doświadczenie w trenowaniu modeli. Praca z agentami nie obejmuje gradientów ani danych treningowych. Karta graficzna ma znaczenie tylko w przypadku samodzielnego uruchamiania modelu, co jest osobną umiejętnością, którą można zdobyć później, korzystając z hosting Ollama on a VPS to self host an LLM.

Często niedocenianą kwestią jest biegłość w obsłudze powłoki. Agenci zawodzą z powodu uprawnień, ścieżek, zmiennych środowiskowych oraz procesów, które kończą się bez komunikatu. Jeśli ślad stosu (stack trace) dotyczący PATH lub trybu pliku powoduje chęć zamknięcia terminala, należy najpierw poświęcić weekend na podstawy systemu Linux. Pozwoli to zaoszczędzić miesiąc pracy w przyszłości.

Etap 1: czym jest agent, a czym nie jest

Zacznij od jednego wywołania API bez pętli. Wyślij prompt, wyświetl odpowiedź i sprawdź liczbę tokenów w odpowiedzi. Zrozumiesz w ten sposób jednostkę kosztu oraz jednostkę opóźnienia.

Następnie poznaj mechanizm użycia narzędzi (tool use), który jest jedyną autentycznie nową koncepcją w tej dziedzinie. Opisujesz modelowi funkcję, podając jej nazwę, opis oraz schemat JSON (JavaScript object notation) dla jej argumentów wejściowych. Model nie uruchamia żadnego kodu. Odpowiada ustrukturyzowanym żądaniem: wywołaj run_command z tymi argumentami. Twój kod wykonuje funkcję, odsyła wynik jako wiadomość i ponownie pyta model. Model pełni rolę planisty, który czyta i generuje tekst. Twój kod jest wykonawcą działań.

Chatbot kończy pracę po jednej odpowiedzi. Agent powtarza tę wymianę, dopóki model przestanie żądać użycia narzędzi. Ta powtarzalność stanowi całą różnicę i wyjaśnia, dlaczego tryby awarii również są odmienne. Chatbot udziela błędnej odpowiedzi jednorazowo. Agent podejmuje działania na podstawie błędnej odpowiedzi wielokrotnie, zanim ktokolwiek to zauważy.

Etap 2: samodzielne napisanie pętli

Nie należy zaczynać od frameworka. Wystarczy około trzydziestu linii kodu w Python, aby zrozumieć strukturę rozwiązania.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

Uruchom skrypt za pomocą python3 agent.py. Poprawne wykonanie skutkuje wyświetleniem akapitu z nazwami systemów plików oraz ilością wolnego miejsca, ponieważ model otrzymał polecenie df -h, kod je wykonał, a drugie przejście pętli przekształciło tabelę w zdanie. Brak danych wyjściowych oznacza, że pętla zakończyła się przed otrzymaniem bloku tekstu. Dodaj print(response.stop_reason) wewnątrz pętli, aby obserwować zmiany wartości.

Teraz celowo wywołaj błąd. Usuń linię tool_use_id i przeanalizuj komunikat o błędzie. Wynik narzędzia bez pasującego identyfikatora jest odrzucany przez API, co stanowi najczęstszy błąd początkujących użytkowników. Zadaj pytanie wymagające użycia dwóch poleceń i obserwuj dwukrotne wykonanie pętli. Zadaj pytanie niemożliwe do zrealizowania i sprawdź, czy proces przerwie działanie, czy wpadnie w nieskończoną pętlę.

Ostrzeżenie dotyczące tego przykładu: przekazuje on dane wyjściowe modelu bezpośrednio do powłoki za pomocą shell=True. Jest to dopuszczalne na maszynie testowej, którą można łatwo odtworzyć, ale niedopuszczalne w jakimkolwiek innym środowisku. Etap 6 rozwiązuje ten problem. Koncepcje związane z pętlą zostały szerzej omówione w budowaniu własnego agenta AI na VPS.

Etap 3: narzędzia, których agent wcześniej nie posiadał

Twoje narzędzie run_command działa, ale prawdziwy agent potrzebuje narzędzi, które wykraczają poza jego środowisko: systemu zgłoszeń, bazy danych, repozytorium. Pisanie dedykowanego wrappera dla każdej usługi i każdego agenta nie jest skalowalne.

Model Context Protocol (MCP) to rozwiązanie, które przyjęła branża. Serwer MCP udostępnia zestaw narzędzi za pośrednictwem standardowego transportu, a każdy agent obsługujący MCP może z nich korzystać bez dodatkowego kodu integrującego. Referencyjny serwer systemu plików uruchamia się jednym poleceniem:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

Wymaga to zainstalowanego Node, a argument katalogu jest jedyną ścieżką, do której serwer będzie miał dostęp. To model bezpieczeństwa w miniaturze: to serwer wyznacza granice, a nie model. Wskaż na niego klienta, a Twój agent zyska możliwość odczytu i zapisu plików, których nie musiałeś samodzielnie implementować. Prawidłowe uruchamianie tych narzędzi, z wykorzystaniem konta serwisowego i z uwzględnieniem wyboru transportu, zostało opisane w uruchamianie serwerów MCP na VPS dla agentów programistycznych AI.

Lekcją płynącą z tego etapu jest to, że projektowanie narzędzi to właściwa praca. Niejasny opis zmusza model do zgadywania. Narzędzie, które zwraca czterdzieści tysięcy znaków, zatruwa okno kontekstowe. Narzędzie, które może usuwać dane, w końcu je usunie.

Etap 4: pamięć, czyli w praktyce głównie pliki

Początkujący użytkownicy sięgają w tym miejscu po bazę wektorową. Nie należy tego robić, przynajmniej na początku.

Agent nie posiada pamięci między wywołaniami. Za każdym razem przesyłana jest cała konwersacja, dlatego długa sesja kosztuje więcej za każdą turę niż krótka. Pamięć dzieli się zatem na dwa problemy. Pierwszym jest to, co mieści się w oknie kontekstowym w danej chwili; zarządza się tym poprzez podsumowywanie, usuwanie starych wyników narzędzi oraz buforowanie stałego prefiksu promptu, co pozwala płacić ułamek ceny za ten fragment. Drugim problemem jest to, co przetrwa restart, czyli przechowywanie danych.

W przypadku drugiego problemu zwykły plik markdown, który agent może odczytywać i zapisywać, sprawdza się lepiej niż baza wektorowa w niemal każdym pierwszym projekcie. Należy udostępnić jeden plik, określić jego format i polecić agentowi odczytanie go przed rozpoczęciem pracy oraz aktualizację po zdobyciu nowej wiedzy. Pozwala to uzyskać większość korzyści, a użytkownik może samodzielnie otworzyć plik i sprawdzić, co agent „wie”. Po embeddingi i mechanizmy wyszukiwania warto sięgnąć dopiero wtedy, gdy notatki przestaną mieścić się w oknie kontekstowym, a nie wcześniej.

Etap 5: pętla jako produkt

Na tym etapie potrafisz stworzyć agenta, który działa, gdy go obserwujesz. Etap 5 polega na sprawieniu, by działał, gdy tego nie robisz.

Cztery pytania decydują o tym, czy pozostawienie agenta bez nadzoru jest bezpieczne. Co go wyzwala, aby nie działał bez celu. W jakich granicach operuje, aby ewentualny błąd pozostał ograniczony. Jak weryfikowany jest wynik, ponieważ agent oceniający własną pracę zawsze wystawia sobie ocenę pozytywną. Jaki budżet go zatrzymuje, wyrażony w tokenach lub czasie rzeczywistym. Świadome zaprojektowanie tych czterech elementów to dyscyplina opisana w inżynierii pętli i zakresie tej definicji.

Ćwiczenie: weź agenta z etapu 2, przydziel mu zadanie wymagające czterech lub pięciu kroków i dodaj sztywny limit iteracji. Następnie usuń limit i obserwuj, co nieograniczona pętla robi z rachunkiem za tokeny. Wykonaj to raz przy małym budżecie, aby nigdy nie dopuścić do takiej sytuacji przypadkowo przy dużym.

Etap 6: bezpieczeństwo, sekrety i koszty

Ten etap nie jest opcjonalny. Znajduje się na końcu tylko dlatego, że ryzyko staje się odczuwalne dopiero po zbudowaniu działającego rozwiązania.

Uruchamiaj agenta jako osobnego użytkownika bez uprawnień, nigdy jako root i nigdy jako własne konto. Dzięki temu zasięg ewentualnej awarii ogranicza się do katalogu, a nie całego systemu. Nie udostępniaj poświadczeń modelowi, ponieważ wszystko, co znajduje się w oknie kontekstowym, może zostać wycieknąć poprzez wywołanie narzędzia. Rozwiązaniem jest stosowanie krótkotrwałych tokenów za pośrednictwem pomocnika, zgodnie z opisem w ochrona sekretów przed agentami AI. Ustaw twardy limit wydatków, ponieważ niekontrolowana pętla generuje koszty przy każdej iteracji, gdy nikt jej nie nadzoruje. Limity oraz mechanizmy grupowania, które zapewniają stabilność, opisano w kontrola kosztów agenta AI na serwerze VPS.

Kwestia kosztów wymaga konkretnych liczb. Według stanu na lipiec 2026 roku, Claude Opus 5 kosztuje 5 USD za milion tokenów wejściowych i 25 USD za milion tokenów wyjściowych. Gadatliwy agent, przesyłający ponownie rosnącą historię konwersacji, może przetworzyć kilkaset tysięcy tokenów w ramach jednego zadania. Prompt caching oraz stosowanie mniejszego modelu do rutynowych kroków zmieniają ten rachunek znacznie bardziej niż jakakolwiek optymalizacja promptu.

W tym miejscu należy również wspomnieć o prompt injection. Jeśli agent odczytuje stronę internetową, system śledzenia zgłoszeń lub skrzynkę odbiorczą, autorzy tych treści jednocześnie tworzą instrukcje dla agenta. Wyszukiwarka internetowa jest zazwyczaj narzędziem, które otwiera tę furtkę jako pierwsze, a skierowanie agenta na własną instancję SearXNG pokazuje zarówno sposób konfiguracji, jak i wynikającą z tego powierzchnię ataku. Obroną nie jest bardziej wyrafinowany system prompt. Obroną jest granica uprawnień, ponieważ agent, który nie ma możliwości usunięcia repozytorium, nie może zostać nakłoniony do jego usunięcia.

Którą ścieżkę nauki wybrać?

Należy wybrać jeden program nauczania i ukończyć go, zamiast próbować sześciu różnych. Repozytorium Microsoft ai-agents-for-beginners jest najbardziej kompletnym darmowym źródłem; to osiemnastolekcyjny kurs, który do lipca 2026 roku zdobył ponad 70,000 gwiazdek i jest ściśle powiązany z powyższymi etapami. Zestawienia popularnych repozytoriów z agentami są przydatne do rozeznania w dostępnych rozwiązaniach, ale słabo sprawdzają się jako sylabus, ponieważ lista posortowana według liczby gwiazdek odzwierciedla popularność, a nie kolejność dydaktyczną.

Jeśli celem jest praca nad rzeczywistym projektem w ramach ćwiczeń, najlepszym pierwszym wyborem będzie agent programistyczny: informacja zwrotna jest natychmiastowa, narzędzia są oczywiste, a błędy łatwo naprawić. Artykuł Uruchamianie agenta AI do programowania na VPS przeprowadza przez ten proces od początku do końca. Jeśli zamiast budowania od zera preferowana jest analiza działających systemów, porównanie w najlepsze agenty AI do samodzielnego hostowania pokazuje, jak różne projekty rozwiązują ten sam problem pętli działania.

Ile czasu to zajmuje?

Dla osoby posiadającej doświadczenie w programowaniu, etapy 1 i 2 zajmują jeden wieczór. Etap 3 to kwestia weekendu, przy czym większość czasu poświęca się na opisy narzędzi, a nie na sam protokół. Etapy 4 i 5 wymagają kilku tygodni rzeczywistego użytkowania, ponieważ braki w pamięci agenta można zidentyfikować dopiero poprzez obserwację jego działania. Etap 6 nigdy się nie kończy, gdyż każda nowa funkcja nadana agentowi wymaga ponownej optymalizacji.

Dwa miesiące regularnej pracy wieczorami pozwalają większości osób stworzyć działającego, ograniczonego i użytecznego agenta. Osoby, którym zajmuje to rok, zazwyczaj poświęcają czas na czytanie zamiast na budowanie.

FAQ

Czy muszę znać uczenie maszynowe, aby budować agentów AI?

Nie. Budowa agenta polega na wywoływaniu modelu przez API i łączeniu jego żądań narzędzi z rzeczywistymi funkcjami, co jest zwykłym programowaniem aplikacji. Nie ma potrzeby zajmowania się trenowaniem, gradientami ani zbiorami danych. O skuteczności agenta decyduje projekt schematów dla narzędzi, obsługa błędów oraz uprawnienia w systemie Linux. Teoria uczenia maszynowego staje się istotna dopiero w przypadku dostrajania modelu, co jest odrębnym zadaniem o innych wymaganiach wstępnych.

Czy powinienem zacząć od frameworka typu LangChain lub CrewAI?

Najpierw napisz jedną surową pętlę, a dopiero potem wdróż framework. Framework zastępuje trzydzieści linii kodu z etapu 2 obiektem konfiguracyjnym, co jest wygodne, gdy wiadomo, co zostało zastąpione, ale dezorientuje, gdy brak tej wiedzy. Gdy agent działa nieprawidłowo, konieczna jest analiza listy wiadomości i wyników narzędzi, co jest znacznie trudniejsze bez wcześniejszego doświadczenia z tym mechanizmem. Po napisaniu własnej pętli framework oszczędza czas, zamiast ukrywać działanie systemu.

Ile kosztuje nauka budowania agentów AI?

Mniej niż większość osób zakłada, pod warunkiem nałożenia limitów. Klucz API oraz niewielki VPS wystarczą do realizacji wszystkich sześciu etapów. Rzeczywistym ryzykiem nie jest stawka godzinowa, lecz nieograniczona pętla naliczająca opłaty za każdą iterację podczas snu. Ustaw twardy limit wydatków na koncie API pierwszego dnia, dodaj limit iteracji do każdej napisanej pętli i używaj tańszego modelu do rutynowych zadań. Uruchomienie modelu lokalnie eliminuje opłaty za tokeny, zastępując je wymaganiami sprzętowymi.

Jaka jest różnica między agentem AI a chatbotem?

Chatbot udziela pojedynczej odpowiedzi. Agent powtarza cykl: model prosi o narzędzie, kod je uruchamia, wynik wraca do modelu, a model decyduje o kolejnym kroku. Ta powtarzalność pozwala agentowi wykonać zadanie wieloetapowe i jest powodem, dla którego agenci wymagają ograniczeń, których chatboty nie potrzebują. Błędna odpowiedź chatbota to tylko niepoprawny akapit tekstu. Błędna odpowiedź agenta to niepoprawny akapit oraz skutki działań, które agent podjął na jego podstawie.