AI agensek epitese a Claude Agent SDK-val: Gyakorlati utmutato

A Claude Agent SDK programozasi hozzeferest biztosit ugyanahhoz az agens ciklushoz, amely a Claude Code-ot hajtja. Az agenseid fajlokat olvashatnak, shell parancsokat futtathatnak, kereshetnek a weben, kodot szerkeszthetnek, kulso API-kat hivhatnak MCP szervereken keresztul es sub-agenseket orchestralhatnak - mindezt nehany sor TypeScript vagy Python koddal.

A standard Anthropic Client SDK-val ellentetben, ahol magad epitesz eszkoz ciklust, az Agent SDK belsoen kezeli az eszkozok vegrehajatasat, a kontextus kezeleset, az ujraprobalkozasokat es az orchestraciot. Leirod, mit szeretnel, biztositod az eszkozoket, es az agens megoldja a tobbit.

Architektura

Az SDK egy egyszeru ciklust kovet: gyujts kontextust, cselekedj, ellenorizd, ismeteld.

A fo belepesi pont a query(), amely egy aszinkron iteratort ad vissza, ami uzeneteket streamel, mig az agens dolgozik. Minden uzenet megmondja, mit csinal az agens: gondolkodik, eszkozt hiv, eredmenyt kap vagy a vegleges kimenetet szallitja.

Kezdes

Telepites

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

# Python
pip install claude-agent-sdk

Szukseged van egy Anthropic API kulcsra, amelyet ANTHROPIC_API_KEY-kent allitasz be a kornyezetedben.

Az elso agensed

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

Ennyi az egesz. Az agens a Glob-ot hasznalja a fajlok megtalalsahoz, a Grep-et a TODO mintak keresesehez, a Read-et a talalatok vizsgalatahoz, es egy strukturalt osszefoglalast ad vissza. Nem te irod az orchestracis logikat - az SDK kezeli helyetted.

Python megfeleloje

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

Beepitett eszkozok

Az SDK ugyanazokat az eszkozoket tartalmazza, amelyek a Claude Code-ban elerhetek:

Az allowedTools-szal szabalyozod, mely eszkozoket hasznalhatja az agens. Ha egy eszkoz nincs a listan, az agens nem hivhatja meg.

Jogosultsagi modok

Mivel az agensek valos parancsokat hajtanak vegre valos rendszereken, a jogosultsagok szamitanak.

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

Produkcios hasznalatra mindig futtasd az agenseket sandbox kornyezetben (kontenerek, VM-ek) es hasznald a legszigorubb jogosultsagi modot, amely meg lehetove teszi az agens munkajat.

Egyedi eszkozok epitese MCP-vel

Az SDK igazi ereje az agensek sajat eszkozokkel valo boviteseben rejlik. Az egyedi eszkozok in-process MCP szerverkent vannak definialva - nincs alprocess kezeles, nincs halozati terhelts.

Pelda: Idojaras eszkoz

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

Az egyedi eszkozok az mcp__{szerver_nev}__{eszkoz_nev} elnevezesi konvenciot kovetik. Hasznalhatsz helyettesito karaktereket az allowedTools-ban: az "mcp__weather__*" engedlyezi az osszes eszkozt a weather szerverrol.

Pelda: Adatbazis lekerdezesi eszkoz

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

Kulso MCP szerverek csatlakoztatasa

Az in-process eszkozokon tul barmely letezo MCP szerverhez csatlakozhatsz - ugyanazokhoz a szerverekhez, amelyek a Claude Desktop-pal, Cursor-ral es mas MCP kliensekkel mukodnek.

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

Tobb MCP szervert is kombinalhatsz. Az agens latja az osszes eszkozt az osszes csatlakoztatott szerverrol es szukseg szerint hasznalja oket.

Tobb agens orchestracioja

Osszetett munkafolyamatokhoz specializalt sub-agenseket definalhatsz, amelyekre a szulo agens feladatokat delegl. Minden sub-agensnek sajat promptja, eszkozei es fokuszteriilete van.

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
}

