Budowanie agentow AI z Claude Agent SDK: Praktyczny przewodnik

Claude Agent SDK daje programistyczny dostep do tej samej petli agenta, ktora napedza Claude Code. Twoi agenci moga czytac pliki, wykonywac komendy powloki, przeszukiwac internet, edytowac kod, wywolywac zewnetrzne API przez serwery MCP i koordynowac sub-agentow - wszystko za pomoca kilku linii TypeScript lub Python.

W przeciwienstwie do standardowego Anthropic Client SDK, gdzie samodzielnie budujesz petle narzedzi, Agent SDK obsluguje wykonywanie narzedzi, zarzadzanie kontekstem, ponawianie prob i orkiestracje wewnetrznie. Opisujesz, czego chcesz, dostarczasz narzedzia, a agent sam rozwiazuje reszte.

Architektura

SDK opiera sie na prostej petli: zbierz kontekst, podejmij dzialanie, zweryfikuj, powtorz.

Glownym punktem wejscia jest query(), ktory zwraca asynchroniczny iterator strumieniujacy wiadomosci w trakcie pracy agenta. Kazda wiadomosc informuje, co agent robi: rozumuje, wywoluje narzedzie, odbiera wynik lub dostarcza koncowy rezultat.

Pierwsze kroki

Instalacja

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

# Python
pip install claude-agent-sdk

Potrzebujesz klucza API Anthropic ustawionego jako ANTHROPIC_API_KEY w zmiennych srodowiskowych.

Twoj pierwszy 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 wszystko. Agent uzyje Glob do znalezienia plikow, Grep do wyszukiwania wzorow TODO, Read do przegladania dopasowania i zwroci ustrukturyzowane podsumowanie. Nie piszesz logiki orkiestracji - SDK zajmuje sie tym za Ciebie.

Odpowiednik w Pythonie

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

Wbudowane narzedzia

SDK zawiera te same narzedzia dostepne w Claude Code:

Kontrolujesz, z ktorych narzedzi agent moze korzystac, za pomoca allowedTools. Jesli narzedzie nie znajduje sie na liscie, agent nie moze go wywolac.

Tryby uprawnien

Poniewaz agenci wykonuja prawdziwe komendy na prawdziwych systemach, uprawnienia maja znaczenie.

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

W srodowisku produkcyjnym zawsze uruchamiaj agentow w izolowanych srodowiskach (kontenery, maszyny wirtualne) i uzywaj najbardziej restrykcyjnego trybu uprawnien, ktory nadal pozwala agentowi wykonywac swoja prace.

Tworzenie wlasnych narzedzi z MCP

Prawdziwa sila SDK tkwi w rozszerzaniu agentow o wlasne narzedzia. Wlasne narzedzia sa definiowane jako serwery MCP dzialajace w procesie - bez zarzadzania podprocesami, bez narzutu sieciowego.

Przyklad: Narzedzie pogodowe

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

Wlasne narzedzia stosuja konwencje nazewnicza mcp__{nazwa_serwera}__{nazwa_narzedzia}. Mozesz uzywac symboli wieloznacznych w allowedTools: "mcp__weather__*" zezwala na wszystkie narzedzia z serwera pogodowego.

Przyklad: Narzedzie do zapytan bazodanowych

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

Podlaczanie zewnetrznych serwerow MCP

Oprocz narzedzi dzialajacych w procesie, mozesz laczyc sie z dowolnym istniejacym serwerem MCP - tymi samymi serwerami, ktore dzialaja z Claude Desktop, Cursor i innymi klientami MCP.

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

Mozesz laczyc wiele serwerow MCP. Agent widzi wszystkie narzedzia ze wszystkich podlaczonych serwerow i uzywa ich w razie potrzeby.

Orkiestracja wielu agentow

W przypadku zlozonych procesow mozesz definiowac wyspecjalizowanych sub-agentow, do ktorych agent nadrzedny deleguje zadania. Kazdy sub-agent ma wlasny prompt, narzedzia i obszar specjalizacji.

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
}

