Sozdanie AI-agentov s Claude Agent SDK: Prakticheskoe rukovodstvo

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:

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.

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