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

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

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

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

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

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

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

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

Обзор Claude Agent SDK

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

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

Agent SDK нужен для того, чтобы взять агента, работающего в разделе «Код» (Claude Code) в Claude, и встроить его в собственные приложения и скрипты — за пределами этого интерфейса.

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

Ядро 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

Нужен Node.js 18 или новее либо Python 3.10 или новее (официальное руководство по быстрому старту).

Аутентификация: API-ключ, а не вход через claude.ai

SDK работает с API-ключом из переменной окружения ANTHROPIC_API_KEY. Чтобы работать через Amazon Bedrock, Google Cloud (версия, которую эксплуатирует Google) или Microsoft Foundry, задайте CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 или CLAUDE_CODE_USE_FOUNDRY=1 и настройте учётные данные соответствующего облака. SDK не загружает файлы .env автоматически, поэтому задайте переменную в той оболочке, где запускается агент. Настройка и цены Claude в Google Cloud разобраны в статье Claude в Vertex AI.

Отдельно об учётных записях claude.ai (подписки Pro, Max и другие). Без предварительного одобрения официальная документация не разрешает сторонним разработчикам предлагать в своих продуктах вход через claude.ai или его лимиты использования — в том числе в агентах, созданных на Agent SDK. Приложения, которые вы делаете на SDK, должны проходить аутентификацию по API-ключу.

Минимальный агент (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)
            if message.total_cost_usd is not None:
                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);
  }
}

Вот и всё — этого достаточно, чтобы запустить агента, который читает файлы, ищет баги, исправляет их и отчитывается о результатах. Но учтите: allowed_tools — это не список инструментов, которыми Claude может пользоваться, а список инструментов, одобряемых автоматически, без запроса. Поскольку в примере указан Bash, выбранные Claude команды оболочки выполняются без подтверждения (кроме немногих действий, например некоторых удалений, которые не одобряет автоматически ни одна настройка). Поскольку в примере не задан permission_mode, режим берётся из permissions.defaultMode в файлах настроек, а если его нет — из встроенного значения по умолчанию; начиная с v2.1.285 это было auto в сессиях, которые не получают feature flags, например при стороннем провайдере (Bedrock, Google Cloud, Microsoft Foundry) или с отключённой телеметрией (официальная документация). Однако v2.1.302 (16 октября 2026 г.) это изменило: сессии Agent SDK и claude -p, в которых режим не задан, теперь стартуют в default, в том числе через сторонних провайдеров. Чтобы использовать auto, его нужно указать явно (в CLI — --permission-mode auto; история изменений, проверено 18 октября 2026 г.). Режим auto отбрасывает широкие разрешающие правила вроде Bash, поэтому, если вы рассчитываете на описанное поведение, явно передайте permission_mode="default" (TS: permissionMode: "default") (официальная документация). Запускайте такой пример в рабочем каталоге, который не жалко испортить. Как действительно ограничить набор инструментов — в следующем разделе.

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

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

Чтобы пользоваться встроенными инструментами, не нужно писать код их обработки. Главное — понимать, что «какие инструменты видит Claude» и «какие инструменты выполняются без запроса» — это разные настройки. Вот как это описывает официальная документация:

Например, если сочетать allowed_tools=["Read"] с permission_mode="bypassPermissions", одобряется всё, включая не перечисленные Bash, Write и Edit (официальная документация прямо предупреждает об этом сочетании). Чтобы инструмент был недоступен, уберите его через tools или disallowed_tools. Чтобы агент работал только с фиксированным набором, сочетайте allowed_tools с permission_mode="dontAsk" — этот режим отклоняет всё, что иначе потребовало бы подтверждения.

И ещё одна деталь: в macOS, Linux и WSL Glob и Grep не входят в набор инструментов по умолчанию (в Windows входят). Там Claude ищет через find и grep с помощью Bash. Если назвать любой из них в tools или 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-серверы и передаются агенту через mcp_servers (TS: mcpServers). Полное имя каждого инструмента имеет вид mcp__имя-сервера__имя-инструмента; чтобы он выполнялся без запроса, добавьте это имя в allowed_tools:

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

Если ваш инструмент выбросит исключение, агентный цикл не остановится. MCP-сервер SDK перехватит его и передаст Claude текст исключения как есть — в виде результата с ошибкой. Если же перехватить ошибку самостоятельно и вернуть "is_error": True (в TypeScript — isError: true), вы сами пишете сообщение, которое прочитает Claude: какой запрос не удался и что попробовать вместо него. В обоих случаях Claude может повторить попытку, выбрать другой инструмент или объяснить сбой (официальная документация: кастомные инструменты).

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

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

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

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

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

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

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

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

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