Dodaj "Agent" do allowedTools agenta nadrzednego, aby umozliwic delegowanie. Sub-agenci dzialaja z wlasnymi narzedziami i nie maja dostepu do narzedzi rodzica, chyba ze zostanie to jawnie przyznane.

Sesje i ciaglosc

Agenci moga utrzymywac kontekst miedzy wieloma zapytaniami za pomoca sesji. Przechwyc session_id z pierwszej interakcji i przekaz go w resume dla kolejnych zapytan.

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

Jesli nie chcesz samodzielnie hostowac infrastruktury agenta, Claude Managed Agents (uruchomiony w kwietniu 2026) zapewnia w pelni zarzadzana usluge chmurowa. Anthropic prowadzi kontenery, obsluguje skalowanie i udostepnia API strumieniowe.

Kluczowa roznica: z Agent SDK uruchamiasz petle agenta we wlasnej infrastrukturze. Z Managed Agents Anthropic hostuje i uruchamia agenta za Ciebie. Komunikujesz sie przez API oparte na sesjach i otrzymujesz zdarzenia przez Server-Sent Events.

Cennik:

• Agent SDK: tylko standardowe stawki za tokeny Claude API. Hosting po Twojej stronie.
• Managed Agents: stawki za tokeny plus 0,08 USD za godzine sesji (rozliczane co milisekunde).

Najlepsze praktyki produkcyjne

1. Zawsze izoluj

Nigdy nie uruchamiaj agentow z nieograniczonymi uprawnieniami na maszynie produkcyjnej. Uzywaj kontenerow (Docker, Fly.io, Modal) lub izolowanych srodowisk (E2B, Vercel Sandbox).

2. Ogranicz dostep do narzedzi

Stosuj zasade najmniejszych uprawnien. Agent generujacy raporty nie potrzebuje Bash ani Write.

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

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

3. Uzywaj hookow jako zabezpieczen

Hooki pozwalaja przechwytywac wywolania narzedzi przed i po wykonaniu. Uzywaj ich do logowania, walidacji i ograniczania czestotliwosci.

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. Obsluguj bledy elegancko

Petla agenta moze generowac bledy - awarie narzedzi, limity API, przepelnienie okna kontekstu. Zawsze sprawdzaj typy wiadomosci.

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. Monitoruj zuzycie tokenow

Petle agentow moga zuzyc znaczna ilosc tokenow, szczegolnie w duzych bazach kodu. SDK zawiera automatyczna kompakcje kontekstu, ale i tak powinienes monitorowac zuzycie.

Podsumowanie

Claude Agent SDK zamienia LLM z maszyny odpowiadajacej na pytania w cos blizszego mlodszemu deweloperowi. Twoi agenci moga czytac, pisac, wykonywac, weryfikowac i iterowac - ten sam workflow, ktory stosuje czlowiek.

Zacznij od malego: zbuduj agenta z kilkoma wbudowanymi narzedziami. Potem dodaj wlasne narzedzia MCP dla swojej konkretnej dziedziny. Skaluj do orkiestracji wielu agentow, gdy Twoje procesy wymagaja specjalizacji.

Petla agenta jest ta sama, ktora napedza Claude Code. Jesli moze budowac oprogramowanie, Twoi agenci tez moga.

Lista kontrolna na start:

• Zainstaluj SDK (npm install @anthropic-ai/claude-agent-sdk)
• Ustaw ANTHROPIC_API_KEY w zmiennych srodowiskowych
• Zbuduj prostego agenta z wbudowanymi narzedziami (Read, Glob, Grep)
• Dodaj wlasne narzedzie przez serwer MCP dzialajacy w procesie
• Podlacz zewnetrzny serwer MCP (GitHub, PostgreSQL, itp.)
• Zaimplementuj orkiestracje wielu agentow z sub-agentami
• Skonfiguruj izolowane srodowisko do produkcji
• Dodaj hooki do logowania i zabezpieczen