AI agent bouwen met Claude op een VPS

Wat het bouwen van een agent met Claude inhoudt

Het bouwen van een agent met Claude betekent dat u Claude gebruikt als de kern voor redeneringen, terwijl de lus, de tools en de data op uw eigen server staan. Claude bepaalt wat er moet gebeuren; uw VPS voert dit uit. U stuurt de taak en de huidige status naar Claude, Claude antwoordt met een antwoord of een verzoek om een van uw tools te gebruiken, uw code voert de tool uit en stuurt het resultaat terug, en de lus gaat door totdat de taak is voltooid. De intelligentie is een dienst die u via internet aanroept. Alles daaromheen is van u.

Deze scheiding is de kracht ervan. U beschikt over redeneervermogen van topniveau zonder zelf een model te hoeven draaien, en u behoudt volledige controle over waar de agent toegang toe heeft, omdat de tools op hardware draaien die uw eigendom is. Als u al een eerste Claude-programma heeft gebouwd, behandelt de handleiding voor de eerste Claude-app op een VPS de basis waarop dit artikel voortbouwt.

Claude is het brein: de Messages API

Elke aanroep naar Claude verloopt via één endpoint, de Messages API. U verstuurt het gesprek tot dusver en de lijst met tools die de agent mag gebruiken; Claude stuurt zijn volgende bericht terug. Dat bericht is ofwel een definitief antwoord, ofwel een verzoek om een tool aan te roepen. Voor de zelfbouw-methode bestaat er geen afzonderlijke "agent API": toolgebruik is een functionaliteit van dit ene endpoint, en de lus daaromheen moet u zelf beheren.

Claude is stateless tussen aanroepen, wat betekent dat het uit zichzelf niets onthoudt. Elk verzoek bevat het volledige gesprek. Uw code houdt de geschiedenis bij en verstuurt deze bij elke beurt, wat de reden is waarom elke beurt in een lange sessie meer tokens kost dan de vorige. Dat is minder een beperking dan een ontwerpkeuze: omdat de status op uw server leeft, bepaalt u precies wat Claude ziet, en wordt er niets over de taak opgeslagen op een plek waar u geen controle over heeft. Het betekent wel dat de prompt blijft groeien, en hoewel het contextvenster van Claude dat comfortabel opvangt, zal een lokaal model in dezelfde lus dat niet doen. Dat is waarom Ollama num_ctx moet worden verhoogd voordat het stopt met het afkappen van lange prompts.

Het gebruik van tools is de agent-loop

De agent-loop met Claude is eenvoudig te beschrijven. U verstuurt een verzoek waarin uw tools zijn opgenomen. Claude leest de taak en, indien actie vereist is, antwoordt met een verzoek om een tool te gebruiken, waarbij de naam van de tool en de bijbehorende invoer worden gespecificeerd. Uw code voert die tool uit en stuurt het resultaat vervolgens in het volgende verzoek terug naar Claude. Claude leest het resultaat en vraagt ofwel om een andere tool, of schrijft het definitieve antwoord. Wanneer er niet langer om tools wordt gevraagd, is de taak voltooid.

U kunt deze loop handmatig in enkele regels schrijven, wat veel mensen ook doen, omdat het proces inzichtelijk en eenvoudig te controleren is. De officiële SDK's bieden ook een tool runner die de loop voor u aanstuurt: u levert de tool-functies aan, en de SDK regelt de interactie door Claude aan te roepen, uw tools uit te voeren en de resultaten terug te koppelen totdat Claude klaar is. In beide gevallen is de structuur identiek. De runner bespaart u enkel het zelf schrijven van de loop. Als de loop nog abstract aanvoelt, is de oplossing om een minimale versie te schrijven voordat u een runner gebruikt; dit is de stap waar alles in dit stapsgewijze pad voor het vanaf nul leren bouwen van AI-agents op voortbouwt.

Drie manieren om te bouwen, en welke geschikt zijn voor een VPS

Er zijn drie manieren om een Claude-agent te bouwen, en ze verschillen in de hoeveelheid infrastructuur die u zelf beheert.

De eerste is uw eigen code die de Claude API aanroept met uw eigen tools. U schrijft de loop, of gebruikt de tool runner van de SDK, en u host het geheel op uw VPS. Dit is de meest gekozen optie, omdat u hiermee volledige controle heeft over de tools, de data en de beveiliging, en het draait als een standaard programma op uw server. Het grootste deel van deze handleiding gaat uit van deze aanpak.

