Jak nauczyć się agentów AI od podstaw

Ścieżka w sześciu etapach

Aby nauczyć się tworzyć agentów AI od podstaw, należy przejść kolejno przez sześć etapów: podstawowe pojęcia, pierwszą pętlę, narzędzia, pamięć, projektowanie pętli i bezpieczeństwo. Na każdym etapie należy samodzielnie zbudować jeden element. Pomijanie etapów jest najczęstszą przyczyną zastoju, ponieważ framework ukrywa dokładnie tę część, którą należało zobaczyć.

Agent AI to pętla wokół modelu językowego, któremu zezwolono na wywoływanie narzędzi. To zdanie obejmuje cały temat. Wszystko, co następuje później, dotyczy elementów pętli, zakresu działania narzędzi oraz sposobu zatrzymania pętli w razie błędu. Jeżeli można wyjaśnić tę pętlę innej osobie, oznacza to, że opanowano zagadnienie. Jeżeli można jedynie wymienić frameworki, oznacza to, że zagadnienie nie zostało opanowane.

Poniższy plan zakłada naukę przez budowanie. Należy przeczytać opis etapu, zbudować mały element, celowo doprowadzić go do błędu, a następnie przejść dalej. Etap, o którym tylko przeczytano, nie jest etapem wykonanym.

Czego rzeczywiście potrzeba przed etapem 1

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

• Można czytać i pisać kod w Python lub TypeScript na poziomie skryptu liczącego pięćdziesiąt wierszy.
• Należy swobodnie posługiwać się powłoką Linux: instalować pakiety, edytować pliki i odczytywać dzienniki.
• Należy mieć klucz API do hostowanego modelu albo komputer, na którym można uruchomić model lokalny.

To cała lista. Nie jest potrzebna znajomość teorii uczenia maszynowego ani wcześniejsze trenowanie modelu. Praca z agentami nie obejmuje gradientów ani danych treningowych. Karta graficzna ma znaczenie tylko wtedy, gdy model ma być uruchamiany samodzielnie. Jest to odrębna umiejętność, którą można później opanować na podstawie hostowania Ollama na VPS w celu samodzielnego uruchamiania LLM.

Najczęściej lekceważona jest część dotycząca powłoki. Agenci przestają działać z powodu uprawnień, ścieżek, zmiennych środowiskowych i procesów, które kończą się bez komunikatu. Jeżeli ślad stosu dotyczący PATH albo trybu pliku powoduje zamknięcie terminala, należy najpierw poświęcić weekend na podstawy Linux. Pozwoli to zaoszczędzić miesiąc pracy w późniejszym etapie.

Etap 1: czym jest agent i czym nie jest

Należy rozpocząć od jednego wywołania API, bez pętli. Należy wysłać prompt, wyświetlić odpowiedź i sprawdzić liczbę tokenów w odpowiedzi. W ten sposób można zrozumieć jednostkę kosztu i jednostkę opóźnienia.

Następnie należy poznać użycie narzędzi. Jest to jedyna rzeczywiście nowa koncepcja w całej tej dziedzinie. Funkcję opisuje się dla modelu za pomocą nazwy, opisu i schematu JSON (JavaScript object notation) jej danych wejściowych. Model niczego nie uruchamia. Zwraca uporządkowane żądanie: wywołać run_command z tymi argumentami. Kod uruchamia funkcję, wysyła jej wynik z powrotem jako wiadomość i ponownie wywołuje model. Model planuje na podstawie odczytywanego tekstu i generuje tekst. Kod wykonuje operacje.

Chatbot kończy działanie po jednej odpowiedzi. Agent powtarza tę wymianę do chwili, gdy model przestanie żądać użycia narzędzi. Na tym polega cała różnica. Z tego powodu różnią się również tryby awarii. Chatbot raz udziela błędnej odpowiedzi. Agent może kilkakrotnie wykonać działania na podstawie błędnej odpowiedzi, zanim ktokolwiek to zauważy.

Etap 2: napisz pętlę samodzielnie, tylko raz

