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 i ich dopasowanie do VPS

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

Pierwszym sposobem jest użycie własnego kodu wywołującego Claude API za pomocą własnych narzędzi. Użytkownik samodzielnie pisze 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 bardzo dobrym rozwiązaniem dla VPS, jeśli potrzebny jest wydajny agent operujący na plikach i powłoce bez konieczności samodzielnego tworzenia całego środowiska. Agent, który odczytuje pliki i wykonuje polecenia powłoki, wymaga zabezpieczeń przed pracą bez nadzoru, a bezpieczne uruchamianie Claude Code na serwerze omawia system uprawnień, piaskownicę (sandbox) oraz opcje izolacji.

Trzecim sposobem są Managed Agents, gdzie Anthropic zarządza pętlą i hostuje piaskownicę, w której wykonywane są narzędzia agenta. Jest to opcja niewymagająca obsługi: użytkownik ma znacznie mniej pracy operacyjnej, ale obszar roboczy agenta znajduje się w infrastrukturze Anthropic, a nie na VPS. Należy wybrać to rozwiązanie, gdy priorytetem jest minimalizacja pracy operacyjnej i nie ma potrzeby, aby narzędzia działały na własnej maszynie. W przypadku dwóch pozostałych metod, serwer użytkownika jest domem dla agenta, co stanowi główny temat 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

Claude występuje w kilku wariantach, a wybór konkretnego modelu stanowi kompromis między możliwościami, szybkością a kosztem. W chwili pisania tego tekstu głównymi opcjami są: Claude Opus 4.8 (claude-opus-4-8) – wydajny standard do złożonego wnioskowania i długotrwałych zadań typu agent; Claude Sonnet 5 (claude-sonnet-5) – zbalansowana opcja, tańsza i szybsza, utrzymująca zbliżony do Opus poziom w wielu zadaniach; oraz Claude Haiku 4.5 (claude-haiku-4-5) – najszybszy i najtańszy model, przeznaczony do prostych zadań o dużej skali. Powyżej nich znajduje się Claude Fable 5 (claude-fable-5) – najbardziej zaawansowany model, przeznaczony do najbardziej wymagających prac. W kodzie należy używać dokładnego identyfikatora modelu, bez dodawania daty.

Praktycznym podejściem jest łączenie modeli. Warto pozwolić tańszemu modelowi obsługiwać rutynowe wywołania narzędzi, a silniejszemu podejmować kluczowe decyzje. Ponieważ model jest definiowany jedynie jako ciąg znaków w żądaniu, zmiana wymaga modyfikacji tylko jednej linii kodu. Należy zacząć od wydajnego modelu domyślnego, a następnie optymalizować w dół tam, gdzie 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 w sposób ciągły, a bezpieczny tylko wtedy, gdy jest odizolowany. Na serwerze VPS oba te warunki spełnia uruchomienie agenta jako zabezpieczonej usługi systemowej, zamiast ręcznego uruchamiania programu w terminalu. Jako usługa, agent uruchamia się wraz z systemem, restartuje w razie awarii i zapisuje logi w journal. W ramach zabezpieczeń działa jako użytkownik bez uprawnień administracyjnych, mając dostęp tylko do niezbędnych zasobów, co ogranicza skutki ewentualnych błędów lub niepożądanych instrukcji. Jednostka usługi może jedynie ograniczyć zakres dostępu procesu, dlatego reszta zabezpieczeń musi znajdować się w samym mechanizmie agenta. Jest to zadanie, które realizują wtyczki DeepSeek Harness warte zainstalowania na innym stosie: limity wydatków, reguły uprawnień dla poszczególnych narzędzi oraz skanowanie 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 powinien znajdować się w pliku dostępnym do odczytu tylko dla użytkownika agenta, ładowanym do usługi jako zmienna środowiskowa. Nigdy nie należy umieszczać go w kodzie, repozytorium ani w miejscu dostępnym z poziomu przeglądarki. Wygeneruj kompletną, zabezpieczoną jednostkę usługi dla swojego agenta tutaj:

Następnie dokończ konfigurację serwera. Ogranicz dostęp SSH wyłącznie do kluczy i zabezpiecz konto, z którego zarządzasz serwerem, zgodnie z instrukcją zabezpieczanie SSH na VPS. Jeśli podczas budowania agenta wolisz korzystać z sesji interaktywnej, pomocny będzie przewodnik uruchamianie Claude Code na VPS z użyciem tmux. Gdy otworzysz drugą sesję na tej samej maszynie, obie mogą wymieniać się pracą, zamiast ręcznego przenoszenia każdej instrukcji między oknami. Jeśli interesują Cię koncepcje stojące za tymi rozwiązaniami, niezależnie od konkretnego modelu, przewodnik budowanie własnego agenta AI na VPS przedstawia niezbędne podstawy.

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

FAQ

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

Należy zacząć od Claude Opus 4.8 (claude-opus-4-8), który jest wydajnym modelem domyślnym, a następnie dostosować 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) oferuje największe możliwości w najtrudniejszych zadaniach. Częstą praktyką jest stosowanie tańszego modelu do rutynowych kroków i silniejszego do podejmowania kluczowych decyzji, ponieważ zmiana modelu wymaga jedynie modyfikacji jednej linii kodu.

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

Zależy to od przyjętego podejścia. W przypadku samodzielnego napisania pętli obsługującej 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 uruchamia pętlę i udostępnia środowisko piaskownicy (sandbox), w którym wykonywane są narzędzia, więc mniejsza część logiki znajduje się na Twoim serwerze. Do uruchomienia agenta na własnej maszynie należy wybrać jedną z dwóch pierwszych opcji.

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

Claude API to surowy punkt końcowy Messages: wysyłasz konwersację oraz definicje narzędzi 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 zawiera gotową pętlę oraz wbudowane narzędzia do obsługi plików, powłoki i wyszukiwania. Użyj API, gdy chcesz samodzielnie zdefiniować wszystkie elementy, a Agent SDK, gdy potrzebujesz sprawnego agenta bez konieczności budowania całego szkieletu od podstaw.

Jak bezpiecznie przechowywać klucz Claude API na serwerze?

Klucz musi pozostać po stronie serwera i poza kodem źródłowym. Przechowuj go w pliku dostępnym tylko dla konta, na którym działa agent, ładuj do usługi jako zmienną środowiskową i nigdy nie umieszczaj w repozytorium ani nie udostępniaj w przeglądarce. Ponieważ każde żądanie do Claude wychodzi z Twojego 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 do budowy agenta z Claude muszę samodzielnie hostować model?

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 oraz dane, natomiast proces wnioskowania odbywa się po stronie Anthropic. Dzięki temu nawet skromny serwer może obsługiwać zaawansowanego agenta. Jeśli natomiast potrzebujesz modelu w pełni lokalnego, jest to ścieżka samodzielnego hostingu, opisana w przewodniku towarzyszącym dotyczącym budowy własnego agenta AI.