Stvorennia AI-ahentiv z Claude Agent SDK: Praktychnyi posibnyk

Claude Agent SDK nadaie prohramnyi dostup do toho samoho tsyklu ahenta, shcho stoiit za Claude Code. Vashi ahenty mozhut chytaty faily, vykonuvaty komandy obolonky, shukaty v interneti, redahuvaty kod, vyklykaty zovnishni API cherez MCP-servery ta orkestruvaty sub-ahentiv - vse tse z kilkokh riadkiv TypeScript abo Python.

Na vidminu vid standartnoho Anthropic Client SDK, de vy samoshtihno buduiete tsykl instrumentiv, Agent SDK vnutrishno obrobliaie vykonannia instrumentiv, keruvannia kontekstom, povtorni sproby ta orkestruvannia. Vy opysuiete, shcho khochiete, nadaiete instrumenty, a ahent rozbyraietsia z reshtou.

Arkhitektura

SDK sliduie prostomu tsyklu: zbyraie kontekst, vykonuie diiu, pereviriate, povtoriuie.

Holovnou tochkoiu vkhodu ie query(), yaka povertaie asynkhronnyi iterator, shcho transliuie povidomlennia pid chas roboty ahenta. Kozhne povidomlennia kazhe vam, shcho robyit ahent: mirkuie, vyklykaie instrument, otrymuie rezultat abo dostavliaie kintsevyi vyvid.

Pochatok roboty

Vstanovlennia

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

# Python
pip install claude-agent-sdk

Vam potriben API-kliuch Anthropic, vstanovlenyi yak ANTHROPIC_API_KEY u vashomu otochenni.

Vash pershyi ahent

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

Ot i vse. Ahent vykorystovuie Glob dlia poshuku failiv, Grep dlia poshuku patterniv TODO, Read dlia vyvchhennia zbihiv i povertaie strukturovane reziume. Vy ne pyshete lohiku orkestratsii - SDK berete tse na sebe.

Ekvivalent na Python

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

Vbudovani instrumenty

SDK postachaietsia z tymy samymy instrumentamy, shcho dostupni v Claude Code:

Vy kontroliuiete, yaki instrumenty ahent mozhe vykorystovuvaty, cherez allowedTools. Yakshcho instrumenta nemaie u spysku, ahent ne mozhe yoho vyklykaty.

Rezhymy dozvoliv

Oskilky ahenty vykonuiut realni komandy na realnykh systemakh, dozvoly maiut znachennia.

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

Dlia produktsiinoho vykorystannia zavzhdy zapuskaiite ahentiv u izolovanykh seredovyshchakh (konteinery, virtualni mashyny) ta vykorystovuiite naistrozhishyi rezhym dozvoliv, yakyi vse shche dozvoliaie ahentu vykonuvaty svoiu robotu.

Stvorennia vlasnykh instrumentiv z MCP

Spravzhnia syla SDK poliahaie u rozshyrenni ahentiv vashymy vlasnymy instrumentamy. Vlasni instrumenty vyznachaiutsia yak in-process MCP-servery - bez keruvannia pidprotsesamy, bez merezhnykh nakladnykh vytrat.

Pryklad: Instrument pohody

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

Vlasni instrumenty sliduiut konventsii naymenuvannia mcp__{imia_servera}__{imia_instrumenta}. Vy mozhete vykorystovuvaty pidstavni znaky v allowedTools: "mcp__weather__*" dozvoliaie vsi instrumenty z servera pohody.

Pryklad: Instrument zapytiv do bazy danykh

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

Pidkliuchennia zovnishnikh MCP-serveriv

Okrim in-process instrumentiv, vy mozhete pidkliuchatysia do bud-yakoho isnuiuchoho MCP-servera - tykh samykh serveriv, shcho pratsiuiut z Claude Desktop, Cursor ta inshymy MCP-kliientamy.

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

Vy mozhete kombinuvaty kilka MCP-serveriv. Ahent bachyt vsi instrumenty z usikh pidkliuchenykh serveriv ta vykorystovuie ikh za potreboiu.

Orkestruvannia kilkokh ahentiv

Dlia skladnykh robochykh protsesiv vy mozhete vyznachaty spetsializovanykh sub-ahentiv, yakym batkivskyj ahent delehuie zavdannia. Kozhnyj sub-ahent maie vlasnyj prompt, instrumenty ta oblast fokusu.

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
}

