← Университет

Claude Agent SDK: Полное досье на систему

Введение

Claude Agent SDK (ранее известный как Claude Code SDK, переименован в сентябре 2025) — это официальная библиотека от Anthropic для построения производственных AI-агентов. Это не просто обёртка над API: это полнофункциональная система для создания автономных агентов, которые могут читать файлы, выполнять команды, искать в веб, редактировать код и взаимодействовать с внешними системами через Model Context Protocol (MCP). SDK доступен на Python (3.10+) и TypeScript/Node.js (18+).

По словам разработчиков, SDK представляет собой "инфраструктурный слой Claude Code, выставленный как библиотека, которую можно применить к любой проблеме". За ним стоит полгода внутреннего развития в Anthropic, где были решены сложные проблемы управления памятью, разрешениями и координацией многоагентных систем.

Что это: определение и назначение

Claude Agent SDK — это программная библиотека, которая даёт вам доступ к мощи Claude как к инфраструктуре для автономных агентов. Вместо того чтобы самостоятельно реализовывать цикл обработки инструментов (tool loop), управлять контекстом и отслеживать состояние сессии, вы передаёте промпт функции query(), а SDK обрабатывает всю остальную логику.

Ключевое различие от Client SDK: - Client SDK (стандартный Anthropic SDK) — это прямой доступ к API. Вы отправляете промпты, получаете ответы и сами реализуете tool loop. - Agent SDK — это готовое решение, где Claude автономно выполняет инструменты, управляет контекстом и ведёт переговоры с окружающей средой.

# Agent SDK — вы передаёте задачу, SDK обрабатывает всё остальное
async for message in query(prompt="Найди и исправь ошибку в auth.py"):
    print(message)

Архитектура и ключевые концепции

Базовая архитектура

Архитектура SDK опирается на модель subprocess. Когда вы вызываете query(), SDK:

  1. Запускает отдельный процесс claude CLI
  2. Общается с ним по stdin/stdout
  3. Этот процесс владеет оболочкой, рабочей директорией и файлами сессии (JSONL) на диске
  4. Процесс вызывает api.anthropic.com для вызовов модели

Одна сессия агента = один subprocess. Несколько одновременных сессий = несколько subprocesses.

Встроенные инструменты (14+)

SDK предоставляет встроенные инструменты, доступные через строковые ссылки, без необходимости вручную определять JSON-схемы:

Инструмент Назначение
Read Читать любой файл в рабочей директории
Write Создавать новые файлы
Edit Делать точечные правки существующих файлов
Bash Выполнять команды терминала, скрипты, операции git
Monitor Следить за фоновым скриптом и реагировать на каждую строку вывода как на событие
Glob Находить файлы по паттерну (**/*.ts, src/**/*.py)
Grep Искать в содержимом файлов по regex
WebSearch Искать в веб текущую информацию
WebFetch Загружать и парсить содержимое веб-страниц
AskUserQuestion Задавать уточняющие вопросы пользователю
Agent Вызывать субагентов
Workflow Запускать динамические workflows (TypeScript SDK v0.3.149+)

Hooks (ловушки жизненного цикла)

Hooks позволяют вам запускать пользовательский код в ключевых точках жизненного цикла агента:

Используйте hooks для валидации, логирования, блокировки опасных операций или преобразования поведения агента.

Субагенты и оркестрация многоагентных систем

Это центральная особенность SDK. Вы определяете специализированных агентов с фокусированными задачами, а главный агент делегирует им работу:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="Специалист по проверке кода для обзоров безопасности и качества",
            prompt="Вы эксперт по проверке кода. Выявляйте уязвимости и предлагайте улучшения.",
            tools=["Read", "Grep", "Glob"],  # Только чтение!
        ),
        "test-runner": AgentDefinition(
            description="Запускает и анализирует test-suite",
            prompt="Вы специалист по выполнению тестов...",
            tools=["Bash", "Read", "Grep"],
        ),
    }
)

Ключевая особенность: каждый субагент работает в изолированном контексте. Промежуточные вызовы инструментов и результаты остаются внутри субагента; только финальное сообщение возвращается родителю. Это означает, что большие объёмы работы (например, обход сотен файлов) не загромождают главный контекст.

Паттерны оркестрации

  1. Контекстная изоляция: Многословная работа (тесты, сканирование документации) исполняется в субагентах, только результат возвращается в главное окно.

  2. Параллельный fan-out: Несколько независимых расследований выполняются одновременно. Каждый субагент возвращает свой результат, родитель синтезирует выводы.

  3. Pipeline/цепочка: Последовательные workflows выполняют субагентов по очереди, каждый потребляет результат предыдущего.

  4. Role Panels: Разные специализированные агенты рецензируют один артефакт с разных углов одновременно (например, scanner безопасности, проверка стиля, анализ покрытия тестами).

Данные наследуются субагентом только через prompt в инструменте Agent — единственный входной канал.

MCP (Model Context Protocol)

SDK имеет встроенную поддержку MCP, позволяя подключать внешние системы:

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
    }
)

