Jak zbudować agenta AI z Claude na VPS

Co oznacza budowa agenta przy użyciu Claude

Budowa agenta przy użyciu Claude oznacza wykorzystanie Claude jako rdzenia rozumującego, podczas gdy pętla, narzędzia oraz dane znajdują się na własnym serwerze. Claude podejmuje decyzje, a VPS wykonuje polecenia. Użytkownik wysyła do Claude zadanie oraz aktualny stan, a Claude odpowiada wynikiem lub prośbą o użycie jednego z narzędzi. Kod wykonuje narzędzie i odsyła wynik, a pętla trwa do zakończenia zadania. Inteligencja jest usługą wywoływaną przez internet. Cała reszta infrastruktury należy do użytkownika.

Ten podział stanowi główną zaletę. Zyskują Państwo rozumowanie na poziomie frontier bez konieczności obsługi modelu, zachowując pełną kontrolę nad tym, do czego agent ma dostęp, ponieważ narzędzia działają na własnym sprzęcie. Jeśli stworzono już pierwszy program z Claude, poradnik first Claude app on a VPS guide opisuje podstawy niezbędne do budowy tego rozwiązania.

Claude jako mózg: Messages API

Każde wywołanie Claude odbywa się poprzez jeden punkt końcowy: Messages API. Wysyłana jest dotychczasowa konwersacja oraz lista narzędzi dostępnych dla agenta; Claude zwraca kolejną wiadomość. Wiadomość ta jest albo ostateczną odpowiedzią, albo prośbą o wywołanie narzędzia. W przypadku podejścia typu "build-it-yourself" nie istnieje osobne "agent API": używanie narzędzi jest funkcją tego samego punktu końcowego, a pętla sterująca należy do użytkownika.

Claude jest bezstanowy (stateless) między wywołaniami, co oznacza, że nie przechowuje żadnych informacji samodzielnie. Każde żądanie zawiera całą historię konwersacji. Kod przechowuje historię i przesyła ją w każdej iteracji, co sprawia, że każda iteracja w długiej sesji kosztuje więcej tokenów niż poprzednia. Nie jest to ograniczenie, lecz wybór projektowy: ponieważ stan znajduje się na serwerze użytkownika, można dokładnie zdecydować, co widzi Claude, a żadne dane dotyczące zadania nie są przechowywane poza kontrolowaną przez użytkownika przestrzenią.

Używanie narzędzi jako pętla agenta

Pętlę agenta z Claude opisuje się prosto. Wysyłane jest żądanie zawierające narzędzia. Claude analizuje zadanie i, jeśli wymaga podjęcia działania, odpowiada prośbą o użycie narzędzia, podając jego nazwę oraz parametry wejściowe. Kod wykonuje to narzędzie, a następnie przesyła wynik do Claude w kolejnym żądaniu. Claude analizuje wynik i albo prosi o kolejne narzędzie, albo generuje ostateczną odpowiedź. Po zaprzestaniu próśb o narzędzia zadanie zostaje ukończone.

Pętlę tę można napisać ręcznie w kilku liniach, co jest powszechną praktyką ze względu na łatwość kontroli i przejrzystość. Oficjalne SDK udostępniają również mechanizm tool runner, który automatyzuje pętlę: użytkownik dostarcza funkcje narzędzi, a SDK zarządza komunikacją z Claude, wykonywaniem narzędzi i przesyłaniem wyników aż do zakończenia pracy przez Claude. W obu przypadkach struktura pozostaje taka sama; runner jedynie eliminuje konieczność ręcznego pisania pętli.

Trzy sposoby budowy i ich przydatność dla VPS

Istnieją trzy sposoby budowy agenta Claude, różniące się zakresem zarządzanej infrastruktury.

Pierwszy to własny kod wywołujący Claude API wraz z własnymi narzędziami. Użytkownik pisze pętlę lub korzysta z tool runnera w SDK i hostuje całość na VPS. Jest to najczęstszy wybór, ponieważ zapewnia pełną kontrolę nad narzędziami, danymi i bezpieczeństwem, a agent działa jako zwykły program na serwerze. Większość tej instrukcji zakłada właśnie to podejście.

