KI-Agenten mit dem Claude Agent SDK erstellen: Ein praktischer Leitfaden

Das Claude Agent SDK bietet programmatischen Zugriff auf dieselbe Agent-Loop, die Claude Code antreibt. Deine Agenten koennen Dateien lesen, Shell-Befehle ausfuehren, das Web durchsuchen, Code bearbeiten, externe APIs ueber MCP-Server aufrufen und Sub-Agenten orchestrieren - alles mit wenigen Zeilen TypeScript oder Python.

Im Gegensatz zum Standard Anthropic Client SDK, bei dem du deine eigene Tool-Loop baust, uebernimmt das Agent SDK die Tool-Ausfuehrung, das Kontextmanagement, Wiederholungsversuche und die Orchestrierung intern. Du beschreibst, was du willst, stellst die Tools bereit, und der Agent erledigt den Rest.

Architektur

Das SDK folgt einer einfachen Schleife: Kontext sammeln, handeln, verifizieren, wiederholen.

Der zentrale Einstiegspunkt ist query(), das einen asynchronen Iterator zurueckgibt, der Nachrichten streamt, waehrend der Agent arbeitet. Jede Nachricht zeigt dir, was der Agent gerade tut: denken, ein Tool aufrufen, ein Ergebnis empfangen oder die finale Ausgabe liefern.

Erste Schritte

Installation

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

# Python
pip install claude-agent-sdk

Du brauchst einen Anthropic API Key, der als ANTHROPIC_API_KEY in deiner Umgebung gesetzt ist.

Dein erster 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);
  }
}

Das war's. Der Agent wird Glob verwenden, um Dateien zu finden, Grep, um nach TODO-Mustern zu suchen, Read, um Treffer zu inspizieren, und eine strukturierte Zusammenfassung zurueckgeben. Du schreibst nicht die Orchestrierungslogik - das SDK uebernimmt das.

Python-Aequivalent

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}")

Integrierte Tools

Das SDK wird mit denselben Tools ausgeliefert, die in Claude Code verfuegbar sind:

Du steuerst ueber allowedTools, welche Tools der Agent verwenden darf. Wenn ein Tool nicht in der Liste steht, kann der Agent es nicht aufrufen.

Berechtigungsmodi

Da Agenten echte Befehle auf echten Systemen ausfuehren, sind Berechtigungen wichtig.

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

Fuer den Produktiveinsatz solltest du Agenten immer in Sandbox-Umgebungen (Container, VMs) ausfuehren und den restriktivsten Berechtigungsmodus verwenden, der dem Agenten noch erlaubt, seine Aufgabe zu erledigen.

Eigene Tools mit MCP erstellen

Die wahre Staerke des SDK liegt in der Erweiterung von Agenten mit eigenen Tools. Eigene Tools werden als In-Process-MCP-Server definiert - kein Subprozess-Management, kein Netzwerk-Overhead.

Beispiel: Wetter-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);
  }
}

Eigene Tools folgen der Namenskonvention mcp__{server_name}__{tool_name}. Du kannst Wildcards in allowedTools verwenden: "mcp__weather__*" erlaubt alle Tools vom Wetter-Server.

Beispiel: Datenbank-Abfrage-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-Server verbinden

Ueber In-Process-Tools hinaus kannst du dich mit jedem bestehenden MCP-Server verbinden - dieselben Server, die mit Claude Desktop, Cursor und anderen MCP-Clients funktionieren.

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__*"],
  },
})) {
  // ...
}

Du kannst mehrere MCP-Server kombinieren. Der Agent sieht alle Tools von allen verbundenen Servern und nutzt sie nach Bedarf.

Multi-Agent-Orchestrierung

Fuer komplexe Workflows kannst du spezialisierte Sub-Agenten definieren, an die der uebergeordnete Agent Aufgaben delegiert. Jeder Sub-Agent hat seinen eigenen Prompt, seine eigenen Tools und seinen eigenen Fokusbereich.

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
}