De tweede is de Claude Agent SDK. Dit is Claude Code, de coding agent, verpakt als een bibliotheek waarop u kunt voortbouwen. Het bevat een volledige agent-loop en ingebouwde tools voor het lezen en schrijven van bestanden, het uitvoeren van shell-commando's en het zoeken, zodat u deze niet vanaf nul hoeft samen te stellen. Het draait ook op uw eigen server, wat het zeer geschikt maakt voor een VPS wanneer u een capabele file-and-shell agent wilt zonder zelf de infrastructuur te hoeven bouwen. Een agent die bestanden leest en shell-commando's uitvoert, heeft beveiliging nodig voordat deze onbeheerd kan werken, en veilig draaien van Claude Code op een server behandelt het permissiesysteem, de sandbox en de isolatie-opties.

De derde is Managed Agents, waarbij Anthropic de loop beheert en een sandbox host waarin de tools van de agent worden uitgevoerd. Dit is de hands-off optie: u hoeft veel minder te beheren, maar de werkomgeving van de agent bevindt zich op de infrastructuur van Anthropic in plaats van op uw VPS. Kies hiervoor wanneer u zo min mogelijk operationeel werk wilt en de tools niet op uw eigen machine hoeven te draaien. Voor de andere twee opties is uw server de thuisbasis van de agent, en daar gaat de rest van deze handleiding over.

Tools verbinden met MCP

Welk pad u ook kiest, u zult de agent willen verbinden met echte systemen, en het Model Context Protocol is de gestructureerde manier om dit te doen. MCP is een open standaard voor het ontsluiten van tools en data aan een agent. In plaats van voor elke service handmatig een integratie te schrijven, wijst u Claude naar een MCP-server die deze mogelijkheden al als tools aanbiedt. U kunt MCP-servers draaien als kleine services op dezelfde VPS, elk met alleen de toegang die nodig is, wat ik behandel in het draaien van MCP-servers op een VPS.

Het kiezen van een model

Claude is beschikbaar in verschillende modellen, waarbij de keuze een afweging is tussen capaciteit, snelheid en kosten. Op het moment van schrijven zijn de gangbare keuzes Claude Opus 4.8 (claude-opus-4-8), de capabele standaard voor complexe redeneringen en langdurige agent-taken; Claude Sonnet 5 (claude-sonnet-5), een gebalanceerde optie die goedkoper en sneller is terwijl deze voor veel taken dicht bij Opus blijft; en Claude Haiku 4.5 (claude-haiku-4-5), de snelste en goedkoopste optie voor eenvoudige stappen met een hoog volume. Daarboven staat Claude Fable 5 (claude-fable-5), het meest capabele model voor de meest veeleisende werkzaamheden. Gebruik de exacte model-identifier in uw code, zonder toevoeging van een datum.

Een praktische werkwijze is om deze modellen te combineren. Laat een goedkoper model routinematige tool-aanroepen afhandelen en een sterker model de lastige beslissingen nemen. Omdat het model slechts een string in uw verzoek is, is het wisselen een wijziging van één regel. Begin daarom met een capabele standaard en schaal af waar snelheid of kosten belangrijker zijn dan de laatste procenten aan kwaliteit.

Draai het als een beveiligde service op uw VPS

Een agent is alleen nuttig als deze blijft draaien, en is alleen veilig als deze is ingesloten. Op een VPS bereikt u beide door de agent als een beveiligde systeemservice te draaien in plaats van als een programma dat u handmatig in een terminal start. Als service start het programma bij het opstarten, herstart het bij een crash en schrijft het logs naar de journal. In de beveiligde modus draait het als een gebruiker zonder privileges met alleen de noodzakelijke toegang, waardoor de impact van een bug of een foutieve instructie beperkt blijft. Een service-unit kan alleen beperken wat het proces mag aanraken; de rest moet worden afgehandeld door de agent-harness zelf. Dit is de taak die de DeepSeek Harness-plugins die het installeren waard zijn op een andere stack uitvoeren: bestedingslimieten, toegangsregels per tool en het scannen op prompt-injectie.