Nie zaczynaj od frameworka. Napisz około trzydziestu wierszy kodu Python, aby samodzielnie określić strukturę programu.

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 program za pomocą python3 agent.py. Prawidłowe wykonanie wyświetla jeden akapit zawierający nazwy systemów plików i ilość dostępnego miejsca. Model poprosił o df -h, kod wykonał to polecenie, a drugie przejście przekształciło tę tabelę w zdanie. Jeśli program nic nie wyświetla, pętla zakończyła się przed pojawieniem się bloku tekstowego. Dodaj print(response.stop_reason) wewnątrz pętli i obserwuj zmiany wartości.

Następnie celowo wywołaj błąd. Usuń wiersz tool_use_id i odczytaj komunikat błędu. Wynik narzędzia bez pasującego identyfikatora jest odrzucany przez API. Jest to najczęstszy błąd początkujących. Zadaj pytanie wymagające wykonania dwóch poleceń i obserwuj dwukrotne wykonanie pętli. Zadaj pytanie, na które nie można odpowiedzieć, i sprawdź, czy program się zatrzyma, czy będzie działać bez końca.

Należy zwrócić uwagę na jedno zagrożenie w tym przykładzie. Przekazuje on wynik modelu bezpośrednio do powłoki za pomocą shell=True. Jest to dopuszczalne na maszynie testowej, którą można odtworzyć, ale w każdym innym środowisku jest błędne. Etap 6 rozwiązuje ten problem. Zagadnienia związane z działaniem pętli omówiono szerzej w tworzenie własnego agenta AI na VPS.

Etap 3: narzędzia, których agent jeszcze nie miał

Narzędzie run_command działa, ale rzeczywisty agent potrzebuje narzędzi umożliwiających dostęp do zasobów poza systemem: systemu zgłoszeń, bazy danych i repozytorium. Tworzenie niestandardowego wrappera dla każdej usługi i każdego agenta nie skaluje się.

Model Context Protocol (MCP) to rozwiązanie, które przyjęto w branży. 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 niestandardowego kodu integracyjnego. Referencyjny serwer systemu plików uruchamia się jednym poleceniem:

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

Wymaga to zainstalowanego Node, a argument określający katalog jest jedyną ścieżką, której serwer będzie używać. W uproszczeniu tak wygląda ten model zabezpieczeń: granicę wyznacza serwer, a nie model. Po wskazaniu tego serwera klientowi agent uzyskuje możliwość odczytu i zapisu plików, której nie trzeba było samodzielnie implementować. Prawidłowe uruchamianie takich serwerów, przy użyciu konta usługi i z omówieniem opcji transportu, opisano w uruchamianie serwerów MCP na VPS dla agentów AI do kodowania.

Najważniejszy wniosek z tego etapu jest taki, że projektowanie narzędzi stanowi właściwą pracę. Nieprecyzyjny opis zmusza model do zgadywania. Narzędzie zwracające czterdzieści tysięcy znaków zanieczyszcza okno kontekstu. Narzędzie umożliwiające usuwanie obiektów ostatecznie je usunie.

Etap 4: pamięć, która w większości sprowadza się do plików

Początkujący sięgają tutaj po wektorową bazę danych. Na razie nie należy tego robić.

Agent nie ma pamięci między wywołaniami. Za każdym razem przesyłana jest cała rozmowa, dlatego długa sesja kosztuje więcej na turę niż krótka. Pamięć dzieli się więc na dwa problemy. Pierwszy dotyczy tego, co mieści się obecnie w oknie kontekstu. Zarządza się tym przez tworzenie podsumowań, usuwanie starych wyników narzędzi oraz buforowanie stabilnego prefiksu promptu, dzięki czemu płaci się za niego tylko ułamek ceny. Drugi dotyczy tego, co przetrwa ponowne uruchomienie. Jest to kwestia przechowywania danych.

W drugim przypadku zwykły plik markdown, który agent może odczytywać i zapisywać, sprawdza się lepiej niż wektorowa baza danych w niemal każdym pierwszym projekcie. Należy udostępnić agentowi jeden plik, określić jego format, polecić odczytywanie go przed rozpoczęciem pracy oraz aktualizowanie po zdobyciu nowych informacji. Zapewnia to większość korzyści, a plik można otworzyć i sprawdzić, co agent uznaje za prawdziwe. Po osadzenia i wyszukiwanie należy sięgać dopiero wtedy, gdy notatki przestaną mieścić się w oknie kontekstu.

