Agent AI: jak działa i jak zbudować go do realnej pracy

Polecenia z tego poradnika zostały uruchomione 6 października 2026 w czystym systemie (Ubuntu 24.04.5 LTS, Node.js 24.21.0, Python 3.12.3). Wyniki pod poleceniami pochodzą z tego uruchomienia.

Agent AI to system, w którym model dobiera kolejne działania i narzędzia, aby wykonać zadanie. Takie rozróżnienie między agentem a procesem o z góry ustalonej kolejności przyjmuje Anthropic w przewodniku po architekturach agentowych. Żeby zbudować użytecznego agenta, proponuję zacząć od jednego mierzalnego zadania, udostępnić potrzebne operacje, zaprogramować kontrolę uprawnień i sprawdzać wynik poza odpowiedzią modelu.

Przykładem będzie przygotowanie odpowiedzi na zgłoszenie: odczyt problemu, sprawdzenie procedury i zapis szkicu do zatwierdzenia. Pokażę, jak zaprojektować taki proces, gdzie pasują MCP i RAG oraz jak ocenić, czy automatyzacja się opłaca. Dokumentację sprawdziłem 6 października 2026 r.

W skrócie

• Zaczynam od konkretnego rezultatu, np. szkicu odpowiedzi opartego na wskazanej procedurze.
• Wybieram agenta, gdy kolejne kroki zależą od odkrytych informacji; dla stałej sekwencji rozważam workflow.
• Kontrolę dostępu, limity i zatwierdzanie zmian umieszczam w aplikacji.
• Ocenę opieram na rezultacie zadania, błędach, czasie i koszcie.

Co agent AI robi inaczej niż chatbot?

Najważniejsze pytanie brzmi: kto wybiera następny krok? W definicji Anthropic workflow prowadzi model przez wcześniej zapisane ścieżki, a agent dynamicznie kieruje procesem i użyciem narzędzi. Sam interfejs czatu nie rozstrzyga architektury.

Dla projektu obsługującego zgłoszenia porównuję możliwości następująco. Przykłady i wskazania w tabeli są moimi propozycjami projektowymi.

Przy streszczeniu dokumentu zacząłbym od pojedynczego wywołania modelu. Przy analizie zgłoszenia, które może wymagać sprawdzenia dokumentacji, historii zamówienia albo dodatkowego pytania, rozważyłbym agenta. Warunkiem byłaby możliwość sprawdzenia poprawności jego pracy.

Jak działa pętla agenta?

W mechanizmie narzędzi Claude model zwraca ustrukturyzowane żądanie operacji, aplikacja wykonuje narzędzie i przekazuje wynik do dalszej rozmowy. Dla narzędzi wykonywanych przez aplikację to właśnie jej kod prowadzi pętlę.

Projektuję ją tak, aby każde działanie przechodziło przez kontrolę przed wykonaniem. Diagram pokazuje proponowaną architekturę, łącznie z zatrzymaniem po przekroczeniu limitu.

flowchart TD
    A[Cel użytkownika] --> B[Model]
    B --> C{Następny krok}
    C -->|Narzędzie| D{Uprawnienia i limit}
    D -->|Zgoda| E[Wykonanie operacji]
    E --> F[Wynik narzędzia]
    F --> B
    D -->|Odmowa| G[Zatrzymanie]
    C -->|Gotowe| H[Kontrola rezultatu]

Dla zgłoszenia „nie działa eksport” model mógłby najpierw odczytać opis błędu, potem sprawdzić procedurę eksportu i przygotować odpowiedź. Jeśli procedura wymaga informacji o wersji aplikacji, polecam zakończyć etap pytaniem do użytkownika. Nie polecam zgadywania brakujących danych.

Z czego składa się agent?

Rozdzielam odpowiedzialności na cztery części: model proponuje działania, narzędzia realizują operacje, stan zadania zapisuje postęp, a aplikacja egzekwuje zasady wykonania. Instrukcja dla modelu powinna opisywać cel i kryteria zakończenia. Kod powinien rozstrzygać dostęp do danych i możliwość wykonania zmian.