Разрешения, хуки и сессии

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

Разрешения: каждый вызов проверяется в фиксированном порядке

Когда Claude запрашивает инструмент, SDK проверяет хуки → правила запрета → правила подтверждения → режим разрешений → разрешающие правила → колбэк can_use_tool именно в таком порядке. Вызов, совпавший с правилом запрета (например, из disallowed_tools), блокируется даже в режиме bypassPermissions. Исключение: мод (плагин, чьи хуки — функции) работает и в сессиях Agent SDK, которые его загружают (официальная документация), а мод, отвечающий на tool.check, может одобрить вызов, отклонённый правилом запрета, кроме машин с управляемыми настройками и входа с планом Team или Enterprise (официальная документация). Устанавливайте моды только от авторов, которым доверяете; подробнее — в статье Моды Claude Code. Режим выбирается параметром permission_mode (по официальной документации на сентябрь 2026 года):

Хуки: свой код в ключевых точках

Хуки — это колбэки, которые срабатывают на события: перед запуском инструмента (PreToolUse), после него (PostToolUse) или при остановке выполнения (Stop). Они выполняются до проверки разрешений, поэтому действие, которое нужно блокировать в любом режиме, стоит запрещать здесь. Пример ниже (сокращённый пример из официальной документации) запрещает запись в файлы .env:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Сессии: продолжить с того же места или ответвиться

SDK автоматически сохраняет на диск историю диалога (промпты, вызовы инструментов, результаты и ответы) как сессию. Сохраните session_id из итогового сообщения и передайте его в resume при следующем query() — агент продолжит работу с учётом уже прочитанных файлов и принятых решений. Чтобы продолжить последнюю сессию, используйте continue_conversation=True (TS: continue: true); чтобы попробовать другой подход, не трогая исходную сессию, — fork_session=True (TS: forkSession: true). Сессия хранит только диалог: изменения файлов не откатываются (официальная документация: сессии).

Кроме того, навыки (skills), команды и память из каталога .claude/ вашего проекта и из ~/.claude/ загружаются автоматически, как в Claude Code. Плагины, объединяющие навыки, агентов, хуки и MCP-серверы, можно подключать по локальному пути.

Agent SDK vs Client SDK vs Claude Code

Официальное сравнение называет четыре способа разработки с Claude: Agent SDK, Claude Code CLI, Client SDK и Managed Agents. Начнём с трёх, которые вы запускаете на своём компьютере или сервере.

Как выбрать:

• Повседневная разработка → Claude Code CLI
• Построение системы автоматизации → Agent SDK
• Создание собственного ИИ-приложения → Client SDK
• Передать и эксплуатацию цикла и песочницы → Managed Agents (агент, размещённый Anthropic: сессии выполняются в облачной песочнице под управлением Anthropic или в собственной песочнице; доступ через SDK для вашего языка, CLI ant или REST API)

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

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

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

# Автоматическое исправление багов
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/xhigh/max)
)

На моделях, которые не поддерживают xhigh, он работает как high. Когда выполнение прерывает лимит, у итогового сообщения subtype равен "error_max_budget_usd" (для max_budget_usd) или "error_max_turns" (для max_turns), а result пуст (None). По subtype можно понять, почему агент остановился.

Имейте в виду: эта сумма — оценка, которую SDK считает по встроенной таблице цен, а не ваш реальный счёт. Бюджет учитывает только расходы самого вызова; траты сессии, продолженной через resume, в него не входят. Точные цифры смотрите на странице Usage в Claude Console или через Usage and Cost API (официальная документация: учёт расходов).

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

Чтобы Claude вообще не видел ненужных инструментов, перечислите в tools только нужные или уберите лишние по имени через disallowed_tools. allowed_tools лишь отключает запрос подтверждения и не сокращает набор инструментов. Список автоматически одобряемых инструментов тоже держите минимальным.

3. Сообщайте об ошибках инструментов через is_error

Исключение в кастомном инструменте не останавливает агентный цикл: SDK передаёт текст исключения Claude как результат с ошибкой. Но «сырого» текста исключения не всегда хватает, чтобы Claude решил, что делать дальше. Перехватите исключение сами и верните "is_error": True (в TypeScript — isError: true) вместе с описанием того, что не удалось и что попробовать вместо этого, — так Claude будет проще восстановиться.

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

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

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

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

Заключение

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

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

Если же вы не хотите самостоятельно управлять циклом, песочницей и состоянием, полностью управляемая альтернатива от Anthropic — это Claude Managed Agents.

О базовых возможностях Claude читайте также в статье Различия чата, Cowork и кода в Claude.