Это даёт агенту доступ к браузер-автоматизации, базам данных, API и сотням других интеграций без необходимости управлять отдельными процессами MCP-серверов.

Сессии и управление состоянием

Сессии позволяют вам:

Сессии хранятся как JSONL-файлы на диске по умолчанию в ~/.claude/projects/. Они включают полную историю разговора, прочитанные файлы, выполненные команды и логику рассуждений.

Управление разрешениями

Строгая система управления разрешениями позволяет контролировать, какие инструменты может использовать агент:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],  # Pre-approve эти инструменты
    permission_mode="acceptEdits",  # Автоматически одобрять редактирование
)

Порядок оценки: hooks → deny rules → ask rules → permission_mode → allow rules → callbacks.

Память и контекст проекта

SDK поддерживает несколько уровней памяти:

  1. CLAUDE.md — файл памяти проекта в корне репозитория. Содержит инструкции, которые загружаются в system prompt.
  2. Auto-memory — автоматическое управление памятью в ~/.claude/projects/<project>/memory/
  3. Session-level — контекст, сохранённый в текущей сессии

Как работают субагенты и оркестрация

Жизненный цикл субагента

  1. Главный агент получает промпт от пользователя
  2. Claude решает, нужен ли субагент, на основе:
  3. Описания (description) каждого субагента
  4. Явного упоминания в промпте (например, "Use the code-reviewer agent")
  5. Главный агент вызывает инструмент Agent, передавая промпт делегирования
  6. SDK запускает новый subprocess для субагента
  7. Субагент выполняется в своём контексте с собственной system prompt и набором инструментов
  8. Только финальное сообщение субагента возвращается родителю
  9. Главный агент включает результат в свой ответ

Что наследует субагент

Наследуется Не наследуется
Собственная system prompt История разговора родителя
CLAUDE.md проекта Результаты инструментов родителя
Определения инструментов Преддефинированный контент навыков
Конфигурация MCP System prompt родителя

Параллелизм

Несколько субагентов выполняются одновременно. Время завершения = время самого медленного субагента, а не сумма всех времён.

Ограничения

Развёртывание на своём сервере

Модель subprocess

Так как SDK работает через subprocess, хостинг не похож на хостинг stateless API:

Паттерны сессий

  1. Ephemeral sessions — контейнер на одну задачу, затем уничтожается. Лучше для: проверка ошибок, извлечение данных, трансформация.

  2. Long-running sessions — постоянные инстансы контейнеров, обслуживающие множество SDK-процессов. Лучше для: email-агенты, chat-боты, непрерывная обработка.

  3. Hybrid sessions — ephemeral контейнеры, которые гидратируют из SessionStore при старте. Лучше для: intermittent work, deep research, customer support.

  4. Multi-agent container — несколько SDK-процессов в одном контейнере для близкого взаимодействия.

Требования к контейнеру

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

Провайдеры песочниц

Популярные варианты для развёртывания с изоляцией:

Персистентность состояния

По умолчанию состояние на диске теряется при перезагрузке контейнера. Для production:

  1. SessionStore adapter — зеркалирование трансценде в S3, Redis или Postgres
  2. Mounted volumes — для CLAUDE.md и артефактов рабочей директории
  3. Sync to object storage — периодическое сохранение

Мультитенантная изоляция

Для общего контейнера, обслуживающего нескольких tenants:

options = ClaudeAgentOptions(
    cwd=tenant_dir,
    setting_sources=[],  # Не загружать filesystem settings
    env={
        "CLAUDE_CONFIG_DIR": config_dir,
        "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",  # Отключить auto-memory
    },
)

Наблюдаемость (Observability)

SDK экспортирует OpenTelemetry сигналы:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

Отслеживайте: какие инструменты выполнялись, сколько они заняли времени, где застопорилась сессия.

Масштабирование

агентов на хост = (RAM хоста - overhead) / (потолок RAM на сессию)

Для долгоживущих сессий используйте consistent hashing по sessionId для pin session на одном контейнере.

Управление памятью и сессиями

Уровни памяти

  1. Project-level: CLAUDE.md в корне проекта. Загружается в system prompt.
  2. Auto-memory: Автоматическое управление в ~/.claude/projects/<project>/memory/
  3. Session-level: Временная память текущей сессии

Persistence

Поведение

Цена и экономика

Модель стоимости

  1. Основные расходы — tokens (доминирует в cost):
  2. Входные токены: стандартная цена
  3. Выходные токены: стандартная цена
  4. Cache read tokens: скидка (примерно 90% от input)

  5. Cache creation tokens: надбавка (примерно 125% от input)

  6. Инфраструктура — хостинг контейнера:

  7. Минимально провизионированный: ~$0.05/hour
  8. Но tokens обычно доминируют на порядок!

Отслеживание costs

async for message in query(prompt="..."):
    if isinstance(message, ResultMessage):
        print(f"Cost: ${message.total_cost_usd}")
        print(f"Input: {message.usage.get('input_tokens')}")
        print(f"Output: {message.usage.get('output_tokens')}")
        print(f"Cache read: {message.usage.get('cache_read_input_tokens')}")

