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~