Урок 22Продвинутое

Agent SDK

Программный доступ

Что такое Claude Agent SDK

Claude Agent SDK — это библиотека, которая позволяет запускать того же агента, что и в терминале, прямо из вашего кода на Python (пакет claude-agent-sdk) или TypeScript (пакет @anthropic-ai/claude-agent-sdk), без интерактивного диалога. Если CLI вы открываете руками и ведёте переписку, то SDK вызывается из скрипта: вы передаёте промпт (prompt) и опции (рабочую директорию, модель, режим разрешений), а агент сам читает файлы, редактирует их, запускает команды и по мере работы отдаёт поток сообщений. Именно это превращает Claude Code из инструмента для ручной работы в строительный блок для автоматизаций, конвейеров CI/CD и встроенных в продукт ассистентов.

Как это работает на примерах

Блоки кода на Python и TypeScript выше показывают минимальный сценарий: вы вызываете функцию query() с текстовой задачей вроде «почини падающие тесты в auth.ts» и объектом опций, где указываете путь к проекту. query() — это асинхронный генератор: он не возвращает один результат, а стримит объекты сообщений (AssistantMessage, ResultMessage и другие) по мере того, как агент выполняет шаги. Вы перебираете их в цикле async for (Python) или for await (TypeScript); финальный ResultMessage несёт итог работы и статистику использования токенов. Никакого объекта вида { output, cost } нет — данные приходят потоком. Команды в блоке неинтерактивного режима делают то же самое из терминала: флаг -p (он же --print) выполняет задачу разово и завершается, --model выбирает модель (например, Sonnet), --permission-mode acceptEdits отключает подтверждения, а --mcp-config подключает внешние инструменты через протокол MCP. Это удобно для разовых скриптов и cron-задач, где не нужен полноценный код на SDK.

Конфигурация для GitHub Actions показывает, как встроить агента в автоматический код-ревью: при каждом открытии или обновлении pull request workflow выкачивает код и запускает официальный action, передавая ему промпт с критериями ревью и два секрета — токен GitHub и ключ ANTHROPIC_API_KEY. Ключи всегда хранят в секретах репозитория, а не в коде. Главные подводные камни при работе с SDK: обязательно ограничивайте число шагов опцией maxTurns, чтобы агент не зациклился и не сжёг бюджет; чтобы агент работал без подтверждений, задавайте permissionMode: ‘acceptEdits’; обрабатывайте таймауты и ошибки, потому что в автоматическом режиме некому вмешаться вручную; и следите за расходом токенов из ResultMessage, так как массовые запуски на каждый PR быстро накапливают расходы. Начинайте с CLI для отладки промпта, а на SDK переходите, когда сценарий стабилен и его нужно повторять.

SDK vs CLI: когда что использовать

CLI (Interactive)

• Интерактивная разработка
• Отладка и исследование
• Одноразовые задачи
• Обучение и эксперименты

SDK (Programmatic)

• CI/CD автоматизация
• Пакетная обработка
• Интеграция в приложения
• Кастомные workflow

Неинтерактивный режим (CLI)

Флаг -p / --print запускает Claude Code без интерактивного диалога — выполняет задачу и завершается:

# Non-interactive (print) mode - run once and exit
claude -p "Fix all TypeScript errors"

# With specific model
claude -p "Add tests for UserService" --model sonnet

# Auto-approve edits (no permission prompts)
claude -p "Refactor the auth module" --permission-mode acceptEdits

# With MCP servers
claude -p "Query database for users" --mcp-config ./mcp.json

-p / --printНеинтерактивный режим, разовый запуск

--modelВыбор модели

--permission-modeНапример, acceptEdits — без подтверждений

--mcp-configПодключение MCP-серверов

Примеры SDK

# pip install claude-agent-sdk
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",
        permission_mode="acceptEdits",  # auto-approve edits, no prompts
        max_turns=10,
    )

    # query() is an async generator: it streams messages as the agent works
    async for message in query(
        prompt="Fix the failing tests in auth.ts",
        options=options,
    ):
        # AssistantMessage, ResultMessage, etc. arrive here
        print(message)

anyio.run(main)

GitHub Actions

Интеграция Claude Code в CI/CD через GitHub Actions:

name: Code Review with Claude

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Claude Code Review
        uses: anthropic/claude-code-action@v1
        with:
          prompt: |
            Review this PR for:
            - Code quality issues
            - Security vulnerabilities
            - Performance problems

            Provide specific feedback with line numbers.
          github-token: ${{ secrets.GITHUB_TOKEN }}
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Примеры применения SDK

Автоматический код-ревью PR

Запускать ревью при каждом PR

PR opened

Генерация тестов

Автоматически писать тесты для нового кода

New file

Документация

Обновлять документацию при изменениях

Merge to main

Миграции БД

Генерировать миграции из описания

Manual

Советы по использованию SDK

1.Ограничивайте число шагов через опцию maxTurns
2.Обрабатывайте ошибки и таймауты
3.Берите итог и расход токенов из ResultMessage в стриме
4.Храните API ключи в секретах

Частые вопросы

Чем Claude Code SDK отличается от CLI?

CLI — это интерактивный режим, который вы открываете руками и ведёте переписку с агентом, удобный для отладки и разовых задач. SDK — программный интерфейс: вы вызываете того же агента из кода на Python или TypeScript, передаёте промпт и рабочую директорию, а результат получаете как структурированный объект. SDK нужен для автоматизаций, CI/CD и встраивания в приложения, где интерактивный диалог невозможен.

Как запустить Claude Code в headless режиме?

Используйте флаг --headless, который отключает интерактивные подтверждения, и --prompt с текстом задачи. Например: claude --headless --prompt "Fix all TypeScript errors". Дополнительно --model выбирает модель (например, Sonnet), --output сохраняет результат в файл, а --mcp-config подключает внешние инструменты через MCP. Это удобно для скриптов и cron-задач.

Как интегрировать Claude Code в GitHub Actions для код-ревью?

В workflow задаётся триггер на события pull_request (opened, synchronize). Шаги выкачивают код через actions/checkout и запускают официальный action anthropic/claude-code-action, которому передаётся промпт с критериями ревью и два секрета: GITHUB_TOKEN и ANTHROPIC_API_KEY. Ключи всегда хранятся в секретах репозитория, а не в коде. Так агент автоматически проверяет каждый PR на качество, безопасность и производительность.

Как контролировать расходы при использовании Claude Code SDK?

Ограничивайте число итераций агента флагом --max-turns, чтобы он не зациклился и не сжёг бюджет. Отслеживайте поле cost в объекте результата — оно показывает стоимость каждого запуска в долларах. В автоматических сценариях, например ревью на каждый PR, расходы накапливаются быстро, поэтому стоит обрабатывать таймауты и ошибки и заранее оценивать объём вызовов.

Этот урок — часть структурированного курса по LLM.

Мой путь обучения