Jak zbudować własnego agenta AI z Claude na VPS

Co oznacza budowa agenta z wykorzystaniem Claude

Budowa agenta z wykorzystaniem Claude oznacza użycie Claude jako rdzenia wnioskującego, podczas gdy pętla sterująca, narzędzia oraz dane znajdują się na własnym serwerze. Claude podejmuje decyzje o działaniu, a VPS wykonuje zadania. Użytkownik przesyła do Claude zadanie oraz bieżący stan, Claude odpowiada odpowiedzią lub żądaniem użycia jednego z narzędzi, kod wykonuje narzędzie i odsyła wynik, a pętla trwa do momentu zakończenia pracy. Inteligencja jest usługą wywoływaną przez Internet. Cała otoczka należy do użytkownika.

Ten podział stanowi o atrakcyjności rozwiązania. Użytkownik otrzymuje wnioskowanie na poziomie modeli klasy frontier bez konieczności utrzymywania modelu, zachowując pełną kontrolę nad tym, do czego agent ma dostęp, ponieważ narzędzia działają na posiadanym sprzęcie. Jeśli pierwszy program z wykorzystaniem Claude został już stworzony, przewodnik po pierwszej aplikacji Claude na VPS zawiera podstawy, na których opiera się niniejszy materiał.

Claude to mózg operacji: Messages API

Każde wywołanie Claude odbywa się za pośrednictwem jednego punktu końcowego, Messages API. Przesyła się dotychczasowy przebieg konwersacji oraz listę narzędzi, z których agent może skorzystać; Claude odsyła w odpowiedzi swoją kolejną wiadomość. Wiadomość ta stanowi albo ostateczną odpowiedź, albo żądanie wywołania narzędzia. W przypadku samodzielnej implementacji nie istnieje oddzielne "agent API": obsługa narzędzi jest funkcją tego jednego punktu końcowego, a pętla sterująca pozostaje po stronie użytkownika.

Claude jest bezstanowy pomiędzy wywołaniami, co oznacza, że nie przechowuje samodzielnie żadnych informacji. Każde żądanie zawiera pełną historię konwersacji. Kod aplikacji przechowuje historię i przesyła ją w każdej turze, co jest powodem, dla którego każda kolejna tura w długiej sesji zużywa więcej tokenów niż poprzednia. Nie jest to ograniczenie, lecz wybór projektowy: ponieważ stan znajduje się na serwerze użytkownika, to on decyduje, co dokładnie widzi Claude, a żadne dane dotyczące zadania nie są przechowywane w miejscu, nad którym użytkownik nie ma kontroli. Oznacza to, że prompt stale rośnie i choć okno kontekstowe Claude bez problemu to obsługuje, model lokalny w tej samej pętli nie poradzi sobie z tym, dlatego Ollama wymaga zwiększenia parametru num_ctx, zanim przestanie ucinać długie prompty.

Wykorzystanie narzędzi jako pętla agenta

Pętlę agenta z modelem Claude można opisać w prosty sposób. Wysyłasz żądanie zawierające definicje narzędzi. Claude analizuje zadanie i, jeśli wymaga ono podjęcia działania, odpowiada żądaniem użycia narzędzia, wskazując jego nazwę oraz wypełniając wymagane parametry wejściowe. Twój kod wykonuje wskazane narzędzie, a następnie przesyła wynik z powrotem do Claude w kolejnym żądaniu. Claude odczytuje wynik i podejmuje decyzję o wywołaniu kolejnego narzędzia lub sformułowaniu ostatecznej odpowiedzi. Gdy model przestaje żądać użycia narzędzi, zadanie zostaje uznane za zakończone.