W przykładzie narzędzie odczytuje zgłoszenie, stan przechowuje jego identyfikator, a aplikacja pozwala zapisać szkic. Wysłanie wiadomości projektuję jako osobną operację wymagającą zatwierdzenia. Taki podział pozwala przeglądać konkretne uprawnienia każdej funkcji.

Wybierz zadanie, które da się odebrać

Zanim wybiorę model lub bibliotekę, zapisuję kontrakt zadania. Proponuję następującą kolejność:

1. Nazwij rezultat. Zamiast „obsługuj klientów” zapisz „przygotuj szkic odpowiedzi na zgłoszenie z odwołaniem do procedury”.
2. Określ dane wejściowe. Wskaż treść zgłoszenia, dostępne dokumenty i kontekst użytkownika.
3. Wypisz dozwolone operacje. Rozdziel odczyt, tworzenie szkicu i wysyłkę; zdecyduj, które wymagają akceptacji.
4. Ustal kryteria odbioru. Sprawdź zgodność z procedurą, kompletność informacji i obecność zapisanego wyniku.
5. Zdefiniuj zatrzymanie. Ustal reakcję na brak danych, odmowę dostępu, awarię narzędzia i wyczerpanie budżetu.

Dla przykładowego zgłoszenia kryterium odbioru może brzmieć: „szkic wskazuje odpowiednią procedurę i pyta o brakujący komunikat błędu”. Dodałbym warunek, że agent nie obiecuje rozwiązania, którego procedura nie potwierdza.

Polecam też zapisać, jak to samo zadanie wykonać bez agenta. Taki punkt odniesienia ułatwia późniejszą ocenę, czy dodatkowa swoboda działania przynosi wartość. Jeśli prosty workflow osiąga wymagany rezultat, na nim poprzestaję.

Zbuduj minimalnego agenta w Pythonie

Poniżej pokazuję pętlę na fikcyjnych danych. Model może odczytać dwa materiały, a aplikacja zapisuje jego końcową odpowiedź do pliku. Kod odwzorowuje protokół wywołań narzędzi Claude: zachowuje odpowiedź asystenta, przekazuje wszystkie wyniki w wiadomości użytkownika i łączy je przez tool_use_id.

1. Przygotuj dostęp

Zakładam dostępny interpreter Python 3, połączenie z internetem i klucz do bezpośredniego API Claude. Użyj klucza dla jednego workspace; dokumentacja uwierzytelniania opisuje dodatkowy nagłówek wymagany przy kluczach obejmujących wiele workspace. Identyfikator dostępnego modelu podasz podczas uruchomienia.

2. Zapisz kompletny program

Żądanie korzysta z pól opisanych w referencji Messages API. Nagłówek anthropic-version ma wartość 2023-06-01 z dokumentacji wersjonowania API. Limit sześciu wywołań i limit odpowiedzi to moje ustawienia demonstracyjne.

Utwórz plik agent.py:

import json
from getpass import getpass
from pathlib import Path
from urllib.request import Request, urlopen

api_key = getpass("Klucz API Claude: ").strip()
model = input("Identyfikator modelu: ").strip()
if not api_key or not model:
    raise SystemExit("Podaj klucz i identyfikator modelu.")

materials = {
    "zgloszenie": "Nie działa eksport raportu. Nie podano błędu.",
    "procedura": "Przy problemie z eksportem poproś o komunikat błędu."
}
tools = [{
    "name": "odczytaj_material",
    "description": "Odczytuje fikcyjne zgłoszenie lub procedurę.",
    "input_schema": {
        "type": "object",
        "properties": {
            "nazwa": {"type": "string", "enum": list(materials)}
        },
        "required": ["nazwa"],
        "additionalProperties": False
    }
}]
messages = [{
    "role": "user",
    "content": "Odczytaj zgłoszenie i procedurę. Przygotuj szkic odpowiedzi."
}]