Fuege "Agent" in die allowedTools des uebergeordneten Agenten ein, um Delegation zu ermoeglichen. Sub-Agenten laufen mit ihren eigenen Tools und koennen nicht auf die Tools des uebergeordneten Agenten zugreifen, es sei denn, dies wird explizit erlaubt.

Sessions und Kontinuitaet

Agenten koennen ueber mehrere Abfragen hinweg den Kontext beibehalten, indem sie Sessions verwenden. Erfasse die session_id aus der ersten Interaktion und uebergib sie in resume fuer nachfolgende Abfragen.

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

Wenn du die Agent-Infrastruktur nicht selbst hosten moechtest, bietet Claude Managed Agents (gestartet im April 2026) einen vollstaendig verwalteten Cloud-Service. Anthropic betreibt die Container, kuemmert sich um die Skalierung und stellt eine Streaming-API bereit.

Der wesentliche Unterschied: Mit dem Agent SDK fuehrst du die Agent-Loop in deiner eigenen Infrastruktur aus. Mit Managed Agents hostet und betreibt Anthropic den Agenten fuer dich. Du interagierst ueber eine session-basierte API und empfaengst Events ueber Server-Sent Events.

Preise:

• Agent SDK: Nur die Standard-Claude-API-Tokenpreise. Du uebernimmst das Hosting.
• Managed Agents: Tokenpreise plus 0,08 $ pro Session-Stunde (millisekundengenau abgerechnet).

Best Practices fuer den Produktiveinsatz

1. Immer sandboxen

Fuehre Agenten niemals mit uneingeschraenkten Berechtigungen auf einem Produktionsrechner aus. Verwende Container (Docker, Fly.io, Modal) oder Sandbox-Umgebungen (E2B, Vercel Sandbox).

2. Tool-Zugriff einschraenken

Folge dem Prinzip der minimalen Berechtigung. Ein Agent, der Berichte generiert, braucht weder Bash noch Write.

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

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

3. Hooks fuer Leitplanken nutzen

Hooks ermoeglichen es dir, Tool-Aufrufe vor und nach der Ausfuehrung abzufangen. Nutze sie fuer Logging, Validierung und 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. Fehler angemessen behandeln

Die Agent-Loop kann Fehler erzeugen - Tool-Fehler, API-Rate-Limits, Context-Window-Ueberlauf. Pruefe immer die Nachrichtentypen.

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. Token-Verbrauch ueberwachen

Agent-Loops koennen erheblich viele Tokens verbrauchen, besonders bei grossen Codebasen. Das SDK enthaelt eine automatische Kontextkomprimierung, aber du solltest den Verbrauch trotzdem ueberwachen.

Fazit

Das Claude Agent SDK verwandelt ein LLM von einer Frage-Antwort-Maschine in etwas, das einem Junior-Entwickler naeherkommt. Deine Agenten koennen lesen, schreiben, ausfuehren, verifizieren und iterieren - derselbe Workflow, dem auch ein Mensch folgt.

Fang klein an: Erstelle einen Agenten mit ein paar integrierten Tools. Fuege dann eigene MCP-Tools fuer deine spezifische Domaene hinzu. Skaliere auf Multi-Agent-Orchestrierung, wenn deine Workflows Spezialisierung erfordern.

Die Agent-Loop ist dieselbe, die Claude Code antreibt. Wenn sie Software bauen kann, koennen deine Agenten das auch.

Checkliste fuer den Einstieg:

• SDK installieren (npm install @anthropic-ai/claude-agent-sdk)
• ANTHROPIC_API_KEY in deiner Umgebung setzen
• Einen einfachen Agenten mit integrierten Tools erstellen (Read, Glob, Grep)
• Ein eigenes Tool ueber einen In-Process-MCP-Server hinzufuegen
• Einen externen MCP-Server verbinden (GitHub, PostgreSQL, etc.)
• Multi-Agent-Orchestrierung mit Sub-Agenten implementieren
• Eine Sandbox-Umgebung fuer den Produktiveinsatz einrichten
• Hooks fuer Logging und Leitplanken hinzufuegen