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/CD	SDK
Встраивание AI-функций в собственные сервисы и приложения	SDK
Фоновая автоматизация задач без участия человека	SDK

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

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

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

Вы можете отладить поведение агента в обычном чате, а затем перенести проверенный промпт и настройки в скрипт автоматизации на базе 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):

# Вариант 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-sdk	pip 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). Проверьте версию вашего интерпретатора перед установкой:

python3 --version

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

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

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

# Содержимое файла .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:

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:

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: Создаем рабочую директорию

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

mkdir my-agent && cd my-agent

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

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

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

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

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

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

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 со следующим содержимым:

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: Запускаем скрипт

python agent.py

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

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

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

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 — для автоматического запуска из кода
Отличие от API	API требует ручного написания цикла обработки инструментов, SDK берет этот цикл на себя
Установка	Пакеты claude-agent-sdk для Python (3.10+) и TypeScript (Node 18+)
Точка входа	Асинхронная функция query(), принимающая промпт и список разрешенных инструментов
Безопасность	Список разрешенных инструментов (allowed_tools) жестко ограничивает права доступа агента к системе

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

---

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

---

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

• Параллельный запуск: управление фоновыми сессиями
• Правила Conventional Commits: стандарты коммитов
• Контроль прав доступа: настройки ограничений в проектах