Важно

Сильные стороны

  1. Встроенные инструменты — 14+ готовых tools, не нужно писать JSON-schema вручную
  2. Субагенты и оркестрация — clean task delegation с контекстной изоляцией
  3. Session persistence — разделение фаз read/write, контрольные точки перед дачей прав
  4. MCP native — встроенная поддержка Model Context Protocol без отдельных процессов
  5. Production-ready — 6 месяцев внутреннего развития в Anthropic, решены hard problems
  6. Полный контроль — hooks, permissions, resource limits на уровне библиотеки
  7. Prompt caching — автоматическое использование для снижения costs
  8. Cost tracking — подробные per-step, per-model, per-session метрики

Слабые стороны

  1. Claude-only — нет альтернативных провайдеров (GPT, Gemini и т.д.)
  2. Deployment complexity — subprocess model требует особого подхода к хостингу, не классический stateless API
  3. Cost concerns — agentic сессии могут быстро стать дорогими без budget safeguards
  4. API instability — API всё ещё развивается, V2 interfaces рядом с существующими паттернами
  5. Memory overhead — долгие сессии растут в памяти, нужна переработка
  6. Windows limitation — очень длинные промпты на Windows могут fail из-за 8191-char CLI limit
  7. No per-subagent wall-clock deadline — только maxTurns, no total timeout для каждого субагента

Для кого это предназначено

Идеально для

Не подходит для

Состояние проекта в 2026 году: жив ли он?

Активное развитие

GitHub활동

Поддержка

Вывод: Проект активно развивается, поддерживается Anthropic, используется в production системах. Это не экспериментальная технология.

Примеры реальных систем

Пример 1: Salon Booking Application (Totalum)

Агент может построить полное приложение salon-booking с использованием MCP-endpoints:

  1. Создание проекта через claude-scaffold MCP
  2. Генерация схемы базы данных для расписания
  3. Настройка Stripe для платежей
  4. Развёртывание Next.js приложения в продакшене

Всё это происходит автономно, без ручного написания Next.js кода.

Пример 2: Email Assistant

# Long-running container
async for message in query(
    prompt="Process incoming emails and respond",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "WebFetch", "WebSearch", "Agent"],
        agents={
            "email-classifier": AgentDefinition(...),
            "response-drafter": AgentDefinition(...),
        }
    )
):
    # Обработка сообщений как events
    # Продолжает работать, обслуживая входящие письма

Пример 3: Code Security Review Pipeline

Три субагента параллельно: - security-scanner — проверка уязвимостей - style-checker — соответствие style guide - test-coverage — анализ покрытия тестами

Главный агент синтезирует выводы в единый отчёт.

Пример 4: Research Agent

Агент самостоятельно исследует тему: 1. Поиск в веб (WebSearch) 2. Загрузка и парсинг статей (WebFetch) 3. Структурирование findings 4. Резюме с источниками

Это используется в production для автоматизированной research.

Сравнение с альтернативами

Claude Agent SDK vs Anthropic Managed Agents

Аспект Agent SDK Managed Agents
Где работает В вашем процессе Anthropic-инфраструктура
Interface Python/TS библиотека REST API
Где работает агент Ваши файлы и services Managed sandbox
Состояние сессии JSONL на диске Anthropic event log
Custom tools Python/TS функции MCP серверы
Лучше для Local prototyping, CI/CD Production async, multi-tenant

Рекомендуемый путь: Prototype с Agent SDK локально, потом migrate на Managed Agents для production.

Claude Agent SDK vs LangGraph

Аспект Agent SDK LangGraph
Models Claude only Multi-model
State Subprocess JSONL In-process dict
Complexity Simplified agent loop Full control
Production Works great Also excellent
Learning curve Lower (fewer concepts) Steeper (state graphs)

Выбирайте Agent SDK, если: - Вы используете Claude - Вам нужны built-in tools и простота - MCP-integration важна

Выбирайте LangGraph, если: - Вам нужна multi-model flexibility - Требуется сложная stateful логика - Нужен полный контроль над agent loop

Ключевые выводы

  1. Claude Agent SDK — это производственная система, не вспомогательная библиотека. Она решает hard problems вокруг agent lifecycle, permission management, session persistence.

  2. Субагенты — это differentiator. Контекстная изоляция позволяет масштабировать сложные workflows без загромождения главного контекста.

  3. Deployment is sophisticated. Subprocess model требует особого подхода: SessionStore для persistence, multi-tenant isolation, observability через OTEL.

  4. Costs доминируются tokens, не инфраструктурой. Budget safeguards обязательны для automation.

  5. In 2026, это активный проект с растущим production adoption. Anthropic инвестирует в развитие, экосистема растёт.

  6. Model lock-in — реальное ограничение. Если вам нужна multi-model flexibility, это critical consideration.

  7. Recommeneded path — начните с Agent SDK для prototyping, затем либо останьтесь (если Claude perfect fit), либо migrate на LangGraph (multi-model) или Managed Agents (fully hosted).

Источники