Drugi sposób to Claude Agent SDK. Jest to Claude Code (agent programistyczny) dostarczony jako biblioteka. Zawiera on pełną pętlę agenta oraz wbudowane narzędzia do odczytu i zapisu plików, wykonywania poleceń shell oraz przeszukiwania, co eliminuje konieczność budowania ich od podstaw. Rozwiązanie to działa na własnym serwerze, co czyni je idealnym dla VPS w przypadku potrzeby posiadania sprawnego agenta plików i shell bez budowania własnego mechanizmu sterującego. Agent czytający pliki i wykonujący polecenia shell wymaga izolacji przed pracą w trybie autonomicznym; poradnik running Claude Code safely on a server opisuje system uprawnień, piaskownicę (sandbox) oraz opcje izolacji.

Trzeci sposób to Managed Agents, gdzie Anthropic zarządza pętlą i hostuje piaskownicę, w której wykonują się narzędzia agenta. Jest to opcja bezobsługowa: wymaga znacznie mniej pracy operacyjnej, ale środowisko pracy agenta znajduje się na infrastrukturze Anthropic, a nie na VPS. Należy z niej skorzystać, gdy wymagana jest minimalna obsługa operacyjna, a narzędzia nie muszą działać na własnym sprzęcie. W dwóch pozostałych przypadkach serwer użytkownika jest domem dla agenta, co stanowi główny temat tej instrukcji.

Łączenie narzędzi za pomocą MCP

Niezależnie od wybranej metody, konieczne będzie połączenie agenta z rzeczywistymi systemami, a Model Context Protocol (MCP) jest do tego optymalnym rozwiązaniem. MCP to otwarty standard udostępniania narzędzi i danych agentowi. Zamiast ręcznie pisać integrację dla każdego serwisu, można wskazać Claude serwer MCP, który już udostępnia te funkcje jako narzędzia. Serwery MCP można uruchamiać jako małe usługi na tym samym VPS, każda z ograniczonym zakresem uprawnień, co opisano w running MCP servers on a VPS.

Wybór modelu

Claude występuje w kilku wersjach, a wybór modelu jest kompromisem między możliwościami, szybkością a kosztem. W momencie pisania tych tekstów głównymi wyborami są: Claude Opus 4.8 (claude-opus-4-8), standardowy wybór do trudnego rozumowania i długich sesji agenta; Claude Sonnet 5 (claude-sonnet-5), opcja zbalansowana, tańsza i szybsza, przy zachowaniu wysokiej wydajności w wielu zadaniach; oraz Claude Haiku 4.5 (claude-haiku-4-5), najszybszy i najtańszy, przeznaczony do prostych, masowych operacji. Najwyżej w hierarchii znajduje się Claude Fable 5 (claude-fable-5), najbardziej zaawansowany model do najbardziej wymagających zadań. W kodzie należy używać dokładnego identyfikatora modelu, bez dodawania daty.

Praktycznym wzorcem jest mieszanie modeli. Tańszy model może obsługiwać rutynowe wywołania narzędzi, natomiast silniejszy może podejmować kluczowe decyzje. Ponieważ model jest definiowany jedynie jako ciąg znaków w żądaniu, zmiana jest prosta i wymaga jednej linii kodu. Zaleca się rozpoczęcie od wydajnego modelu domyślnego i stopniowe obniżanie klasy modelu tam, gdzie szybkość lub koszt są ważniejsze niż najwyższa jakość.

Uruchomienie jako zabezpieczona usługa na VPS

Agent jest użyteczny tylko wtedy, gdy działa nieprzerwanie, i bezpieczny tylko wtedy, gdy jest odizolowany. Na VPS oba te warunki zapewnia uruchomienie agenta jako zabezpieczona usługa systemowa, a nie jako program uruchomiony ręcznie w terminalu. Jako usługa, agent uruchamia się przy starcie systemu, restartuje po awarii i loguje zdarzenia do journala. Po zabezpieczeniu działa jako użytkownik o ograniczonych uprawnieniach, co ogranicza skutki błędów lub błędnych instrukcji.