Pętlę tę można zaimplementować samodzielnie w kilku liniach kodu, co jest często praktykowane ze względu na przejrzystość i łatwość kontroli procesu. Oficjalne pakiety SDK udostępniają również gotowy mechanizm uruchamiania narzędzi, który automatyzuje działanie pętli: dostarczasz funkcje narzędzi, a SDK zarządza wymianą danych, wywołując Claude, uruchamiając narzędzia i przekazując wyniki z powrotem, aż do momentu zakończenia pracy przez model. W obu przypadkach struktura procesu pozostaje identyczna. Mechanizm uruchamiający jedynie zwalnia z konieczności samodzielnego pisania pętli. Jeśli koncepcja pętli wydaje się abstrakcyjna, najlepszym rozwiązaniem jest napisanie jej minimalnej wersji przed przejściem do gotowych rozwiązań, co stanowi fundament dla dalszych etapów opisanych w tej ścieżce nauki tworzenia agentów AI od podstaw.

Trzy sposoby budowy agenta i ich dopasowanie do VPS

Istnieją trzy sposoby budowy agenta Claude, które różnią się zakresem obsługiwanej infrastruktury.

Pierwszym z nich jest napisanie własnego kodu wywołującego API Claude za pomocą własnych narzędzi. Użytkownik samodzielnie tworzy pętlę lub korzysta z narzędzia uruchomieniowego SDK i hostuje całość na swoim VPS. Jest to najczęstszy wybór, ponieważ zapewnia pełną kontrolę nad narzędziami, danymi i bezpieczeństwem, a całość działa jako zwykły program na serwerze. Większość tego przewodnika zakłada właśnie tę ścieżkę.

Drugim sposobem jest Claude Agent SDK. Jest to Claude Code, czyli agent programistyczny dostarczony w formie biblioteki, na której można budować własne rozwiązania. Zawiera on gotową pętlę agenta oraz wbudowane narzędzia do odczytu i zapisu plików, wykonywania poleceń powłoki oraz wyszukiwania, dzięki czemu nie trzeba ich tworzyć od podstaw. Działa on również na własnym serwerze, co czyni go dobrym rozwiązaniem dla VPS, gdy potrzebny jest wydajny agent operujący na plikach i powłoce bez konieczności samodzielnego tworzenia całego mechanizmu. Agent odczytujący pliki i wykonujący polecenia powłoki wymaga zabezpieczeń przed pracą bez nadzoru, a sekcja bezpieczne uruchamianie Claude Code na serwerze omawia system uprawnień, piaskownicę (sandbox) oraz opcje izolacji.

Trzecim sposobem są Managed Agents, gdzie pętla agenta jest uruchamiana przez Anthropic. Domyślnie narzędzia agenta wykonują się w piaskownicy hostowanej przez Anthropic, więc obszar roboczy agenta znajduje się w infrastrukturze Anthropic, a nie na Twoim VPS. Według stanu na 11 października 2026 r. dostępna jest opcja self-hosted sandbox (w fazie beta), która pozwala procesowi roboczemu na własnym serwerze wykonywać wywołania narzędzi, podczas gdy pętla pozostaje po stronie Anthropic. Z Managed Agents warto korzystać, gdy celem jest minimalizacja nakładu pracy operacyjnej i nie ma potrzeby, aby sama pętla działała na własnej maszynie. W pozostałych dwóch przypadkach serwer jest głównym środowiskiem pracy agenta, co stanowi przedmiot dalszej części tego przewodnika.

Łączenie narzędzi za pomocą MCP

Niezależnie od wybranej ścieżki, konieczne będzie połączenie agenta z rzeczywistymi systemami, a Model Context Protocol stanowi w tym celu uporządkowane rozwiązanie. MCP to otwarty standard udostępniania narzędzi i danych agentowi. Zamiast ręcznie programować integrację dla każdej usługi, należy wskazać Claude serwer MCP, który prezentuje te możliwości jako gotowe narzędzia. Serwery MCP można uruchamiać jako niewielkie usługi na tym samym VPS, z których każda posiada jedynie niezbędne uprawnienia, co zostało opisane w uruchamianie serwerów MCP na VPS.

Wybór modelu

