Tvorba AI agentu s Claude Agent SDK: Prakticky pruvodce

Claude Agent SDK vam dava programovy pristup ke stejne smycce agenta, ktera pohani Claude Code. Vasi agenti mohou cist soubory, spoustet shellove prikazy, prohledavat web, editovat kod, volat externi API pres MCP servery a orchestrovat sub-agenty - to vse z nekolika radku TypeScriptu nebo Pythonu.

Na rozdil od standardniho Anthropic Client SDK, kde si stavite vlastni smycku nastroju, Agent SDK se stara o vykonavani nastroju, spravu kontextu, opakovani pokusu a orchestraci interne. Popisete, co chcete, poskytnete nastroje a agent si zbytek vyresi sam.

Architektura

SDK se ridi jednoduchou smyckou: shromazdi kontext, proved akci, over, opakuj.

Hlavnim vstupnim bodem je query(), ktery vraci asynchronni iterator streamujici zpravy behem prace agenta. Kazda zprava vam rika, co agent dela: uvazuje, vola nastroj, prijima vysledek nebo dorucuje finalni vystup.

Zacatek

Instalace

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

# Python
pip install claude-agent-sdk

Potrebujete API klic Anthropic nastaveny jako ANTHROPIC_API_KEY ve vasem prostredi.

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

To je vse. Agent pouzije Glob k nalezeni souboru, Grep k hledani vzoru TODO, Read k prozkoumani shod a vrati strukturovany souhrn. Nepisete logiku orchestrace - SDK se o to postara.

Ekvivalent v Pythonu

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

Vestevene nastroje

SDK obsahuje stejne nastroje, ktere jsou dostupne v Claude Code:

Ovladate, ktere nastroje agent muze pouzivat, pomoci allowedTools. Pokud nastroj neni na seznamu, agent ho nemuze zavolat.

Rezimy opravneni

Protoze agenti spousteji skutecne prikazy na skutecnych systemech, opravneni jsou dulezita.

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

Pro produkcni pouziti vzdy spoustejte agenty v sandboxovanych prostredich (kontejnery, VM) a pouzivejte nejrestriktivnejsi rezim opravneni, ktery agentovi stale umoznuje vykonavat svou praci.

Tvorba vlastnich nastroju s MCP

Skutecna sila SDK spociva v rozsireni agentu o vase vlastni nastroje. Vlastni nastroje jsou definovany jako in-process MCP servery - zadna sprava podprocesu, zadna sitova rezie.

Priklad: Nastroj pro pocasi

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

Vlastni nastroje se ridi konvenci pojmenovani mcp__{nazev_serveru}__{nazev_nastroje}. V allowedTools muzete pouzivat zastupne znaky: "mcp__weather__*" povoli vsechny nastroje z weather serveru.

Priklad: Nastroj pro databazove dotazy

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

Pripojeni externich MCP serveru

Krome in-process nastroju se muzete pripojit k libovolnemu existujicimu MCP serveru - stejnym serverum, ktere funguji s Claude Desktop, Cursor a dalsimi MCP klienty.

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

Muzete kombinovat vice MCP serveru. Agent vidi vsechny nastroje ze vsech pripojenych serveru a pouziva je podle potreby.

Orchestrace vice agentu

Pro slozite workflow muzete definovat specializovane sub-agenty, na ktere nadrazeny agent deleguje ukoly. Kazdy sub-agent ma svuj vlastni prompt, nastroje a oblast zameru.

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
}

Pridejte "Agent" do allowedTools nadruzeneho agenta pro umozneni delegovani. Sub-agenti bezi se svymi vlastnimi nastroji a nemaji pristup k nastrojum rodice, pokud to neni explicitne povoleno.

Relace a kontinuita

Agenti mohou udrzovat kontext mezi vice dotazy pomoci relaci. Zachytte session_id z prvni interakce a predejte ho v resume pro nasledujici dotazy.

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

Pokud nechcete hostovat infrastrukturu agenta sami, Claude Managed Agents (spusteno v dubnu 2026) poskytuje plne spravovanou cloudovou sluzbu. Anthropic provozuje kontejnery, stara se o skalovani a poskytuje streamovaci API.

Klicovy rozdil: s Agent SDK spoustite smycku agenta ve sve vlastni infrastrukture. S Managed Agents Anthropic hostuje a spousti agenta za vas. Komunikujete pres API zalozene na relacich a prijimate udalosti pres Server-Sent Events.

Cenik:

• Agent SDK: pouze standardni sazby za tokeny Claude API. Hosting zajistujete vy.
• Managed Agents: sazby za tokeny plus 0,08 USD za hodinu relace (uctovano po milisekundach).

Nejlepsi postupy pro produkci

1. Vzdy izolujte

Nikdy nespoustejte agenty s neomezenymi opravnenimi na produkcnim stroji. Pouzivejte kontejnery (Docker, Fly.io, Modal) nebo sandboxovana prostredi (E2B, Vercel Sandbox).

2. Omezte pristup k nastrojum

Ridtse se principem nejmensich opravneni. Agent generujici reporty nepotrebuje Bash ani Write.

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

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

3. Pouzivejte hooky jako ochranne mechanismy

Hooky vam umoznuji zachytavat volani nastroju pred a po provedeni. Pouzivejte je pro logovani, validaci a omezeni frekvence.

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. Zvladejte chyby elegantne

Smycka agenta muze produkovat chyby - selhani nastroju, limity API, preteceni kontextoveho okna. Vzdy kontrolujte typy zprav.

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. Monitorujte spotreby tokenu

Smycky agentu mohou spotrebovat vyznamne mnozstvi tokenu, obzvlaste u velkych codebasi. SDK obsahuje automatickou kompakci kontextu, ale i tak byste meli monitorovat spotreby.

Zaver

Claude Agent SDK premeni LLM z stroje na odpovidani otazek v neco blizsiho juniorinimu vyvojari. Vasi agenti mohou cist, psat, spoustet, overovat a iterovat - stejny workflow, jaky nasleduje clovek.

Zacnete v malem: postavte agenta s nekolika vestavenymi nastroji. Pak pridejte vlastni MCP nastroje pro svou konkretni domenu. Skalujte na orchestraci vice agentu, kdyz vase workflow vyzaduji specializaci.

Smycka agenta je stejna jako ta, ktera pohani Claude Code. Pokud dokaze stavet software, vasi agenti to dokazou take.

Kontrolni seznam pro zacatek:

• Nainstalujte SDK (npm install @anthropic-ai/claude-agent-sdk)
• Nastavte ANTHROPIC_API_KEY ve vasem prostredi
• Postavte jednoducheho agenta s vestavenymi nastroji (Read, Glob, Grep)
• Pridejte vlastni nastroj pres in-process MCP server
• Pripojte externi MCP server (GitHub, PostgreSQL, atd.)
• Implementujte orchestraci vice agentu se sub-agenty
• Nastavte sandboxovane prostredi pro produkci
• Pridejte hooky pro logovani a ochranne mechanismy