Claude Agent SDK daiot programmnyi dostup k tomu zhe tsiklu agenta, kotoryi stoit za Claude Code. Vashi agenty mogut chitat faily, vypolniat komandy obolochki, iskat v internete, redaktirovat kod, vyzyvat vneshnie API cherez MCP-servery i orkestirovat sub-agentov - vsio eto iz neskolkikh strok TypeScript ili Python.

V otlichie ot standartnogo Anthropic Client SDK, gde vy sami stroite tsikl instrumentov, Agent SDK vnutrenne obrabatyvaet vypolnenie instrumentov, upravlenie kontekstom, povtornye popytki i orkestratsiiu. Vy opisyvaete to, chto khotite, predostavliaete instrumenty, a agent razbiraitsia s ostalnym.

Arkhitektura

SDK sleduet prostomu tsiklu: soberi kontekst, vypolni deistvie, prover, povtori.

Osnovnaia tochka vkhoda - query(), kotoraia vozvrashchaet asinkhronny iterator, transliriuiushchii soobshcheniia po mere raboty agenta. Kazhdoe soobshchenie govori vam, chto delaet agent: razmyshliaet, vyzyvaet instrument, poluchaet rezultat ili dostavliaet itogovyi vyvod.

Nachalo raboty

Ustanovka

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

# Python
pip install claude-agent-sdk

Vam nuzhen API-kliuch Anthropic, ustanovlenny kak ANTHROPIC_API_KEY v vashem okruzhenii.

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

Vot i vsio. Agent ispolzuet Glob dlia poiska failov, Grep dlia poiska patternov TODO, Read dlia izucheniia sovpadenii i verniot strukturirovannoe reziume. Vy ne pishete logiku orkestratsii - SDK berot eto na sebia.

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

Vstroennye instrumenty

SDK postavliaetsia s temi zhe instrumentami, kotorye dostupny v Claude Code:

Instrument	Opisanie
Read	Chtenie soderzhimogo failov
Write	Sozdanie novykh failov
Edit	Tselevye pravki v sushchestvuiushchikh failakh
Bash	Vypolnenie komand obolochki
Glob	Poisk failov po patternu
Grep	Poisk v soderzhimom failov s pomoshchiu regex
WebSearch	Poisk v internete
WebFetch	Zagruzka URL i vozvrat ego soderzhimogo
AskUserQuestion	Zapros vvoda ot polzovatelia

Vy kontroliruete, kakie instrumenty agent mozhet ispolzovat, cherez allowedTools. Esli instrumenta net v spiske, agent ne mozhet ego vyzvat.

Rezhimy razreshenii

Poskolku agenty vypolniaiut nastoyashchie komandy na nastoyashchikh sistemakh, razresheniia vazhny.

Rezhim	Povedenie	Primenenie
default	Polzovatelsky callback canUseTool reshaet pri kazhdom vyzove	Tonkaia nastroika
acceptEdits	Avtoodobrenie failovykh operatsii, zapros dlia Bash	Rabochie protsessy razrabotki
dontAsk	Otkaz vo vsem, chto ne v allowedTools	Ogranichennye agenty
bypassPermissions	Avtomaticheskoe odobrenie vsego	Doverennye sandbox-sredy
auto	Klassifikator modeli reshaet o bezopasnosti	Sbalansirovannaia avtomatizatsiia

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

Dlia produktsionnogo ispolzovaniia vsegda zapuskaite agentov v izolirovannykh sredakh (konteinery, virtualnye mashiny) i ispolzuyte samyi strogiiy rezhim razreshenii, kotoryi vsio eshchio pozvoliaet agentu vypolniat svoiu rabotu.

Sozdanie polzovatelskikh instrumentov s MCP

Nastoiashchaia sila SDK zakliuchaetsia v rasshirenii agentov vashimi sobstvennymi instrumentami. Polzovatelskie instrumenty opredeliaiutsia kak in-process MCP-servery - bez upravleniia podprotsessami, bez setevykh nakladnykh raskhodov.

Primer: Instrument pogody

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

Polzovatelskie instrumenty sleduiut konventsii imenovaniia mcp__{imia_servera}__{imia_instrumenta}. Vy mozhete ispolzovat podstanovochnye znaki v allowedTools: "mcp__weather__*" razreshaet vse instrumenty s servera pogody.

Primer: Instrument zaprosov k baze dannykh

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

Podkliuchenie vneshnikh MCP-serverov

Pomimo in-process instrumentov, vy mozhete podkliuchatsia k liubomu sushchestvuiushchemu MCP-serveru - tem zhe serveram, kotorye rabotaiut s Claude Desktop, Cursor i drugimi MCP-klientami.

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 kombinirovat neskolko MCP-serverov. Agent vidit vse instrumenty so vsekh podkliuchennykh serverov i ispolzuet ikh po mere neobkhodimosti.