Dodaite "Agent" do allowedTools batkivskoho ahenta dlia vvimknennia delehuvannia. Sub-ahenty pratsiuiut zi svoimy instrumentamy i ne maiut dostupu do instrumentiv batka, yakshcho tse ne nadano yavno.

Sesii ta bezperervnist

Ahenty mozhut pidtrymuvaty kontekst mizh kilkoma zapytamy za dopomohoiu sesii. Zakhopliuite session_id z pershoi vzaiemodii ta peredaite yoho u resume dlia nastupnykh zapytiv.

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

Yakshcho vy ne khochete samoshtiiino rozmishchuvaty infrastrukturu ahenta, Claude Managed Agents (zapushchenyj u kvitni 2026) nadaie povnistiu kerovanyj khmarnyi servis. Anthropic zapuskaie konteinery, obrobliaie mashcabuvannia ta nadaie streaming API.

Kliuchova vidminnist: z Agent SDK vy zapuskaete tsykl ahenta u vlasnii infrastrukturi. Z Managed Agents Anthropic rozmishchuie ta zapuskaie ahenta za vas. Vy vzaiemodiiete cherez API na osnovi sesii ta otrymyiete podii cherez Server-Sent Events.

Tsiny:

• Agent SDK: tilky standartni taryfy na tokeny Claude API. Khostynh na vashii storoni.
• Managed Agents: taryfy na tokeny plius 0,08 USD za hodynu sesii (taryfikatsiia pomilisekundno).

Naikrashchi praktyky dlia produktsii

1. Zavzhdy izoliuite

Nikoly ne zapuskaiite ahentiv z neobmezhenymy dozvolamy na produktsiinii mashyni. Vykorystovuiite konteinery (Docker, Fly.io, Modal) abo izoliovani seredovyshcha (E2B, Vercel Sandbox).

2. Obmezhuite dostup do instrumentiv

Dotrymujtesia pryntsypu naimenshykh pryvileiv. Ahentu, shcho heneruie zvity, ne potribni Bash abo Write.

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

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

3. Vykorystovuiite hooks dlia zakhysnykh mekhanizmiv

Hooks dozvoliaiut perekhopliuvaty vyklyky instrumentiv do ta pislia vykonannia. Vykorystovuiite ikh dlia lohuvannia, validatsii ta obmezhhennia chastoty.

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. Obrobliajte pomylky elehantno

Tsykl ahenta mozhe heneruvaty pomylky - zboi instrumentiv, limity API, perepovnennia kontekstnoho vikna. Zavzhdy pereviriate typy povidomlen.

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. Monitorte vykorystannia tokeniv

Tsykly ahentiv mozhut spozhyvaty znachnu kilkist tokeniv, osoblyvo z velykymy bazamy kodu. SDK vkliuchaie avtomatychnu kompaktsiiu kontekstu, ale vy vse odno povynni monitory vykorystannia.

Vysnovok

Claude Agent SDK peretvoriuie LLM z mashyny dlia vidpovidei na pytannia u shchos blyzhche do junior-rozrobnyka. Vashi ahenty mozhut chytaty, pysaty, vykonuvaty, pereviryaty ta iteruvaty - toi samyi workflow, yakoho dotrymuietsia liudyna.

Pochnit z maloho: stvori ahenta z kilkoma vbudovanymy instrumentamy. Potim dodaite vlasni MCP-instrumenty dlia vashoi konkretNoi oblasti. Mashchanuiite do orkestratsii kilkokh ahentiv, koly vashi protsesy vymahaeiut spetsializatsii.

Tsykl ahenta - toi samyi, shcho stoiit za Claude Code. Yakshcho vin mozhe stvoriuvaty prohramne zabezpechennia, vashi ahenty tezh zmozhut.

Chek-lyst dlia pochatku:

• Vstanovit SDK (npm install @anthropic-ai/claude-agent-sdk)
• Vstanovit ANTHROPIC_API_KEY u vashomu otochenni
• Stvority prostoho ahenta z vbudovanymy instrumentamy (Read, Glob, Grep)
• Dodaty vlasnyj instrument cherez in-process MCP-server
• Pidkliuchyty zovnishnij MCP-server (GitHub, PostgreSQL, toshcho)
• Realizuvaty orkestruvannia kilkokh ahentiv z sub-ahentamy
• Nalashtuvy izoliovane seredovyshche dlia produktsii
• Dodaty hooks dlia lohuvannia ta zakhysnykh mekhanizmiv