Skip to content

Agent SDK: программная интеграция возможностей Claude Code ​

📚 Навигация по серии: Предыдущая статья 44 GitHub Actions научила вас настраивать CI/CD для автоматического вызова Claude в репозитории через комментарии к PR. Эта статья делает следующий шаг — мы разберем, как использовать Claude Code как отдельную программную библиотеку, встраиваемую в ваши собственные приложения. Инструмент Agent SDK предоставляет официальный интерфейс для вызова агента Claude непосредственно из вашего кода.

Давайте сегодня поговорим об инструменте, который переводит вас из категории «пользователей» в категорию «создателей» решений на базе AI.

В предыдущих статьях мы выступали в роли пользователей Claude Code: запускали команду claude в консоли, общались с AI и наблюдали за изменением файлов. Но у программы есть и обратная сторона: её ядро — логический цикл «анализ-действие-проверка» и набор системных инструментов — можно вызывать напрямую из вашего программного кода.

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

Различие становится очевидным, когда вы пытаетесь создать простого бота для автоматического ревью пул-реквестов. При прямой работе с API моделей вам придется вручную писать логику обработки каждого действия: отправлять промпт, получать ответ с запросом инструмента («хочу прочитать файл X»), считывать файл на диске, передавать контент обратно в модель и повторять этот цикл. Использование Agent SDK полностью избавляет от необходимости писать этот служебный код — Claude самостоятельно считывает файлы, находит баги и вносит исправления с помощью встроенного цикла инструментов.

Прочитав эту статью, вы получите:

  • Понимание сути Agent SDK и того, какие части Claude Code вы можете использовать в своем коде.
  • Сравнение возможностей SDK и стандартного консольного интерфейса (CLI) — один движок, разные способы вызова.
  • Разницу между Agent SDK и классическими библиотеками API (Client SDK), избавляющую от написания лишнего кода.
  • Требования к установке библиотек для TypeScript и Python.
  • Шаблон кода минимального агента, способного самостоятельно найти и исправить ошибку в файле.
  • Критерии выбора: кому и в каких проектах необходим этот инструмент.

01 Какую логику предоставляет Agent SDK ​

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

В статье 03 мы разбирали цикл работы агента: «анализ → действие → проверка». Claude строит гипотезу, вызывает инструмент (чтение, запись, выполнение команды), оценивает результат и планирует следующий шаг. Консольная утилита claude предоставляет этот цикл в виде чата со встроенным набором инструментов (Read, Edit, Bash и др.).

Официальное описание SDK подтверждает:

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

Аналогия с профессиональной кофемашиной. Вы можете заходить в кофейню каждый день и заказывать готовый эспрессо у бариста — это использование консольной версии CLI. Но если вы открываете свою точку по продаже завтраков и хотите предлагать клиентам кофе того же качества, вы покупаете аналогичную кофемашину и встраиваете её в свою кухонную стойку. Вы сами решаете, когда запускать помол, какие зерна использовать и в какие наборы включать напиток. Agent SDK выступает в роли такой встраиваемой кофемашины — тот же внутренний механизм, но управляемый вашей программой.

В SDK доступны те же возможности, что и в CLI:

  • Встроенные инструменты: Read, Write, Edit, Bash, Glob, Grep, WebSearch готовы к вызову. Вам не нужно писать код для их выполнения.
  • Логический цикл: управление цепочкой вызовов инструментов берет на себя SDK.
  • Управление контекстом: хранение истории сообщений и прочитанных файлов происходит автоматически.
  • Расширения: поддержка MCP-серверов, системных событий (hooks), субагентов и настроек безопасности.

Примеры использования SDK в ваших проектах:

  • Интеграция с рабочими чатами (например, Slack-бот): разработчик отправляет в чат лог ошибки, бот запускает сессию Claude в репозитории для поиска проблемного места и возвращает готовое решение.
  • Автоматические фоновые проверки: скрипт по расписанию сканирует проект на предмет незавершенных задач (TODO) и формирует отчеты.
  • Создание специализированных AI-помощников: встраивание функций автономного редактирования файлов в ваши собственные инструменты разработки.