Najważniejszą zasadą jest przechowywanie klucza API Claude po stronie serwera. Klucz służy do autoryzacji i opłacania każdego wywołania, dlatego powinien znajdować się w pliku dostępnym tylko dla użytkownika agenta, być ładowany do usługi jako zmienna środowiskowa i nigdy nie może znaleźć się w kodzie, w repozytorium ani w miejscu dostępnym przez przeglądarkę. Kompletna, zabezpieczona jednostka usługowa (service unit) dla agenta znajduje się tutaj:

Następnie należy skonfigurować serwer. Należy ograniczyć dostęp SSH wyłącznie do kluczy i zabezpieczyć konto administracyjne, zgodnie z instrukcją SSH hardening on a VPS. Jeśli podczas budowy preferowane jest sterowanie agentem z sesji interaktywnej, pomocny będzie poradnik running Claude Code on a VPS with tmux. Jeśli wymagane są koncepcje leżące u podstaw tych rozwiązań, bez ograniczania ich do jednego modelu, poradnik building your own AI agent on a VPS przedstawia fundamenty.

Jeśli celem jest asystent programistyczny w terminalu, poradnik running a coding AI agent on a VPS opisuje narzędzia Aider oraz Goose.

FAQ

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

Należy zacząć od Claude Opus 4.8 (claude-opus-4-8), który jest wydajnym standardem, a następnie dostosowywać wybór. Claude Sonnet 5 (claude-sonnet-5) jest tańszy i szybszy w większości zadań, Claude Haiku 4.5 (claude-haiku-4-5) najlepiej sprawdza się w prostych, masowych operacjach, a Claude Fable 5 (claude-fable-5) jest najbardziej zaawansowany do najtrudniejszych zadań. Częstym wzorcem jest używanie tańszego modelu do rutynowych kroków, a silniejszego do kluczowych decyzji, ponieważ zmiana modelu wymaga edycji tylko jednej linii kodu.

Czy agent działa w całości na VPS, czy w infrastrukturze Anthropic?

Zależy to od wybranego podejścia. Jeśli użytkownik pisze własną pętlę przy użyciu Claude API lub korzysta z Claude Agent SDK, agent działa w całości na VPS, a do Anthropic wysyłane są jedynie wywołania modelu. W przypadku Managed Agents to Anthropic zarządza pętlą i hostuje piaskownicę, w której wykonują się narzędzia, więc mniej procesów odbywa się na serwerze użytkownika. Aby agent działał 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: użytkownik wysyła konwersację i narzędzia, a następnie samodzielnie implementuje pętlę agenta lub używa tool runnera z SDK. Claude Agent SDK to biblioteka wyższego poziomu (Claude Code), która zawiera pełną pętlę oraz wbudowane narzędzia do plików, shell i wyszukiwania. API należy stosować, gdy wymagana jest pełna kontrola nad każdym elementem, natomiast Agent SDK, gdy potrzebny jest gotowy agent bez konieczności budowania mechanizmu sterującego.

Jak bezpiecznie przechowywać klucz API Claude na serwerze?

Klucz musi znajdować się po stronie serwera, poza kodem źródłowym. Należy go zapisać w pliku dostępnym wyłącznie dla konta, na którym działa agent, załadować jako zmienną środowiskową w usłudze i nigdy nie przesyłać do repozytorium ani nie udostępniać w przeglądarce. Ponieważ każde żądanie do Claude pochodzi z serwera, klucz nie musi trafiać na urządzenie użytkownika, co ułatwia zabezpieczenie agenta działającego na serwerze w porównaniu do aplikacji klienckiej.

Czy do budowy agenta przy użyciu Claude konieczne jest hostowanie własnego modelu?

Nie. W przypadku Claude model jest usługą hostowaną, wywoływaną przez API, więc nie wymaga uruchamiania procesów na GPU. VPS obsługuje pętlę agenta, narzędzia i dane, natomiast proces rozumowania odbywa się po stronie Anthropic. Pozwala to na uruchomienie sprawnego agenta na skromnym serwerze. Jeśli wymagany jest w pełni lokalny model, należy skorzystać z podejścia self-hosted opisanego w poradniku dotyczącym budowy własnego agenta AI.