AI-agents bouwen met de Claude Agent SDK: Een praktische gids

De 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.

In 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.

Architectuur

De SDK volgt een eenvoudige loop: context verzamelen, actie ondernemen, verifieren, herhalen.

Het 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.

Aan de slag

Installatie

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Je hebt een Anthropic API key nodig, ingesteld als ANTHROPIC_API_KEY in je omgeving.

Je eerste agent

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Dat 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.

Python-equivalent

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Ingebouwde tools

De SDK wordt geleverd met dezelfde tools die beschikbaar zijn in Claude Code:

Tool	Beschrijving
Read	Bestandsinhoud lezen
Write	Nieuwe bestanden aanmaken
Edit	Gerichte bewerkingen aan bestaande bestanden
Bash	Shell-commando's uitvoeren
Glob	Bestanden zoeken op patroon
Grep	Bestandsinhoud doorzoeken met regex
WebSearch	Het web doorzoeken
WebFetch	Een URL ophalen en de inhoud teruggeven
AskUserQuestion	De gebruiker om invoer vragen

Je bepaalt via allowedTools welke tools de agent mag gebruiken. Als een tool niet in de lijst staat, kan de agent het niet aanroepen.

Toestemmingsmodi

Aangezien agents echte commando's op echte systemen uitvoeren, zijn toestemmingen belangrijk.

Modus	Gedrag	Toepassing
default	Aangepaste canUseTool-callback beslist per aanroep	Fijnmazige controle
acceptEdits	Bestandsoperaties automatisch goedkeuren, vragen bij Bash	Ontwikkelworkflows
dontAsk	Alles weigeren wat niet in allowedTools staat	Beperkte agents
bypassPermissions	Alles automatisch goedkeuren	Vertrouwde sandbox-omgevingen
auto	Model-classifier bepaalt veiligheid	Gebalanceerde automatisering

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Voor 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.

Custom tools bouwen met MCP

De 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.

Voorbeeld: Weer-tool

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Custom 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.

Voorbeeld: Database-query-tool

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Externe MCP-servers verbinden

Naast in-process tools kun je verbinding maken met elke bestaande MCP-server - dezelfde servers die werken met Claude Desktop, Cursor en andere MCP-clients.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Je kunt meerdere MCP-servers combineren. De agent ziet alle tools van alle verbonden servers en gebruikt ze naar behoefte.

Multi-agent-orchestratie

Voor 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.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Voeg "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.

Sessies en continuiteit

Agents 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.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Als 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.

Het 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.

Prijzen:

• Agent SDK: alleen standaard Claude API-tokentarieven. Je regelt zelf het hosting.
• Managed Agents: tokentarieven plus $0,08 per sessie-uur (per milliseconde gefactureerd).

Best practices voor productie

1. Altijd sandboxen

Draai agents nooit met onbeperkte rechten op een productiemachine. Gebruik containers (Docker, Fly.io, Modal) of sandbox-omgevingen (E2B, Vercel Sandbox).

2. Tool-toegang beperken

Volg het principe van minimale rechten. Een agent die rapporten genereert, heeft geen Bash of Write nodig.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Hooks gebruiken als vangrails

Met hooks kun je tool-aanroepen onderscheppen voor en na uitvoering. Gebruik ze voor logging, validatie en rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Fouten netjes afhandelen

De agent loop kan fouten opleveren - tool-fouten, API-rate-limits, context-window-overflow. Controleer altijd de berichttypes.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Tokengebruik monitoren

Agent loops kunnen aanzienlijk veel tokens verbruiken, vooral bij grote codebases. De SDK bevat automatische contextcompressie, maar je moet het gebruik toch monitoren.

Conclusie

De 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.

Begin 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.

De agent loop is dezelfde die Claude Code aandrijft. Als die software kan bouwen, kunnen jouw agents dat ook.

Checklist om te beginnen:

• SDK installeren (npm install @anthropic-ai/claude-agent-sdk)
• ANTHROPIC_API_KEY instellen in je omgeving
• Een eenvoudige agent bouwen met ingebouwde tools (Read, Glob, Grep)
• Een custom tool toevoegen via een in-process MCP-server
• Een externe MCP-server verbinden (GitHub, PostgreSQL, etc.)
• Multi-agent-orchestratie implementeren met sub-agents
• Een sandbox-omgeving opzetten voor productie
• Hooks toevoegen voor logging en vangrails