Dostępnych jest kilka modeli Claude, a wybór konkretnego stanowi kompromis między możliwościami, szybkością a kosztem. Według stanu na 11 października 2026 r. aktualna oferta obejmuje Claude Opus 5.5 (claude-opus-5-5), który Anthropic zaleca jako punkt wyjścia dla większości obciążeń oraz zadań związanych z długotrwałym programowaniem agentowym i pracą koncepcyjną; Claude Sonnet 5.5 (claude-sonnet-5-5), opcję zrównoważoną, tańszą i szybszą; oraz Claude Haiku 5.5 (claude-haiku-5-5), najszybszy i najtańszy model przeznaczony do prostych zadań o dużej skali. Powyżej nich znajduje się Claude Fable 5.1 (claude-fable-5-1), najbardziej zaawansowany model dostępny dla wszystkich klientów, przeznaczony do wymagającego wnioskowania i długofalowej pracy agentowej. Starsze modele, takie jak Claude Opus 4.8 oraz Claude Fable 5, są nadal dostępne, ale zostały oznaczone jako starsze wersje (legacy). W kodzie należy używać dokładnego identyfikatora modelu, bez dodawania daty.

Praktycznym wzorcem jest łączenie różnych modeli. Tańszy model może obsługiwać rutynowe wywołania narzędzi, podczas gdy silniejszy model zajmuje się trudnymi decyzjami. Ponieważ model jest definiowany jedynie jako ciąg znaków w żądaniu, zmiana wymaga modyfikacji tylko jednej linii kodu. Warto więc rozpocząć od wydajnego modelu domyślnego i optymalizować go w dół, jeśli szybkość lub koszt są ważniejsze niż najwyższa jakość odpowiedzi.

Uruchomienie jako zabezpieczona usługa na VPS

Agent jest użyteczny tylko wtedy, gdy działa nieprzerwanie, a bezpieczny tylko wtedy, gdy jest odizolowany. Na VPS oba te warunki spełnia uruchomienie agenta jako zabezpieczonej usługi systemowej, zamiast ręcznego uruchamiania programu w terminalu. Jako usługa, agent startuje wraz z systemem, restartuje się w razie awarii i zapisuje logi do journal. W trybie zabezpieczonym działa jako użytkownik bez uprawnień, posiadający tylko niezbędny dostęp, co ogranicza skutki ewentualnego błędu lub wykonania niepożądanej instrukcji. Jednostka usługi może ograniczyć zasoby, do których proces ma dostęp, oraz limity pamięci, CPU i liczby zadań, jednak nie jest w stanie ocenić decyzji podejmowanych przez agenta w ramach tych uprawnień. Reszta zabezpieczeń spoczywa na samym mechanizmie agenta, co jest zadaniem dla wtyczek DeepSeek Harness wartych zainstalowania działających na innym stosie: limitów wydatków, reguł uprawnień dla poszczególnych narzędzi oraz skanowania pod kątem prompt injection.

Najważniejszą zasadą jest przechowywanie klucza API Claude wyłącznie po stronie serwera. Klucz opłaca i autoryzuje każde wywołanie, dlatego musi znajdować się w pliku dostępnym tylko dla użytkownika agenta, ładowanym do usługi jako zmienna środowiskowa i nigdy nieumieszczanym w kodzie, repozytorium ani w miejscu dostępnym z poziomu przeglądarki. Wygeneruj kompletną, zabezpieczoną jednostkę usługi dla swojego agenta tutaj:

Następnie zabezpiecz sam serwer. Używaj wyłącznie kluczy SSH i ogranicz dostęp do konta, z którego zarządzasz systemem, zgodnie z zabezpieczaniem SSH na VPS. Jeśli podczas budowania agenta wolisz korzystać z sesji interaktywnej, uruchomienie Claude Code na VPS z użyciem tmux będzie dobrym rozwiązaniem. Gdy masz otwartą drugą sesję na tej samej maszynie, obie mogą przekazywać sobie pracę, zamiast ręcznego przenoszenia każdej instrukcji między oknami. Jeśli interesują Cię koncepcje stojące za tymi rozwiązaniami, bez przywiązywania się do konkretnego modelu, przewodnik budowanie własnego agenta AI na VPS przedstawia fundamenty.

