1 
2De Claude Agent SDK geeft je programmatische toegang tot dezelfde agent loop die Claude Code aandrijft. Je agents kunnen bestanden lezen, shell-commando's uitvoeren, het web doorzoeken, code bewerken, externe API's aanroepen via MCP-servers, en sub-agents orchestreren  -  allemaal met slechts een paar regels TypeScript of Python.
3 
4In tegenstelling tot de standaard Anthropic Client SDK, waar je je eigen tool loop bouwt, handelt de Agent SDK de tool-uitvoering, contextbeheer, retries en orchestratie intern af. Je beschrijft wat je wilt, levert de tools, en de agent doet de rest.
5 
6## Architectuur
7 
8De SDK volgt een eenvoudige loop: **context verzamelen, actie ondernemen, verifieren, herhalen**.
9 
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18 
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25 
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31 
32    Tool --> T1
33    Tool --> M1
34```
35 
36Het centrale ingangspunt is `query()`, dat een asynchrone iterator teruggeeft die berichten streamt terwijl de agent werkt. Elk bericht vertelt je wat de agent doet: redeneren, een tool aanroepen, een resultaat ontvangen, of de uiteindelijke output leveren.
37 
38## Aan de slag
39 
40### Installatie
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50Je hebt een Anthropic API key nodig, ingesteld als `ANTHROPIC_API_KEY` in je omgeving.
51 
52### Je eerste agent
53 
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56 
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63 
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73 
74Dat is alles. De agent gebruikt Glob om bestanden te vinden, Grep om te zoeken naar TODO-patronen, Read om treffers te inspecteren, en geeft een gestructureerde samenvatting terug. Je schrijft de orchestratielogica niet zelf  -  de SDK regelt dat.
75 
76### Python-equivalent
77 
78```python
79from claude_agent_sdk import query
80 
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90 
91## Ingebouwde tools
92 
93De SDK wordt geleverd met dezelfde tools die beschikbaar zijn in Claude Code:
94 
95| Tool | Beschrijving |
96|------|-------------|
97| **Read** | Bestandsinhoud lezen |
98| **Write** | Nieuwe bestanden aanmaken |
99| **Edit** | Gerichte bewerkingen aan bestaande bestanden |
100| **Bash** | Shell-commando's uitvoeren |
101| **Glob** | Bestanden zoeken op patroon |
102| **Grep** | Bestandsinhoud doorzoeken met regex |
103| **WebSearch** | Het web doorzoeken |
104| **WebFetch** | Een URL ophalen en de inhoud teruggeven |
105| **AskUserQuestion** | De gebruiker om invoer vragen |
106 
107Je bepaalt via `allowedTools` welke tools de agent mag gebruiken. Als een tool niet in de lijst staat, kan de agent het niet aanroepen.
108 
109## Toestemmingsmodi
110 
111Aangezien agents echte commando's op echte systemen uitvoeren, zijn toestemmingen belangrijk.
112 
113| Modus | Gedrag | Toepassing |
114|------|----------|----------|
115| `default` | Aangepaste `canUseTool`-callback beslist per aanroep | Fijnmazige controle |
116| `acceptEdits` | Bestandsoperaties automatisch goedkeuren, vragen bij Bash | Ontwikkelworkflows |
117| `dontAsk` | Alles weigeren wat niet in allowedTools staat | Beperkte agents |
118| `bypassPermissions` | Alles automatisch goedkeuren | Vertrouwde sandbox-omgevingen |
119| `auto` | Model-classifier bepaalt veiligheid | Gebalanceerde automatisering |
120 
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130 
131Voor productiegebruik moet je agents altijd in sandbox-omgevingen draaien (containers, VM's) en de meest restrictieve toestemmingsmodus gebruiken die de agent nog in staat stelt zijn werk te doen.
132 
133## Custom tools bouwen met MCP
134 
135De echte kracht van de SDK zit in het uitbreiden van agents met je eigen tools. Custom tools worden gedefinieerd als in-process MCP-servers  -  geen subproces-beheer, geen netwerk-overhead.
136 
137### Voorbeeld: Weer-tool
138 
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142 
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165 
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171 
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184 
185Custom tools volgen de naamconventie `mcp__{server_name}__{tool_name}`. Je kunt wildcards gebruiken in `allowedTools`: `"mcp__weather__*"` staat alle tools van de weer-server toe.
186 
187### Voorbeeld: Database-query-tool
188 
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203 
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216 
217## Externe MCP-servers verbinden
218 
219Naast in-process tools kun je verbinding maken met elke bestaande MCP-server  -  dezelfde servers die werken met Claude Desktop, Cursor en andere MCP-clients.
220 
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238 
239Je kunt meerdere MCP-servers combineren. De agent ziet alle tools van alle verbonden servers en gebruikt ze naar behoefte.
240 
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249 
250## Multi-agent-orchestratie
251 
252Voor complexe workflows kun je gespecialiseerde sub-agents definiëren waaraan de bovenliggende agent taken delegeert. Elke sub-agent heeft zijn eigen prompt, tools en focusgebied.
253 
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282 
283Voeg `"Agent"` toe aan de `allowedTools` van de bovenliggende agent om delegatie mogelijk te maken. Sub-agents draaien met hun eigen tools en hebben geen toegang tot de tools van de bovenliggende agent, tenzij dit expliciet wordt toegestaan.
284 
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295 
296## Sessies en continuiteit
297 
298Agents kunnen context behouden over meerdere queries door sessies te gebruiken. Leg de `session_id` vast van de eerste interactie en geef deze door in `resume` voor vervolgqueries.
299 
300```typescript
301let sessionId: string | undefined;
302 
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312 
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322 
323## Claude Managed Agents
324 
325Als je de agent-infrastructuur niet zelf wilt hosten, biedt **Claude Managed Agents** (gelanceerd in april 2026) een volledig beheerde cloudservice. Anthropic draait de containers, verzorgt de schaalbaarheid en biedt een streaming API.
326 
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334 
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342 
343Het belangrijkste verschil: met de Agent SDK draai je de agent loop in je eigen infrastructuur. Met Managed Agents host en draait Anthropic de agent voor je. Je communiceert via een sessiegebaseerde API en ontvangt events via Server-Sent Events.
344 
345**Prijzen:**
346- **Agent SDK**: alleen standaard Claude API-tokentarieven. Je regelt zelf het hosting.
347- **Managed Agents**: tokentarieven plus $0,08 per sessie-uur (per milliseconde gefactureerd).
348 
349## Best practices voor productie
350 
351### 1. Altijd sandboxen
352 
353Draai agents nooit met onbeperkte rechten op een productiemachine. Gebruik containers (Docker, Fly.io, Modal) of sandbox-omgevingen (E2B, Vercel Sandbox).
354 
355### 2. Tool-toegang beperken
356 
357Volg het principe van minimale rechten. Een agent die rapporten genereert, heeft geen `Bash` of `Write` nodig.
358 
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362 
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366 
367### 3. Hooks gebruiken als vangrails
368 
369Met hooks kun je tool-aanroepen onderscheppen voor en na uitvoering. Gebruik ze voor logging, validatie en rate limiting.
370 
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389 
390### 4. Fouten netjes afhandelen
391 
392De agent loop kan fouten opleveren  -  tool-fouten, API-rate-limits, context-window-overflow. Controleer altijd de berichttypes.
393 
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411 
412### 5. Tokengebruik monitoren
413 
414Agent loops kunnen aanzienlijk veel tokens verbruiken, vooral bij grote codebases. De SDK bevat automatische contextcompressie, maar je moet het gebruik toch monitoren.
415 
416## Conclusie
417 
418De Claude Agent SDK transformeert een LLM van een vraag-antwoord-machine naar iets dat meer lijkt op een junior developer. Je agents kunnen lezen, schrijven, uitvoeren, verifieren en itereren  -  dezelfde workflow die een mens volgt.
419 
420Begin klein: bouw een agent met een paar ingebouwde tools. Voeg daarna custom MCP-tools toe voor je specifieke domein. Schaal op naar multi-agent-orchestratie wanneer je workflows specialisatie vereisen.
421 
422De agent loop is dezelfde die Claude Code aandrijft. Als die software kan bouwen, kunnen jouw agents dat ook.
423 
424> **Checklist om te beginnen:**
425>
426> - [x] SDK installeren (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] `ANTHROPIC_API_KEY` instellen in je omgeving
428> - [x] Een eenvoudige agent bouwen met ingebouwde tools (Read, Glob, Grep)
429> - [x] Een custom tool toevoegen via een in-process MCP-server
430> - [x] Een externe MCP-server verbinden (GitHub, PostgreSQL, etc.)
431> - [x] Multi-agent-orchestratie implementeren met sub-agents
432> - [x] Een sandbox-omgeving opzetten voor productie
433> - [x] Hooks toevoegen voor logging en vangrails
434