Etap 5: pętla jest produktem

Na tym etapie można już utworzyć agenta, który działa pod nadzorem. Etap 5 polega na zapewnieniu jego działania bez nadzoru.

O tym, czy można bezpiecznie pozostawić agenta bez nadzoru, decydują cztery pytania. Co go uruchamia, aby nie działał bez powodu. W jakich granicach działa, aby błąd miał ograniczone skutki. Jak weryfikowany jest wynik, ponieważ agent, który sam ocenia własną pracę, zawsze uznaje ją za poprawną. Jaki limit zatrzymuje agenta — liczba tokenów czy czas rzeczywisty. Celowe zaprojektowanie tych czterech elementów stanowi dyscyplinę opisaną w projektowaniu pętli i zakresie tego pojęcia.

Ćwiczenie: użyj agenta z etapu 2, przydziel mu zadanie wymagające czterech lub pięciu kroków i dodaj twardy limit iteracji. Następnie usuń ten limit i obserwuj wpływ nieograniczonej pętli na zużycie tokenów. Wykonaj to raz przy małym budżecie, aby nie zrobić tego przypadkowo przy dużym budżecie.

Etap 6: bezpieczeństwo, dane uwierzytelniające i koszty

Ten etap nie jest opcjonalny. Znajduje się na końcu wyłącznie dlatego, że ryzyka nie można odczuć, dopóki nie zostanie zbudowane coś, co działa.

Uruchamiany agent powinien używać własnego nieuprzywilejowanego konta. Nie należy uruchamiać go jako root ani jako własne konto. Dzięki temu zakres potencjalnych szkód ogranicza się do katalogu, a nie do całej maszyny. Dane uwierzytelniające należy trzymać poza zasięgiem modelu, ponieważ wszystko, co znajduje się w oknie kontekstu, może zostać zwrócone w odpowiedzi za pośrednictwem wywołania narzędzia. Rozwiązaniem są ograniczone czasowo tokeny używane za pośrednictwem helpera, zgodnie z opisem w przechowywanie danych uwierzytelniających poza zasięgiem agentów AI. Należy ustawić twardy limit wydatków, ponieważ działająca bez nadzoru pętla nalicza opłaty za każdą iterację. Limity i przetwarzanie wsadowe opisane w kontrola kosztów agenta AI na stale działającym VPS zapobiegają niekontrolowanemu wzrostowi kosztów.

Koszt wymaga podania konkretnej wartości. W lipcu 2026 Claude Opus 5 nalicza $5 za milion tokenów wejściowych i $25 za milion tokenów wyjściowych. Agent wysyłający wielokrotnie rozrastającą się konwersację może przetworzyć w ramach jednego zadania kilkaset tysięcy tokenów. Buforowanie promptów i użycie mniejszego modelu do rutynowych czynności zmieniają te wyliczenia znacznie bardziej niż dowolna korekta promptu.

Należy uwzględnić również prompt injection. Jeżeli agent odczytuje stronę internetową, system śledzenia zgłoszeń lub skrzynkę odbiorczą, osoba, która napisała ten tekst, tworzy jednocześnie instrukcje dla agenta. Ochroną nie jest sprytniejszy prompt systemowy. Ochronę zapewnia granica uprawnień, ponieważ agent, który nie może usunąć repozytorium, nie może zostać nakłoniony do jego usunięcia.

Której mapy należy się trzymać?

Należy wybrać jeden program i ukończyć go zamiast przeglądać sześć. Repozytorium Microsoft ai-agents-for-beginners jest najbardziej kompletnym bezpłatnym programem. Obejmuje osiemnaście lekcji i w lipcu 2026 miało ponad 70,000 gwiazdek. Jego struktura odpowiada etapom opisanym powyżej. Zestawienia popularnych repozytoriów agentów ułatwiają sprawdzenie, jakie projekty istnieją, ale znacznie gorzej sprawdzają się jako program nauki. Lista posortowana według liczby gwiazdek jest uporządkowana według popularności, a nie kolejności nauki.