Orkestratsiia neskolkikh agentov

Dlia slozhnykh rabochikh protsessov vy mozhete opredelit spetsializirovannykh sub-agentov, kotorym roditelsky agent delegiruet zadachi. U kazhdogo sub-agenta svoi prompt, instrumenty i oblast fokusa.

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
}

Dobavte "Agent" v allowedTools roditelskogo agenta dlia vkliucheniia delegirovaniia. Sub-agenty rabotaiut so svoimi instrumentami i ne imeiut dostupa k instrumentam roditelia, esli eto ne predostavleno iavno.

Sessii i nepreryvnost

Agenty mogut sokhraniat kontekst mezhdu neskolkimi zaprosami s pomoshchiu sessii. Zakhvatite session_id iz pervogo vzaimodeistviia i peredaite ego v resume dlia poslesuiushchikh zaprosov.

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

Esli vy ne khotite razvorachivat infrastrukturu agenta samostoiatelno, Claude Managed Agents (zapushcheny v aprele 2026) predostavliaet polnostiu upravliaemyi oblachny servis. Anthropic zapuskaet konteinery, obrabatyvaet masshtabirovanie i predostavliaet streaming API.

Kliuchevoe razlichie: s Agent SDK vy zapuskaete tsikl agenta v svoei sobstvennoi infrastrukture. S Managed Agents Anthropic razmeshshaet i zapuskaet agenta za vas. Vy vzaimodeistuvete cherez API na osnove sessii i poluchaete sobytiia cherez Server-Sent Events.

Tseny:

• Agent SDK: tolko standartnye tarify na tokeny Claude API. Khosting na vashei storone.
• Managed Agents: tarify na tokeny plius 0,08 USD za chas sessii (tarifikatsiia pomillisekundno).

Luchshie praktiki dlia produktsii

1. Vsegda izoliruyte

Nikogda ne zapuskaite agentov s neogranichennymi razresheniiami na produktsionnoi mashine. Ispolzuite konteinery (Docker, Fly.io, Modal) ili izolirovannye sredy (E2B, Vercel Sandbox).

2. Ogranichivaite dostup k instrumentam

Sleduyte printsipu naimenshikh privilegii. Agentu, generiruiushchemu otchioty, ne nuzhny Bash ili Write.

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

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

3. Ispolzuyte hooks dlia zashchitnykh ograzhdenii

Hooks pozvoliaiut perekhvatyvat vyzovy instrumentov do i posle vypolneniia. Ispolzuyte ikh dlia logirovaniia, validatsii i ogranicheniia 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. Obrabatyvyte oshibki akkuratno

Tsikl agenta mozhet generirovat oshibki - sboi instrumentov, limity API, perepolnenie kontekstnogo okna. Vsegda proveryaite tipy soobshchenii.

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 ispolzovanie tokenov

Tsikly agentov mogut potrebliat znachitelnoe kolichestvo tokenov, osobenno s bolshimi bazami koda. SDK vkliuchaet avtomaticheskuiu kompaktsiiu konteksta, no vy vsio ravno dolzhny monitorit ispolzovanie.

Zakliuchenie

Claude Agent SDK prevrashchaet LLM iz mashiny dlia otvetov na voprosy v chto-to blizhe k junior-razrabotchiku. Vashi agenty mogut chitat, pisat, vypolniat, proveriat i iteirovat - tot zhe workflow, kotoromu sleduet chelovek.

Nachinte s malogo: sozdaite agenta s neskolkimi vstroennymi instrumentami. Zatem dobavte polzovatelskie MCP-instrumenty dlia vashei konkretnoi oblasti. Masshtabiruyte do orkestratsii neskolkikh agentov, kogda vashi protsessy trebuiut spetsializatsii.

Tsikl agenta - tot zhe, kotoryi stoit za Claude Code. Esli on mozhet sozdavat programmnoe obespechenie, vashi agenty toge smogut.

Chek-list dlia nachala:

• Ustanovite SDK (npm install @anthropic-ai/claude-agent-sdk)
• Ustanovite ANTHROPIC_API_KEY v vashem okruzhenii
• Sozdaite prostogo agenta so vstroennymi instrumentami (Read, Glob, Grep)
• Dobavte polzovatelsky instrument cherez in-process MCP-server
• Podkliuchite vneshni MCP-server (GitHub, PostgreSQL, i t.d.)
• Realizuyte orkestratsiiu neskolkikh agentov s sub-agentami
• Nastroite izolirovannuiu sredu dlia produktsii
• Dobavte hooks dlia logirovaniia i zashchitnykh ograzhdenii