Bygga AI-agenter med Claude Agent SDK: En praktisk guide

Claude Agent SDK ger dig programmatisk tillgang till samma agent loop som driver Claude Code. Dina agenter kan laesa filer, koera shell-kommandon, soeka pa webben, redigera kod, anropa externa API:er via MCP-servrar och orkestrera sub-agenter - allt med nagra fa rader TypeScript eller Python.

Till skillnad fran standard Anthropic Client SDK, daer du bygger din egen tool loop, hanterar Agent SDK verktygskoerning, kontexthantering, omfoersoek och orkestrering internt. Du beskriver vad du vill, tillhandahaller verktygen, och agenten skoeter resten.

Arkitektur

SDK:n foeljer en enkel loop: samla kontext, agera, verifiera, upprepa.

Den centrala ingangspunkten aer query(), som returnerar en asynkron iterator som streamar meddelanden medan agenten arbetar. Varje meddelande talar om vad agenten goer: resonerar, anropar ett verktyg, tar emot ett resultat eller levererar den slutgiltiga outputen.

Komma igang

Installation

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

# Python
pip install claude-agent-sdk

Du behoever en Anthropic API-nyckel satt som ANTHROPIC_API_KEY i din miljoevariabel.

Din foersta 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);
  }
}

Det aer allt. Agenten anvaender Glob foer att hitta filer, Grep foer att soeka efter TODO-moenster, Read foer att inspektera traeffar, och returnerar en strukturerad sammanfattning. Du skriver inte orkestreringslogiken - SDK:n hanterar det.

Python-motsvarighet

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

Inbyggda verktyg

SDK:n levereras med samma verktyg som finns tillgaengliga i Claude Code:

Du styr vilka verktyg agenten far anvaenda via allowedTools. Om ett verktyg inte finns i listan kan agenten inte anropa det.

Behoerrighetslaegen

Eftersom agenter koer riktiga kommandon pa riktiga system aer behoerrigheter viktiga.

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

Foer produktionsanvaendning boeraer du alltid koera agenter i sandbox-miljoeer (containers, VM:ar) och anvaenda det mest restriktiva behoerrighetslaege som fortfarande later agenten goera sitt jobb.

Bygga egna verktyg med MCP

Den verkliga styrkan hos SDK:n ligger i att utvidga agenter med egna verktyg. Egna verktyg definieras som in-process MCP-servrar - ingen subprocesshantering, ingen naetverks-overhead.

Exempel: Vaeder-verktyg

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

Egna verktyg foeljer namnkonventionen mcp__{server_name}__{tool_name}. Du kan anvaenda wildcards i allowedTools: "mcp__weather__*" tillater alla verktyg fran vaeder-servern.

Exempel: Databasfrageverktyg

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),
        },
      ],
    };
  }
);

Ansluta externa MCP-servrar

Utoevar in-process-verktyg kan du ansluta till vilken befintlig MCP-server som helst - samma servrar som fungerar med Claude Desktop, Cursor och andra MCP-klienter.

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 kan kombinera flera MCP-servrar. Agenten ser alla verktyg fran alla anslutna servrar och anvaender dem efter behov.

Multi-agent-orkestrering

Foer komplexa workflows kan du definiera specialiserade sub-agenter som den oeverordnade agenten delegerar till. Varje sub-agent har sin egen prompt, sina egna verktyg och sitt eget fokusomrade.

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
}

Inkludera "Agent" i den oeverordnade agentens allowedTools foer att aktivera delegering. Sub-agenter koers med sina egna verktyg och kan inte komma at den oeverordnade agentens verktyg om det inte uttryckligen medges.

Sessioner och kontinuitet

Agenter kan behaalla kontext oevar flera fragor genom att anvaenda sessioner. Fanga session_id fran den foersta interaktionen och skicka med den i resume foer efterfoeljande fragor.

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

Om du inte vill hosta agent-infrastrukturen sjaelv erbjuder Claude Managed Agents (lanserat i april 2026) en helt hanterad molntjaenst. Anthropic koer containrarna, skoeter skalningen och tillhandahaller ett streaming-API.

Den viktigaste skillnaden: med Agent SDK koer du agent-loopen i din egen infrastruktur. Med Managed Agents hostar och koer Anthropic agenten at dig. Du interagerar via ett sessionsbaserat API och tar emot events via Server-Sent Events.

Priser:

• Agent SDK: enbart standardpriser foer Claude API-tokens. Du star foer hostingen.
• Managed Agents: tokenpriser plus $0,08 per sessionstimme (faktureras per millisekund).

Best practices foer produktion

1. Koer alltid i sandbox

Koer aldrig agenter med obegransade behoerrigheter pa en produktionsmaskin. Anvaend containers (Docker, Fly.io, Modal) eller sandbox-miljoeer (E2B, Vercel Sandbox).

2. Begraensa verktygsatkomst

Foelj principen om minsta behoerighet. En agent som genererar rapporter behoever varken Bash eller Write.

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

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

3. Anvaend hooks som skyddsraecken

Med hooks kan du fanga upp verktygsanrop foere och efter koerning. Anvaend dem foer loggning, validering och 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. Hantera fel pa ett bra saett

Agent-loopen kan producera fel - verktygsfel, API-rate-limits, context-window-overflow. Kontrollera alltid meddelandetyper.

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. Oevervaka tokenanvaendning

Agent-loopar kan foerbruka avsevarda maengder tokens, saerskilt med stora kodbaser. SDK:n inkluderar automatisk kontextkomprimering, men du boer aenda oevervaka anvaendningen.

Slutsats

Claude Agent SDK foerandrar ett LLM fran en fraga-svar-maskin till nagot som liknar en junior-utvecklare. Dina agenter kan laesa, skriva, koera, verifiera och iterera - samma arbetsflode som en maenniska foeljer.

Boerja smatt: bygg en agent med nagra fa inbyggda verktyg. Laegg sedan till egna MCP-verktyg foer din specifika domaen. Skala upp till multi-agent-orkestrering naer dina workflows kraever specialisering.

Agent-loopen aer densamma som driver Claude Code. Om den kan bygga mjukvara kan dina agenter det ocksa.

Checklista foer att komma igang:

• Installera SDK:n (npm install @anthropic-ai/claude-agent-sdk)
• Saett ANTHROPIC_API_KEY i din miljoevariabel
• Bygg en enkel agent med inbyggda verktyg (Read, Glob, Grep)
• Laegg till ett eget verktyg via en in-process MCP-server
• Anslut en extern MCP-server (GitHub, PostgreSQL, etc.)
• Implementera multi-agent-orkestrering med sub-agenter
• Saett upp en sandbox-miljoe foer produktion
• Laegg till hooks foer loggning och skyddsraecken