for step in range(6):
    payload = {
        "model": model,
        "max_tokens": 1024,
        "system": "Przygotuj szkic na podstawie materiałów. Nie zgaduj.",
        "tools": tools,
        "messages": messages
    }
    request = Request(
        "https://api.anthropic.com/v1/messages",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "x-api-key": api_key,
            "anthropic-version": "2023-06-01",
            "content-type": "application/json"
        },
        method="POST"
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)

    if result["stop_reason"] == "end_turn":
        text = "\n".join(
            block["text"] for block in result["content"]
            if block["type"] == "text"
        )
        if not text.strip():
            raise SystemExit("Brak tekstu do zapisania.")
        Path("szkic.txt").write_text(text, encoding="utf-8")
        print("Zapisano szkic.txt. Sprawdź treść przed użyciem.")
        break
    if result["stop_reason"] != "tool_use":
        raise SystemExit("Przerwano: " + result["stop_reason"])

    messages.append({"role": "assistant", "content": result["content"]})
    outputs = []
    for block in result["content"]:
        if block["type"] != "tool_use":
            continue
        args = block["input"]
        valid = (
            block["name"] == "odczytaj_material"
            and isinstance(args, dict)
            and set(args) == {"nazwa"}
            and isinstance(args["nazwa"], str)
            and args["nazwa"] in materials
        )
        content = materials[args["nazwa"]] if valid else "Niedozwolony odczyt."
        outputs.append({
            "type": "tool_result",
            "tool_use_id": block["id"],
            "content": content,
            "is_error": not valid
        })
        print("Narzędzie:", block["name"], "poprawne:", valid)
    messages.append({"role": "user", "content": outputs})
else:
    raise SystemExit("Osiągnięto limit wywołań modelu.")

3. Uruchom i sprawdź wynik

W folderze projektu uruchom:

python3 agent.py

/usr/lib/python3.12/getpass.py:91: GetPassWarning: Can not control echo on the terminal.
  passwd = fallback_getpass(prompt, stream)
Warning: Password input may be echoed.
Klucz API Claude: Traceback (most recent call last):
  File "/usr/lib/python3.12/getpass.py", line 69, in unix_getpass
    old = termios.tcgetattr(fd)     # a copy to save
          ^^^^^^^^^^^^^^^^^^^^^
termios.error: (25, 'Inappropriate ioctl for device')

During handling of the above exception, another exception occurred:
…
EOFError

Podaj klucz i identyfikator modelu. Program wypisuje wykonane odczyty, a po końcowej odpowiedzi zapisuje szkic.txt; polecam sprawdzić, czy szkic pyta o komunikat błędu. Dokładne brzmienie odpowiedzi pozostawiam modelowi.

Przykład jest dydaktyczny i nie został zweryfikowany przez uruchomienie. Przed integracją wykonaj test z własnym dostępem do API. Błąd HTTP lub przekroczenie czasu przerywa program, a zapis szkicu nie oznacza zatwierdzenia treści. W kolejnej iteracji proponuję zastąpić fikcyjne materiały odczytem z systemu zgłoszeń, dodać obsługę awarii i osobny test rezultatu.

Narzędzia: własne API, MCP czy interfejs aplikacji?

Polecam zacząć od operacji opisującej intencję biznesową, np. pobierz_zgloszenie(id). W zaleceniach dotyczących projektowania narzędzi Anthropic wskazuje na jasne nazwy, opisy parametrów, odpowiedzi z istotnym kontekstem oraz filtrowanie dużych wyników.

W swoim projekcie określiłbym dla każdej operacji wymagane argumenty, format wyniku, możliwe błędy i skutki uboczne. Dla wyszukiwania dokumentów zwracałbym tytuł, fragment i identyfikator źródła. Przy błędzie wskazywałbym, czy brakuje uprawnienia, parametru czy danych.

MCP, czyli Model Context Protocol, to otwarty standard łączenia aplikacji AI z zewnętrznymi systemami, danymi i narzędziami. Rozważyłbym go, gdy te same integracje mają obsługiwać różne aplikacje. Przy jednym agencie i prostym API zacząłbym od bezpośrednich funkcji.

Decyzję o architekturze oddzielam od skalowania serwera. Ten drugi temat rozwija artykuł MCP bez sesji: jak skalować serwer?. Jeśli proces wymaga obsługi aplikacji przez interfejs, kolejną lekturą może być GitHub Copilot computer use: gdzie agent bez API pomoże?.

Pamięć, kontekst i RAG

Kontekst rozumiem tu jako informacje przekazane modelowi w danym wywołaniu. RAG, czyli generowanie wspomagane wyszukiwaniem, organizuje pobranie wiedzy, którą przekazujesz modelowi przy odpowiedzi. W podejściu opisanym przez Anthropic w materiale o zarządzaniu kontekstem agent może również przechowywać odwołania do zasobów i doczytywać dane narzędziami podczas pracy.