Для решения этих задач консольный интерфейс (CLI) неудобен, так как он ориентирован на интерактивное общение с человеком за экраном. Для автоматических процессов предназначен SDK.

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


02 Сравнение CLI и SDK: один движок, разные интерфейсы ​

Важное понимание: Agent SDK и консольная утилита CLI работают на одном логическом движке. Различие заключается лишь в способе взаимодействия — для человека или для программы.

Как указывает документация:

Одинаковые возможности, разные интерфейсы.

Аналогия с платежным терминалом. Покупатель может оплатить покупку на кассе через экран терминала, нажимая кнопки пальцем — это интерактивный интерфейс CLI, удобный для разовых ручных действий. Но тот же банк предоставляет API для интеграции оплаты на сайте, где транзакции запускаются программно без физического нажатия кнопок — это SDK, удобный для автоматической обработки потока платежей. Движок проведения транзакции один и тот же, различаются лишь способы инициации.

Критерии выбора инструмента:

ЗадачаРекомендуемый инструмент
Интерактивное написание и отладка кода в процессе работыCLI
Разовое выполнение команд разработчиком в консолиCLI
Запуск проверок в пайплайнах CI/CDSDK
Встраивание AI-функций в собственные сервисы и приложенияSDK
Фоновая автоматизация задач без участия человекаSDK

Главный вопрос при выборе: «кто запускает действие — разработчик вручную или программа по событию». Если требуется ручной контроль — запускайте CLI; если процесс автоматизирован — используйте SDK.

Опыт использования инструментов показывает:

Опыт написания правил и настройки контекста полностью переносим. Правила CLAUDE.md, структура промптов и конфигурация инструментов одинаково работают как в консоли, так и в коде SDK.

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

Схема взаимодействия с ядром представлена на рисунке:

布局: Две точки входа к ядру Claude Code: CLI для интерактивного ручного управления разработчиком, SDK для автоматического вызова из программного кода

Схема наглядно показывает: пользователь работает через CLI, программа вызывает функции через SDK, но оба пути ведут к общему логическому ядру Claude Code со встроенным набором инструментов.

💡 Резюме в одной фразе: CLI и SDK представляют собой два разных интерфейса к одному ядру. CLI ориентирован на ручную работу разработчика, а SDK — на автоматический запуск из кода программ. Опыт настройки правил для них полностью идентичен.


03 Отличие Agent SDK от классических библиотек API (Client SDK) ​

Этот раздел описывает разницу между программными инструментами, предотвращая написание избыточного кода.

Часто путают понятия «Client SDK» (официальные библиотеки API Anthropic для отправки запросов к моделям) и «Agent SDK». Оба инструмента позволяют вызывать Claude из кода, но решают задачи разного уровня.

Библиотека Client SDK предоставляет прямой доступ к модели: вы отправляете текст и получаете ответ, самостоятельно реализуя вызов инструментов. Agent SDK предоставляет готовую сборку Claude со встроенным механизмом выполнения инструментов.

Аналогия с покупкой продуктов. Client SDK похож на покупку ингредиентов для блюда в магазине. Вам привозят качественные продукты (модель), но готовить обед — чистить овощи, варить, жарить и следить за таймером — вы должны самостоятельно. Agent SDK похож на доставку готового горячего блюда из ресторана. Вы делаете заказ («приготовьте суп»), и вам привозят готовый результат.

Сравним программную реализацию вызова инструментов (на примере Python):

python
# Вариант 1: Использование Client SDK (ручная обработка цикла инструментов)
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    # Разработчик должен самостоятельно написать код выполнения инструмента
    result = your_tool_executor(response.tool_use)
    # И передать результат обратно модели для следующего шага
    response = client.messages.create(tool_result=result, **params)

# Вариант 2: Использование Agent SDK (автоматический цикл)
async for message in query(prompt="Исправь баг в файле auth.py"):
    print(message)

