Что такое Claude Agent SDK? Полное руководство по разработке ИИ-агентов

«Дать ИИ задание — и он сам разберётся, что и как делать…» Именно эту мечту воплощают ИИ-агенты. Claude Agent SDK от Anthropic — это фреймворк для создания ИИ-агентов на Python или TypeScript, в основе которых лежит Claude. Эта же технология используется внутри Claude Code — официального CLI от Anthropic.

В этой статье мы подробно рассмотрим Claude Agent SDK: от основных концепций до практической реализации и сценариев применения.

Что такое ИИ-агент?

ИИ-агент принципиально отличается от обычного режима «вопрос — ответ». Его главная особенность — автономное разбиение задач на подзадачи, использование инструментов, анализ результатов и принятие решений о следующих шагах.

Например, если вы попросите агента «исправить баг в auth.py», он выполнит следующую последовательность действий:

1. Прочитает файл и разберётся в коде
2. Найдёт связанные файлы для понимания общей картины
3. Определит причину ошибки
4. Исправит код
5. Запустит тесты для проверки
6. Отчитается о результатах

Всё это выполняется без участия человека — агент сам принимает решения на каждом этапе. В этом и заключается его сила.

Обзор Claude Agent SDK

Claude Agent SDK — официальный фреймворк для разработки агентов от Anthropic. Он предоставляет программный доступ к тому же движку, на котором работает Claude Code.

Основные характеристики:

Из трёх режимов Claude — Чат, Cowork и Код именно Agent SDK является технологией, лежащей в основе режима Код (Claude Code).

Как работает агентный цикл

Ядро Agent SDK — это агентный цикл. Это механизм автоматического повторения последовательности: «Claude размышляет, использует инструмент, анализирует результат и снова размышляет».

Процесс выглядит следующим образом:

1. Получение запроса: пользовательская инструкция передаётся Claude
2. Анализ Claude: анализ инструкции и определение необходимых действий
3. Выполнение инструмента: вызов инструментов — Bash, Edit, Read и других
4. Обработка результата: результат выполнения возвращается Claude
5. Продолжение или завершение: если работа не закончена — возврат к шагу 2; если всё готово — возврат текстового ответа

Ключевой момент: цикл завершается, когда больше не нужны вызовы инструментов. Как только Claude решает, что инструменты больше не нужны, возвращается финальный текстовый ответ.

Начало работы: установка и базовый код

Установка

SDK доступен для Python и TypeScript.

# Python
pip install claude-agent-sdk

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

Минимальный агент (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Найди и исправь баг в src/auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            print(f"Стоимость: ${message.total_cost_usd:.4f}")

asyncio.run(main())

Минимальный агент (TypeScript)

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Найди и исправь баг в src/auth.py",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Вот и всё — этого достаточно, чтобы запустить агента, который читает файлы, ищет баги, исправляет их и отчитывается о результатах.

Встроенные инструменты

Agent SDK поставляется с набором готовых инструментов, которые можно использовать без написания дополнительного кода.

Чтобы использовать эти инструменты, достаточно указать их в allowed_tools. Писать код обработки самостоятельно не нужно.

Создание кастомных инструментов

Если встроенных инструментов недостаточно, можно создать собственные. Рассмотрим пример интеграции с API погоды.

Версия на Python

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "Получить текущую погоду для указанного города",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # В реальности здесь вызов API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"Погода в {city}: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

Версия на TypeScript

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "Получить текущую погоду для указанного города",
  { city: z.string().describe("Название города") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `Погода в ${args.city}: ${data}` }]
    };
  }
);

Кастомные инструменты создаются как MCP-серверы и подключаются к агенту. Важный момент: при ошибке не выбрасывайте исключение, а возвращайте isError: true. Это позволит агентному циклу продолжить работу, а Claude — попробовать другой подход.

Параллельная обработка с субагентами

Крупные задачи эффективнее разбивать на части и выполнять параллельно через субагентов. Это позволяет не засорять контекст (память) основного агента, делегируя специализированные задачи отдельным агентам.

Когда субагенты полезны

• Массовое тестирование: даже если логи тестов огромны, они не влияют на контекст основного агента
• Параллельное исследование: одновременный анализ нескольких модулей с получением только результатов
• Разделение обязанностей: «ревью кода» и «запуск тестов» выполняются разными агентами

Кастомные субагенты в Claude Code

В Claude Code (CLI) достаточно создать Markdown-файл в каталоге .claude/agents/, чтобы определить кастомного субагента.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: Агент, специализирующийся на ревью кода
tools: Read, Glob, Grep
model: sonnet
---

Вы — опытный ревьюер кода.
Проводите ревью с точки зрения качества кода,
безопасности и лучших практик.

Ограничение доступных инструментов (в примере выше — только чтение) предотвращает случайное изменение кода ревьюером.

Agent SDK vs Client SDK vs Claude Code

Claude предлагает три интерфейса для разработчиков, каждый со своими сильными сторонами. Выбирайте в зависимости от задачи.

Как выбрать:

• Повседневная разработка → Claude Code CLI
• Построение системы автоматизации → Agent SDK
• Создание собственного ИИ-приложения → Client SDK

Практические сценарии использования

Автоматизация разработки

Самый распространённый сценарий. Достаточно сказать «реализуй эту функцию», и агент изучит структуру файлов, напишет код и запустит тесты.

# Автоматическое исправление багов
async for msg in query(
    prompt="Тесты модуля аутентификации падают. Найди причину и исправь",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # Лимит $2
    ),
):
    pass

Интеграция в CI/CD-пайплайн

Можно настроить связку с GitHub Actions для автоматического ревью кода при создании PR или автоматического исправления при падении тестов.

Анализ данных и исследование

Агенту можно поручить многоэтапные задачи вроде «проанализируй логи за последний месяц и найди паттерны ошибок». В сочетании с WebSearch можно подключить и актуальную информацию из интернета.

Лучшие практики

1. Не забывайте о контроле затрат

Агент работает в цикле, поэтому расход токенов может оказаться больше ожидаемого. Обязательно устанавливайте max_budget_usd и max_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # Остановка при $5
    max_turns=30,           # Остановка после 30 итераций
    effort="medium",        # Глубина рассуждений (low/medium/high/max)
)

2. Минимизируйте набор инструментов

Разрешение ненужных инструментов впустую расходует контекстное окно. Указывайте в allowed_tools только те инструменты, которые действительно необходимы.

3. Обрабатывайте ошибки через isError

Если кастомный инструмент выбрасывает исключение, весь агентный цикл останавливается. Вместо этого возвращайте isError: true — тогда Claude сможет попробовать восстановиться.

4. Выносите тяжёлые задачи в субагентов

Запуск тестов, анализ логов и другие операции с большим объёмом вывода лучше делегировать субагентам, чтобы не перегружать контекст основного агента.

5. Формулируйте промпты конкретно

Вместо «улучши код» пишите «добавь ограничение частоты запросов в функцию логина auth.py и напиши тесты». Конкретные инструкции повышают эффективность агента.

Заключение

Claude Agent SDK — это фреймворк, который значительно упрощает разработку ИИ-агентов. Используя тот же движок, что и Claude Code, вы можете создавать автономных агентов на Python и TypeScript.

Рекомендуемый подход: сначала попробуйте Claude Code для интерактивного знакомства с возможностями агентов, а когда возникнет потребность в автоматизации — переходите на Agent SDK.

О базовых возможностях Claude читайте также в статье Три режима Claude: Чат, Cowork и Код — подробное сравнение.