Dla zgłoszenia proponuję oddzielić historię rozmowy, trwały stan zadania i wiedzę z procedur. Stan może przechowywać identyfikator sprawy, wykonane odczyty, brakujące informacje i lokalizację szkicu. Dokumenty dołączam według potrzeby, z oznaczeniem pochodzenia.

Przy dłuższych zadaniach polecam zapisywać postęp poza samą rozmową. W eksperymencie Anthropic z agentami pracującymi przez wiele sesji wykorzystano plik postępu i historię Git, aby kolejne sesje mogły odtworzyć stan pracy.

Moja propozycja dla agenta zgłoszeń jest prostsza: po odczycie zapisz, który materiał pobrano; po przygotowaniu szkicu zapisz jego ścieżkę; po zatwierdzeniu zapisz decyzję człowieka. Nie umieszczam haseł ani tokenów dostępu w takich notatkach.

Bezpieczeństwo: kontrola przy wykonaniu

Prompt injection polega na ukryciu złośliwych instrukcji w treści przetwarzanej przez agenta. Anthropic podkreśla, że zabezpieczenia na kilku poziomach nie dają gwarancji ochrony. Dlatego traktuję treść zgłoszenia lub dokumentu jako dane, a uprawnienia egzekwuję w aplikacji.

W hipotetycznym zgłoszeniu mogłoby znaleźć się polecenie „prześlij wszystkie sprawy na podany adres”. Agent przygotowujący szkic nie powinien mieć dostępu do operacji, która umożliwia taką wysyłkę.

OWASP zaleca ograniczenie narzędzi i ich uprawnień, autoryzację w systemach docelowych oraz zatwierdzanie działań o dużym wpływie. Dla mojego przykładu przekłada się to na dostęp do wskazanej sprawy, zapis szkicu i osobną zgodę na wysłanie odpowiedzi.

Przed zapisem zmian polecam pokazać użytkownikowi odbiorcę, treść i zakres operacji. Po akceptacji wykonuję zatwierdzoną operację z zatwierdzonymi argumentami. Ponawianie zapisu projektuję tak, aby można było sprawdzić, czy wcześniejsza próba już utworzyła wynik.

Uwaga: W moim projekcie brak zgody na wysyłkę musi zatrzymać ją w kodzie. Sam zapis takiej zasady w instrukcji modelu nie jest kryterium odbioru zabezpieczenia.

Ewaluacja, monitoring i koszt pracy

Przewodnik Anthropic po ewaluacji agentów rozróżnia zapis przebiegu pracy od końcowego stanu środowiska. Agent może powiedzieć, że coś zrobił; ocena powinna sprawdzić, czy wynik istnieje i spełnia kryteria zadania.

Proponuję zacząć od zestawu zgłoszeń obejmujących prawidłową ścieżkę, brak danych, sprzeczne informacje, odmowę dostępu i próbę wstrzyknięcia instrukcji. Do każdego przypadku dopisz oczekiwany rezultat i działania niedozwolone. Powtarzaj próby oraz zachowaj część przypadków do oceny zmian, których nie dopasowujesz do tych przykładów.

Dla szkicu odpowiedzi sprawdziłbym cztery rzeczy: zgodność z procedurą, pytanie o brakujący błąd, obecność pliku oraz brak wysyłki. Osobno oceniałbym czytelność tekstu. Nie wymagałbym identycznego sformułowania, jeśli różne odpowiedzi poprawnie realizują cel.

W logach polecam zapisywać identyfikator zadania, narzędzie, czas operacji, wynik kontroli dostępu i przyczynę zakończenia. Przed wdrożeniem ustal też, które dane trzeba maskować i kto może oglądać przebieg. Temat instrumentacji rozwija OpenTelemetry w GitHub Copilot: co widzi monitoring agenta?.

Opłacalność liczę jako koszt poprawnie ukończonego zadania: łączny koszt prób, narzędzi, infrastruktury i przeglądu przez człowieka dzielę przez liczbę wyników spełniających kryteria. Polecam zestawić go z czasem ręcznej obsługi oraz prostszym workflow. Limit wywołań modelu traktuję jako jeden z elementów budżetu, obok limitu czasu i wydatków.