В первом варианте разработчик вынужден писать служебный цикл while, отслеживать статус tool_use, считывать файлы с диска на основе текстовых команд модели и возвращать строки обратно в API. Это требует написания сотен строк сложного кода обработки ошибок.

Во втором варианте (Agent SDK) весь служебный цикл скрыт внутри одной функции query(). Вы лишь передаете задачу, а программа самостоятельно открывает нужные файлы, вносит изменения и запускает тесты, возвращая вам поток статусных сообщений.

Различия библиотек:

ПараметрClient SDK (прямой API)Agent SDK (данный инструмент)
Результат вызоваТекстовый ответ моделиРаботающий агент
Выполнение инструментовПишется разработчиком вручнуюВыполняется SDK автоматически
Служебный цикл whileТребуется ручная реализацияСкрыт внутри библиотеки
Доступ к файловой системеОтсутствует (требует написания кода)Встроенные инструменты работы с файлами
ПрименениеПростые текстовые чаты, генерация контентаАвтономные агенты для работы с кодом

Если ваша цель — создать программу, способную самостоятельно анализировать структуру папок, читать и изменять файлы на диске, выбирайте Agent SDK. Прямой API (Client SDK) стоит использовать только в тех случаях, когда вам не нужен доступ к файловой системе и вы хотите полностью контролировать логику вызова модели на каждом шаге.

💡 Резюме в одной фразе: Главное отличие: Client SDK дает вам только текстовый ответ модели (вызовы инструментов вы пишите сами), а Agent SDK предоставляет автономного агента, который сам считывает файлы и выполняет команды на диске в автоматическом цикле.


04 Требования к установке и поддерживаемые языки ​

Разработчики предоставляют библиотеки для двух платформ: TypeScript (для Node.js-проектов) и Python. Они обладают идентичными возможностями и поддерживают одинаковые параметры вызова. Выбирайте язык, который является основным в вашем проекте.

Технические требования к установке библиотек:

ПараметрTypeScript (Node.js)Python
Команда установкиnpm install @anthropic-ai/claude-agent-sdkpip install claude-agent-sdk
Версия окруженияNode.js v18 или вышеPython v3.10 или выше
Установка CLI-версииНе требуется (SDK содержит встроенный бинарник)См. описание ниже

Установка библиотеки для TypeScript имеет особенность:

Библиотека TypeScript SDK содержит встроенный исполняемый файл Claude Code для целевой платформы, поэтому предварительная глобальная установка утилиты claude в систему не требуется.

Для Python-версии критичным требованием является версия Python не ниже 3.10. Попытка установить библиотеку на старые версии Python вернет ошибку отсутствия пакета в репозитории (No matching distribution found). Проверьте версию вашего интерпретатора перед установкой:

bash
python3 --version

При необходимости обновите версию Python в вашей системе.

Авторизация запросов ​

Для работы библиотек в системе должна быть объявлена переменная окружения с API-ключом Anthropic. Рекомендуется использовать файл .env в корне проекта:

bash
# Содержимое файла .env
ANTHROPIC_API_KEY=your-api-key

Ключ доступа создается в панели управления Anthropic Console (platform.claude.com). Добавьте файл .env в исключения .gitignore, чтобы избежать публикации ключа в репозитории (основы безопасности из статьи 04).

Правила тарификации при работе с SDK:

С 15 июня 2026 года использование Agent SDK и неинтерактивного режима claude -p в рамках платных подписок тарифицируется из отдельного лимита (Agent SDK quota), не пересекающегося с лимитами вашего интерактивного использования в консоли.

Учитывайте это правило при планировании расходов на автоматические тесты.

💡 Резюме в одной фразе: Библиотеки SDK для TypeScript (Node 18+) и Python (3.10+) идентичны по возможностям. Установка выполняется через стандартные менеджеры пакетов. Для работы требуется объявить переменную ANTHROPIC_API_KEY, а расходы на SDK тарифицируются отдельно.


05 Разбор структуры кода: функция query() ​

Основной точкой входа в библиотеку является асинхронная функция query(). Разберем пример её вызова.

