Wat is een managed agent?

Als je een agent loop handmatig hebt gebouwd, ken je het ritueel: while loops, stop reason switches, tool executions. Dat werkt, en voor veel features is het eigenlijk de juiste vorm. Maar soms gaat die loop erg lang lopen — minuten, misschien zelfs uren — over veel tools heen, met state om bij te houden, bestanden om weg te schrijven, en werk om te hervatten na een netwerkstoring. Op dat moment wil je de loop niet op je server laten draaien. Je wilt het delegeren. Dat zijn managed agents.

Een managed agent is een agent loop die draait op Anthropic's infrastructuur in plaats van de jouwe. Je beschrijft de agent eenmaal, je geeft het een omgeving om in te werken, en je start een sessie. Anthropic draait de loop, en jij streamt de events gewoon terug terwijl het werkt.

Managed agents zijn standaard ingeschakeld voor elk API-account — geen speciale toegang nodig.

De vier primitieven

Er zijn vier primitieven, en ze komen in volgorde:

Agent — de persoonlijkheid: model, system prompt, en toolset. Dit is herbruikbaar over veel runs.
Environment — waar de agent draait: cloud of lokaal, netwerkconfiguratie, enzovoort.
Session — een enkele run van een agent in een bepaalde omgeving. De sessie is de eenheid van werk.
Events — de berichten die in en uit gaan: de acties van de agent, de tool calls, de resultaten, de antwoorden.

Hier is hoe de stukken in elkaar passen: je app praat met een sessie, de sessie drijft werk in de omgeving aan, en alles wat gebeurt stroomt terug via de event stream:

Architecture diagram showing an agent connected to a Session, which drives an Environment, with results flowing back through an Event Stream to your app

Let op de verschuiving hier: je draait geen while loop. Je stuurt events en leest events.

De kleinst mogelijke managed agent

Laten we de kleinst mogelijke managed agent bouwen die iets nuttigs doet: een bestand in de temp drive maken, de regels tellen, en terugrapporteren.

Voor tools gebruiken we de agent toolset — Anthropic's gebundelde file, bash, en web tools. Ze werken prima voor deze taak, dus we hoeven geen tools zelf te definiëren.

Stap 1: Maak de agent

Eerst maken we de agent. Let op de agent toolset gedefinieerd in de tools array — dat is de gebundelde toolset:

import anthropic

client = anthropic. Anthropic()

agent = client. beta. agents. create( name="Line Counter", model="claude-opus-4-8", system="You are a helpful agent that completes small file tasks. ", tools=[ {"type": "agent_toolset_20260401", "default_config": {"enabled": True}} ], )

Onthoud: de agent is herbruikbaar. Maak het eenmaal en voer het uit over veel sessies.

Stap 2: Maak de omgeving

Vervolgens de omgeving. Dit start de container template — cloud, met onbeperkt netwerk. Dit is de sandbox waar het bestand eigenlijk wordt geschreven:

environment = client. beta. environments. create( name="line-counter-env", config={ "type": "cloud", "networking": {"type": "unrestricted"}, }, )

Stap 3: Maak de sessie

Dan maken we een sessie met onze agent en omgeving, plus een optionele titel. De sessie is de eenheid van werk:

session = client. beta. sessions. create( agent=agent. id, environment_id=environment. id, title="Count lines demo", )

Stap 4: Open de stream, stuur dan de kickoff

Nu openen we de event stream — en let op dat we dit eerst doen. De stream levert alleen events af die plaatsvinden nadat deze opent, dus open het altijd voordat je het kickoff bericht stuurt. Dan sturen we het gebruikersbericht in de live stream:

with client. beta. sessions. events. stream(session_id=session. id) as stream:

client. beta. sessions. events. send( session_id=session. id, events=[ { "type": "user. message", "content": [ { "type": "text", "text": "Create a file in the temp directory, " "count its lines, and report back. ", } ], } ], )

Let op dat het events is — meervoud. Events zijn hoe alles in deze API stroomt.

Stap 5: Consumeer de stream

Tot slot consumeren we de stream. Er zijn drie event types die voor deze demo belangrijk zijn:

agent. message — Claude's tekst
agent. tool_use — welke tool Claude koos
session. status_idle — de agent is klaar

for event in stream: if event. type == "agent. message": for block in event. content: if block. type == "text": print(block. text, end="", flush=True) elif event. type == "agent. tool_use": print(f"\n[tool] {event. name}") elif event. type == "session. status_idle": print("\n--- Agent done ---") break

Voer het uit, en de output is de agent die hardop redeneert — echte tekst, de tools die het kiest, en een eindantwoord. Alles draait in Anthropic's container, niet de jouwe:

Terminal output of the managed agent run: agent, environment, and session IDs are created, then the event stream shows the agent writing the file, running its tools, and reporting that the file contains 3 lines

De afweging

Meestal hebben we met agents onze eigen loop waar we alles moeten controleren. Met managed agents delegeer je die loop, de sandbox, en de hervatbaarheid — en consumeer je gewoon de event stream terwijl deze binnenkomt.

In een productie-app is dit de vorm voor langlopende, bestand-aanrakende, "ga dit voor me organiseren" taken. Stel je een file share cleanup voor: een managed agent leest een doelmap structuurspec, loopt door de rommelige inkomende map, verplaatst bestanden naar de juiste projectmappen, archiveert duplicaten en nul-byte rommel, en markeert alles wat het niet zeker kan plaatsen — allemaal in een sessie die minuten kan lopen tegen duizenden bestanden. Hier is hoe dat eruit ziet in een echte app — een fileshare cleanup dashboard dat de activiteit van de agent live streamt terwijl het sorteert, archiveert en bestanden markeert:

A fileshare cleanup web app powered by a managed agent, showing the folder tree being organized alongside a live activity feed of the agent's events as it moves and archives files

Samenvatting

Managed agents zijn de agent loop, voor jou uitgevoerd — op Anthropic's infrastructuur in plaats van je server.
De flow is: maak een agent, maak een omgeving, maak een sessie, stuur events in, en stream events uit.
De agent (model, system prompt, toolset) is herbruikbaar over runs; de sessie is een enkele run; events zijn hoe alles stroomt.
Open de event stream voordat je je kickoff bericht stuurt — het levert alleen events af die plaatsvinden nadat het opent.
Let op drie events: agent. message (tekst), agent. tool_use (tool picks), en session. status_idle (klaar).
Grijp naar managed agents wanneer de loop te lang zou lopen, te veel zou doen, of een storing moet overleven. Grijp naar een handmatige loop wanneer je volledige controle wilt.