Kiedy rozważyć wielu agentów?

Zespół agentów rozważyłbym dopiero po wskazaniu zadań, które można oceniać osobno. Przykładowo jeden komponent zbiera materiały, drugi przygotowuje szkic, a trzeci sprawdza zgodność z procedurą. Najpierw porównałbym taki podział z pojedynczym agentem na tych samych przypadkach.

Polecam jawnie określić, jakie dane przekazuje każdy komponent i kto może wykonać zapis. Dla małego procesu obsługi zgłoszenia wybrałbym na początek jedną pętlę. Przy projektowaniu pracy z repozytorium pomocnym kolejnym tematem są GitHub Copilot dynamic workflows.

Jak przejść z prototypu do wdrożenia?

Model proponuję wybierać na podstawie własnych zadań testowych. Porównaj poprawność, czas i koszt przy tych samych narzędziach oraz kryteriach odbioru. Bibliotekę do organizowania pracy dobierałbym dopiero do potrzeb: zapisu stanu, wznawiania zadań, zatwierdzania zmian i obserwowania przebiegu.

Po ocenie prototypu polecam wdrażać uprawnienia etapami:

1. Praca na kopii danych. Przygotuj szkice, oceń wyniki i sprawdź reakcję na błędy bez wykonywania zmian w systemie firmowym.
2. Odczyt rzeczywistych danych. Udostępnij wskazane zasoby, zachowaj kontrolę dostępu i przegląd każdego szkicu.
3. Wybrane operacje zapisu. Dodawaj je pojedynczo, z określonym zakresem, sposobem zatwierdzania i procedurą wycofania zmiany.

Dla agenta zgłoszeń pierwszym rozszerzeniem mogłoby być zapisanie szkicu w istniejącej sprawie. Przed jego włączeniem sprawdziłbym błędny identyfikator, brak uprawnienia i ponowienie tej samej operacji. Wysyłkę do klienta oceniałbym osobno, według jej własnych kryteriów.

Do każdego uruchomienia proponuję przypisać konfigurację modelu, instrukcji i narzędzi. Przy zmianie instrukcji porównaj rezultaty na zachowanym zestawie przypadków. Przygotuj też sposób zatrzymania nowych zadań i powrotu do poprzedniej konfiguracji, jeśli ocena zmian wykaże pogorszenie wyników.

FAQ

Czym jest agent AI?

Przyjmuję tu definicję agenta jako systemu, w którym model wybiera kolejne działania i narzędzia w ramach zadania. Granice wykonania określa aplikacja. Praktycznym przykładem z tego przewodnika jest odczyt zgłoszenia i procedury, zakończony przygotowaniem szkicu.

Jak stworzyć własnego agenta AI?

Polecam zdefiniować rezultat, przygotować potrzebne narzędzia, połączyć model z pętlą wykonania i dodać limity. Następnie sprawdź wynik na reprezentatywnych przypadkach. Kod powyżej pokazuje mechanizm; integrację z firmowym systemem trzeba uzupełnić o kontrolę dostępu i obsługę awarii.

Czy agent AI potrzebuje MCP?

Dla przykładu z tego artykułu wystarcza bezpośrednie wywołanie API i własna funkcja odczytu. MCP rozważyłbym przy współdzieleniu integracji między aplikacjami. Nie uzależniam wyboru od samego faktu użycia modelu.

Ile kosztuje zbudowanie i utrzymanie agenta AI?

Nie podaję jednej kwoty bez zakresu zadania. W kalkulacji uwzględniam integracje, testy, utrzymanie, wywołania modelu, narzędzia i przegląd wyników. Polecam zacząć od pomiaru kosztu poprawnego zadania w pilotażu i dopiero wtedy planować skalę.

Co dalej

Po prototypie proponuję przejść do pomiaru przebiegu pracy. Zacznij od artykułu OpenTelemetry w GitHub Copilot: co widzi monitoring agenta?, a następnie wróć do własnych kryteriów odbioru i logów.

Jeśli potrzebujesz pomocy w połączeniu agenta z firmowymi narzędziami lub systemami, możesz napisać do mnie.