Add hozza az "Agent"-et a szulo agens allowedTools-jahoz a delegalas engedelyezesehez. A sub-agensek sajat eszkozikkel futnak, es nem fernek hozza a szulo eszkozeihez, hacsak nem kapnak kifejezett engedelyt.

Munkamenetek es folytonossag

Az agensek munkamenetek segitsegevel tobb lekerdezes kozott is fenntarthatjak a kontextust. Ragadd meg a session_id-t az elso interakciobol es add at a resume-ban a kovetkezo lekerdezeseknel.

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

Ha nem szeretned magad uzemeltetni az agens infrastrukturajat, a Claude Managed Agents (2026 aprilisaban indult) teljes mertekben kezelt felhoszolgaltatast biztosit. Az Anthropic futtatja a kontenereket, kezeli a skalazast es streaming API-t biztosit.

A kulcsfontossagu kulonbseg: az Agent SDK-val az agens ciklust a sajat infrastrukturadban futtatod. A Managed Agents-szel az Anthropic hosztolia es futtatja az agenst helyetted. Munkamenet-alapu API-n keresztul kommunikalsz es Server-Sent Events-en keresztul kapod az esemenyeket.

Arazes:

• Agent SDK: csak a standard Claude API token dijak. A hosztolast te biztositod.
• Managed Agents: token dijak plusz 0,08 USD munkamenet-orankent (milliszekundumonkent szamlazva).

Produkcios best practice-ek

1. Mindig izolalj

Soha ne futtass agenseket korlatlan jogosultsagokkal produkcios gepen. Hasznalj kontenereket (Docker, Fly.io, Modal) vagy sandbox kornyezeteket (E2B, Vercel Sandbox).

2. Korlatoz az eszkoz hozzaferest

Kovasd a legkisebb jogosultsag elvet. Egy jelenteseket generalo agens nem igenyli a Bash-t vagy a Write-ot.

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

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

3. Hasznalj hookokat vedokorlatokent

A hookok lehetove teszik az eszkoz hivasok elfogasat vegrehajtas elott es utan. Hasznald oket naplozasra, validaciora es sebessegorlatozasra.

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. Kezeld elegansan a hibakat

Az agens ciklus hibakat produlhat - eszkoz meghibasodasok, API limitek, kontextus ablak tulcsordulas. Mindig ellenorizd az uzenet tipusokat.

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. Figyeld a token felhasznalast

Az agens ciklusok jelentos mennyisegu tokent fogyaszthatnak, kulonosen nagy kodbazisoknal. Az SDK tartalmaz automatikus kontextus tomoritest, de ettol fuggetlenul erdemes figyelni a felhasznalast.

Osszefoglalas

A Claude Agent SDK egy LLM-et kerdesekre valaszolo gepbol valami olyanra alakit, ami kozelebb all egy junior fejlesztohoz. Az agenseid olvashatnak, irhatnak, vegrehajthatnak, ellenorizhetnek es iteralhatnak - ugyanaz a munkafolyamat, amit egy ember kovet.

Kezdj kiciben: epits egy agenst nehany beepitett eszkozzel. Aztan adj hozza egyedi MCP eszkozoket a sajat szakteruletedhez. Skalazz tobb agens orchestraciora, amikor a munkafolyamataid specializaciot igenyelnek.

Az agens ciklus ugyanaz, amely a Claude Code-ot hajtja. Ha az kepes szoftvert epiteni, a te agenseid is kepesek ra.

Kezdesi ellenorzo lista:

• Telepitsd az SDK-t (npm install @anthropic-ai/claude-agent-sdk)
• Allitsd be az ANTHROPIC_API_KEY-t a kornyezetedben
• Epits egy egyszeru agenst beepitett eszkozokkel (Read, Glob, Grep)
• Adj hozza egyedi eszkozt in-process MCP szerveren keresztul
• Csatlakoztass kulso MCP szervert (GitHub, PostgreSQL, stb.)
• Implementalj tobb agens orchestraciot sub-agensekkel
• Allits be sandbox kornyezetet produkciohoz
• Adj hozza hookokat naplozashoz es vedokorlatokhoz