Do praktycznych ćwiczeń najlepiej na początek wybrać agenta programistycznego. Informacja zwrotna jest natychmiastowa, narzędzia są oczywiste, a błędy można łatwo cofnąć. W artykule Uruchamianie agenta AI do programowania na VPS opisano cały proces. Jeśli zamiast tworzyć system od zera wolisz przeanalizować działające systemy, porównanie najlepszych agentów AI hostowanych samodzielnie pokazuje, jak kilka projektów odmiennie rozwiązuje tę samą pętlę działania.

Jak długo to potrwa?

Dla osoby, która już programuje, etapy 1 i 2 zajmują jeden wieczór. Etap 3 zajmuje weekend, przy czym większość czasu pochłaniają opisy narzędzi, a nie protokół. Etapy 4 i 5 wymagają kilku tygodni rzeczywistego użytkowania, ponieważ można się dowiedzieć, o czym agent zapomina, tylko obserwując, jak zapomina. Etap 6 nigdy nie kończy się całkowicie, ponieważ każda nowa przyznana funkcja powoduje konieczność ponownego przeanalizowania tego etapu.

Dwa miesiące regularnej pracy wieczorami wystarczą większości osób do zbudowania działającego, ograniczonego i użytecznego agenta. Osoby, którym zajmuje to rok, zwykle nadal czytają zamiast budować.

FAQ

Czy muszę znać uczenie maszynowe, aby zbudować agenta AI?

Nie. Budowanie agenta polega na wywoływaniu modelu za pośrednictwem API oraz podłączaniu jego żądań użycia narzędzi do rzeczywistych funkcji. Jest to standardowe programowanie aplikacji. Nie ma potrzeby zajmowania się trenowaniem, gradientami ani zbiorami danych. O działaniu agenta decydują przede wszystkim projektowanie schematów narzędzi, obsługa błędów i uprawnienia systemu Linux. Teoria uczenia maszynowego staje się istotna dopiero w przypadku dalszego dostrajania modelu. Jest to odrębne zadanie, wymagające innych podstaw.

Czy należy rozpocząć od frameworka, takiego jak LangChain lub CrewAI?

Najpierw należy napisać jedną pętlę bezpośrednio, a dopiero potem przyjąć framework. Framework zastępuje trzydzieści wierszy z etapu 2 obiektem konfiguracyjnym. Jest to wygodne, gdy wiadomo, co zostało zastąpione, ale wcześniej może powodować niejasności. W przypadku nieprawidłowego działania agenta trzeba bezpośrednio przeanalizować listę komunikatów i wyniki działania narzędzi. Jest to znacznie trudniejsze, jeśli nie zostały one wcześniej poznane. Po napisaniu własnej pętli framework oszczędza czas, zamiast ukrywać mechanizm działania.

Ile kosztuje nauka budowania agentów AI?

Mniej, niż zwykle się oczekuje, jeśli koszty zostaną ograniczone. Klucz API udostępniany przez dostawcę oraz niewielki VPS wystarczą do wykonania wszystkich sześciu etapów. Rzeczywistym zagrożeniem nie jest stawka godzinowa, lecz nieograniczona pętla, która nalicza opłaty za każdą iterację podczas nieobecności użytkownika. Od pierwszego dnia należy ustawić twardy limit wydatków na koncie API, dodać limit iteracji do każdej tworzonej pętli oraz używać tańszego modelu w rutynowych krokach. Uruchomienie modelu lokalnie eliminuje opłaty za tokeny, ale wymaga odpowiedniego sprzętu.

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

Chatbot udziela jednej odpowiedzi. Agent powtarza cykl: model żąda użycia narzędzia, kod je uruchamia, wynik jest przekazywany z powrotem, a model decyduje, co zrobić dalej. To powtarzanie umożliwia agentowi wykonanie zadania składającego się z kilku kroków. Z tego samego powodu agenci wymagają ograniczeń, które nie są potrzebne chatbotom. Błędna odpowiedź chatbota to nieprawidłowy akapit. Błędna odpowiedź agenta to nieprawidłowy akapit oraz działania wykonane na jej podstawie.