Пример реализации на Python:

python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    # Асинхронный генератор возвращает поток сообщений от агента
    async for message in query(
        prompt="Найди и исправь ошибку в файле auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

Пример реализации на TypeScript:

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

async function main() {
  for await (const message of query({
    prompt: "Найди и исправь ошибку в файле auth.ts",
    options: { allowedTools: ["Read", "Edit", "Bash"] }
  })) {
    console.log(message);
  }
}
main();

Код состоит из трех основных элементов:

1. Функция query() — запускает логический цикл агента. Она возвращает асинхронный генератор (async iterator), что позволяет получать сообщения о работе агента в реальном времени по мере их генерации.

2. Параметр prompt — текстовое задание для агента (аналогично вводу в консоли CLI).

3. Блок options — параметры конфигурации. Наиболее важным свойством является allowed_tools (allowedTools в TypeScript) — список разрешенных для использования инструментов.

Выбор разрешенных инструментов определяет уровень доступа агента к системе:

Список инструментовУровень доступаОписание
["Read", "Glob", "Grep"]Только чтениеАгент может читать код, но не имеет права вносить изменения
["Read", "Edit", "Glob"]Чтение и редактированиеАгент может изменять код, но не может запускать команды сборки
["Read", "Edit", "Bash"]Полный доступАгент может изменять файлы и выполнять команды в терминале

Если вы хотите запустить безопасного агента для экспресс-аудита кодовой базы, передайте ему только инструменты чтения Read и Glob. Даже при наличии вредоносных инструкций в коде агент физически не сможет перезаписать файлы.

Для Python-разработчиков библиотека предоставляет класс ClaudeSDKClient, который сохраняет состояние сессии между несколькими последовательными вызовами query(), избавляя от необходимости вручную передавать параметры восстановления диалога. Это полезно при создании интерактивных чат-ботов.

💡 Резюме в одной фразе: Запуск агента выполняется функцией query(), которая принимает промпт и список разрешенных инструментов (allowed_tools), возвращая асинхронный поток сообщений о ходе выполнения задачи.


06 Практика: пишем скрипт автоматического исправления кода ​

Напишем работающий скрипт на Python, который запустит агента для автоматического поиска и исправления багов в коде. Мы создадим файл с ошибками и передадим его нашему агенту.

Перед запуском убедитесь, что у вас установлен Python версии 3.10 или выше, и настроена переменная ANTHROPIC_API_KEY в системе. Для работы требуется подключение к интернету.

Шаг 1: Создаем рабочую директорию

Выполните в терминале:

bash
mkdir my-agent && cd my-agent

Шаг 2: Настраиваем виртуальное окружение и устанавливаем библиотеку

bash
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Создайте файл .env в папке my-agent и добавьте ваш ключ:

bash
# Содержимое .env
ANTHROPIC_API_KEY=your-api-key

Шаг 3: Создаем тестовый файл с ошибками

Создайте файл utils.py с кодом, содержащим две потенциальные ошибки падения приложения (деление на ноль при пустом списке и обращение к ключу несуществующего объекта):

python
def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Шаг 4: Пишем код запуска агента

Создайте файл agent.py со следующим содержимым:

python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    print("Запуск агента для проверки utils.py...")
    # Запускаем цикл проверки
    async for message in query(
        prompt="Изучи файл utils.py на наличие багов, которые могут вызвать падение программы. Исправь найденные ошибки.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",  # Автоматически подтверждаем изменение файлов
        ),
    ):
        # Выводим только текстовые размышления Claude и имена инструментов
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Вызов инструмента: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Статус завершения: {message.subtype}")

asyncio.run(main())

В настройках мы указали параметр permission_mode="acceptEdits". Это разрешает Claude изменять файлы проекта без вывода интерактивных запросов подтверждения в консоли, что необходимо для автоматических скриптов.

Шаг 5: Запускаем скрипт

bash
python agent.py