De belangrijkste regel is om uw Claude API-key aan de serverzijde te houden. De key betaalt voor en autoriseert elke aanroep, dus deze hoort in een bestand dat alleen leesbaar is voor de gebruiker van de agent. Laad de key als omgevingsvariabele in de service en plaats deze nooit in code, in een repository of op een plek die via een browser bereikbaar is. Genereer hier een complete, beveiligde service-unit voor uw agent:

Voltooi daarna de server zelf. Gebruik uitsluitend SSH-keys en beveilig het account van waaruit u beheert, zoals beschreven in SSH-beveiliging op een VPS. Als u de agent liever vanuit een interactieve sessie aanstuurt terwijl u deze opbouwt, is Claude Code draaien op een VPS met tmux een goed alternatief. Zodra u een tweede sessie op dezelfde machine heeft geopend, kunnen de twee sessies werk tussen elkaar uitwisselen in plaats van dat u elke instructie van het ene naar het andere venster moet kopiëren. En als u de concepten achter dit alles wilt begrijpen, zonder deze aan één specifiek model te koppelen, legt de zusterhandleiding over het bouwen van uw eigen AI-agent op een VPS de fundamenten uit.

Als u op zoek bent naar een terminal-gebaseerde programmeerassistent, behandelt het draaien van een AI-programmeeragent op een VPS Aider en Goose.

FAQ

Welk Claude-model moet ik gebruiken om een agent te bouwen?

Begin met Claude Opus 4.8 (claude-opus-4-8), de capabele standaard, en pas dit aan waar nodig. Claude Sonnet 5 (claude-sonnet-5) is goedkoper en sneller voor het meeste werk, Claude Haiku 4.5 (claude-haiku-4-5) is het meest geschikt voor eenvoudige stappen met een hoog volume, en Claude Fable 5 (claude-fable-5) is het meest capabel voor de zwaarste taken. Een veelgebruikt patroon is om een goedkoper model te gebruiken voor routinematige stappen en een krachtiger model voor de lastige beslissingen, aangezien wisselen slechts een wijziging van één regel code vereist.

Draai ik de volledige agent op mijn VPS, of doet Anthropic dat?

Dit hangt af van de gekozen aanpak. Als u uw eigen loop schrijft tegen de Claude API, of de Claude Agent SDK gebruikt, draait de agent volledig op uw VPS en gaan alleen de modelaanroepen naar Anthropic. Als u Managed Agents gebruikt, voert Anthropic de loop uit en host het de sandbox waarin tools worden uitgevoerd, waardoor er minder op uw server draait. Gebruik voor een agent die op uw eigen machine draait een van de eerste twee opties.

Wat is het verschil tussen de Claude API en de Claude Agent SDK?

De Claude API is het ruwe Messages-eindpunt: u verstuurt een conversatie en tools, en u schrijft zelf de agent-loop eromheen, of u gebruikt de tool-runner van de SDK om deze aan te sturen. De Claude Agent SDK is een bibliotheek op een hoger niveau, Claude Code verpakt om op voort te bouwen, die een volledige loop en ingebouwde bestands-, shell- en zoektools bevat. Gebruik de API wanneer u alles zelf wilt definiëren, en de Agent SDK wanneer u een capabele agent wilt zonder zelf het raamwerk te hoeven samenstellen.

Hoe houd ik mijn Claude API-key veilig op een server?

Houd deze aan de serverzijde en buiten uw code. Sla de key op in een bestand dat alleen leesbaar is voor het account waaronder de agent draait, laad deze in de service als een omgevingsvariabele en commit deze nooit naar een repository of stel deze nooit bloot aan een browser. Omdat elk verzoek aan Claude vanaf uw server vertrekt, hoeft de key nooit het apparaat van een gebruiker te bereiken; dit maakt een server-gebaseerde agent eenvoudiger te beveiligen dan een agent die is ingebed in een client-applicatie.

Moet ik zelf een model hosten om een agent met Claude te bouwen?

Nee. Bij Claude is het model een gehoste service die u aanroept via de API, dus er hoeft niets op een GPU te draaien. Uw VPS voert de agent-loop, de tools en de data uit, en het redeneren vindt plaats aan de kant van Anthropic. Dat is wat een bescheiden server in staat stelt een capabele agent te draaien. Als u in plaats daarvan een volledig lokaal model wilt, is dat het self-hosted pad dat wordt behandeld in de bijbehorende handleiding over het bouwen van uw eigen AI-agent.