Jeśli szukasz asystenta programistycznego działającego w terminalu, uruchamianie agenta AI do kodowania na VPS omawia narzędzia Aider i Goose.

FAQ

Którego modelu Claude użyć do budowy agenta?

Należy zacząć od Claude Opus 5.5 (claude-opus-5-5), który Anthropic rekomenduje dla większości obciążeń, a następnie dostosować wybór. Claude Sonnet 5.5 (claude-sonnet-5-5) jest tańszy i szybszy w większości zadań, Claude Haiku 5.5 (claude-haiku-5-5) najlepiej sprawdza się w prostych, masowych operacjach, a Claude Fable 5.1 (claude-fable-5-1) oferuje największe możliwości w najtrudniejszych zadaniach. Często stosowaną praktyką jest używanie tańszego modelu do rutynowych kroków i silniejszego do podejmowania kluczowych decyzji, ponieważ zmiana modelu wymaga modyfikacji tylko jednej linii kodu.

Czy cały agent działa na moim VPS, czy po stronie Anthropic?

Zależy to od wybranego podejścia. W przypadku samodzielnego napisania pętli komunikującej się z Claude API lub użycia Claude Agent SDK, agent działa w całości na VPS, a do Anthropic wysyłane są jedynie zapytania do modelu. Jeśli korzystasz z Managed Agents, Anthropic obsługuje pętlę i domyślnie udostępnia środowisko piaskownicy (sandbox), w którym wykonywane są narzędzia, więc na serwerze działa mniej komponentów. Opcja self-hosted sandbox, dostępna w wersji beta od 11 października 2026, przenosi wykonywanie narzędzi na własną maszynę, podczas gdy pętla pozostaje po stronie Anthropic. Aby agent działał w całości na własnym sprzęcie, należy wybrać jedną z dwóch pierwszych metod.

Jaka jest różnica między Claude API a Claude Agent SDK?

Claude API to surowy punkt końcowy Messages: wysyłasz konwersację oraz narzędzia i samodzielnie tworzysz pętlę agenta lub używasz mechanizmu uruchamiania narzędzi z SDK. Claude Agent SDK to biblioteka wyższego poziomu, czyli Claude Code przygotowany do rozbudowy, który dostarcza gotową pętlę oraz wbudowane narzędzia do obsługi plików, powłoki i wyszukiwania. Użyj API, jeśli chcesz samodzielnie zdefiniować wszystkie elementy, a Claude Agent SDK, jeśli potrzebujesz sprawnego agenta bez konieczności budowania całego szkieletu od podstaw.

Jak bezpiecznie przechowywać klucz Claude API na serwerze?

Klucz musi znajdować się po stronie serwera i poza kodem źródłowym. Należy przechowywać go w pliku dostępnym tylko dla konta, na którym działa agent, wczytywać do usługi jako zmienną środowiskową i nigdy nie umieszczać w repozytorium ani nie udostępniać w przeglądarce. Ponieważ każde żądanie do Claude wychodzi z serwera, klucz nigdy nie trafia na urządzenie użytkownika, co sprawia, że agent działający na serwerze jest łatwiejszy do zabezpieczenia niż ten osadzony w aplikacji klienckiej.

Czy muszę hostować model samodzielnie, aby zbudować agenta z Claude?

Nie. W przypadku Claude model jest usługą hostowaną, z którą łączysz się przez API, więc nie ma potrzeby uruchamiania niczego na GPU. Twój VPS obsługuje pętlę agenta, narzędzia i dane, natomiast proces wnioskowania odbywa się po stronie Anthropic. Dzięki temu nawet skromny serwer może obsługiwać zaawansowanego agenta. Jeśli wymagany jest w pełni lokalny model, należy wybrać ścieżkę self-hosted, opisaną w przewodniku towarzyszącym dotyczącym budowy własnego agenta AI.