Ожидаемый результат: в консоль начнет выводиться поток размышлений Claude. Вы увидите, как он решает прочитать файл utils.py (вызов инструмента Read), анализирует код, находит ошибки деления на ноль и отсутствия проверки на None, после чего вносит исправления (вызов инструмента Edit) и завершает работу со статусом success.

Шаг 6: Проверяем результат

Откройте файл utils.py. Код функций должен измениться — в них появятся проверки входных данных:

python
def calculate_average(numbers):
    if not numbers:
        return 0  # Защита от деления на ноль
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    if user is None or "name" not in user:
        return ""  # Защита от обращения к None
    return user["name"].upper()

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

💡 Резюме в одной фразе: Наш тестовый скрипт подтверждает: передача промпта в функцию query() с правами acceptEdits позволяет Claude самостоятельно считывать код, находить ошибки и сохранять исправления на диске.


07 Кому необходим инструмент Agent SDK ​

Использование SDK требует навыков программирования и не всегда является оптимальным выбором. Поможем вам определиться с необходимостью изучения этого инструмента.

Кому SDK не нужен: если ваша повседневная работа сводится к написанию кода под личным контролем в терминале (исправление багов, рефакторинг текущей папки, написание тестов), используйте стандартный CLI-интерфейс. Он проще в настройке и не требует написания служебных скриптов запуска.

Кому SDK необходим:

  • Разработчикам инструментов автоматизации: если вы хотите автоматизировать повторяющиеся многошаговые процессы (например, еженедельный аудит зависимостей во всех репозиториях компании с автоматическим созданием PR).
  • Создателям AI-интеграций: если вы хотите встроить функции автономного написания кода в свои продукты (чат-боты поддержки, внутренние админ-панели, специализированные редакторы кода).
  • Специалистам по автоматизации тестирования: для создания сложных сценариев динамического тестирования интерфейсов с помощью AI.

При масштабировании решений в промышленную эксплуатацию Anthropic предлагает следующий путь развития:

Обычной практикой является создание и тестирование прототипов решений локально с помощью Agent SDK, с последующим переносом логики на платформу управляемых агентов (Managed Agents) для промышленной эксплуатации.

Платформа Managed Agents от Anthropic берет на себя вопросы масштабирования, хранения истории сессий и запуска кода в безопасных облачных песочницах (sandboxes), избавляя вас от необходимости администрирования инфраструктуры серверов. Но точкой входа и прототипирования всегда служит Agent SDK.

💡 Резюме в одной фразе: SDK предназначен для создания автоматических скриптов и встраивания AI в свои программные продукты. Для повседневного написания кода используйте стандартный CLI. Разработка обычно начинается с прототипа на SDK и переносится в облако Managed Agents.


08 Заключение ​

Мы изучили возможности библиотеки Agent SDK для интеграции ядра Claude Code в программные продукты.

Резюмируем ключевые аспекты темы:

ВопросОтвет
Что такое Agent SDKБиблиотека для программного вызова ядра Claude Code в коде на Python и TypeScript
Связь с CLIОдин логический движок. CLI предназначен для ручной работы, SDK — для автоматического запуска из кода
Отличие от APIAPI требует ручного написания цикла обработки инструментов, SDK берет этот цикл на себя
УстановкаПакеты claude-agent-sdk для Python (3.10+) и TypeScript (Node 18+)
Точка входаАсинхронная функция query(), принимающая промпт и список разрешенных инструментов
БезопасностьСписок разрешенных инструментов (allowed_tools) жестко ограничивает права доступа агента к системе

Использование Agent SDK позволяет создавать интеллектуальных роботов-помощников, способных автономно работать с кодовой базой ваших проектов, решая задачи автоматического аудита, исправления ошибок и генерации тестов.


В следующей статье 46 «Настройка окружения разработчика» мы перейдем к техническим деталям развертывания. Как правильно управлять конфигурациями при работе в команде? Мы изучим правила разделения профилей (разработка, тесты, продакшн), способы безопасного управления переменными окружения на серверах и настройки кэширования для ускорения работы агентов.


Рекомендуемое чтение ​