Claude Agent SDK: как создавать агентов (2026)

TL;DR

• Claude Agent SDK — это библиотека Anthropic для создания AI-агентов в вашем собственном коде — тот же агентный движок, на котором работает Claude Code, доступный как claude-agent-sdk для Python (3.10+) и @anthropic-ai/claude-agent-sdk для TypeScript.
• В конце 2025 года он был переименован из `claude-code-sdk`; если в руководстве написано ClaudeCodeOptions, оно устарело — теперь класс называется ClaudeAgentOptions.
• Вы бесплатно получаете полный агентный цикл: инструменты для работы с файлами, Bash, веб-поиск, пользовательские инструменты через @tool, MCP-серверы (именно так вы подключаете Jira или Shopify), субагентов, хуки и разрешения. Вы платите только за токены Claude API.
• Он работает с Anthropic Messages API, поэтому вы можете направить его на шлюз через ANTHROPIC_BASE_URL — мы протестировали его с endpoint /v1/messages у Velokey, и он работает на одном ключе с оплатой по кредитам.

Сейчас все создают агентов, и большинство руководств останавливаются на быстром старте из десяти строк. Это руководство охватывает то, что происходит дальше: как установить его без распространенной ловушки с Node, как подключить реальные инструменты вроде Jira и Shopify, сколько на самом деле стоит запуск и как направить его через шлюз. Давайте разбираться.

Что такое Claude Agent SDK?

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

Важный контекст, который большинство людей упускает: раньше это называлось Claude Code SDK. Anthropic переименовала его в Claude Agent SDK в конце 2025, чтобы показать, что он предназначен для создания *любых* агентов, а не только инструментов для программирования. Пакет, импорты и один ключевой класс — все изменилось: claude-code-sdk стал claude-agent-sdk, а ClaudeCodeOptions стал ClaudeAgentOptions. Многие посты в блогах и ответы на Stack Overflow все еще ссылаются на старые названия, так что если ваш импорт не работает, обычно причина именно в этом.

Под капотом SDK оборачивает Claude Code CLI как подпроцесс. Ваш код на Python или TypeScript взаимодействует с SDK; SDK управляет встроенным CLI; CLI взаимодействует с Claude. Эта архитектура важна по двум причинам, к которым мы еще вернемся: CLI — это Node-бинарник (поэтому Node должен быть установлен даже для Python SDK), и CLI агрессивно кэширует промпт для своего системного промпта (что меняет ваши расчеты стоимости).

Как установить и использовать Claude Agent SDK?

Установите Claude Agent SDK из PyPI (или npm), задайте свой API-ключ и вызовите query() — рабочий агент занимает около десяти строк. Для Python нужна версия 3.10 или новее:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

Вот минимальный одноразовый агент. query() возвращает асинхронный итератор сообщений:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

Для всего интерактивного или многоходового используйте ClaudeSDKClient и настройте его с помощью ClaudeAgentOptions:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

Две проблемы установки, на которых часто спотыкаются, и ни одной из них нет в десятистрочном quickstart:

Что можно создать с Claude Agent SDK?

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

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

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Hooks и permissions — это то, что превращает демо во что-то, что можно запускать без присмотра. Hook PreToolUse может заблокировать команду Bash, которая соответствует опасному шаблону; permission_mode определяет, будет ли агент останавливаться для подтверждения или автоматически принимать правки. В production большинство команд начинают с узкого списка allowed_tools и расширяют его по мере роста доверия к агенту — в противоположность широко открытому quickstart.

Шестой блок, к которому обращаются, когда один агент начинает работать медленно, — это subagents. SDK может запустить нового sub-agent с собственным контекстом для выполнения ограниченной подзадачи, а затем вернуть результат обратно — Claude Code использует это, чтобы распараллеливать работу по файлам. Это встроенный ответ на вопросы «может ли он работать над несколькими вещами параллельно» и «как не дать основному контексту переполниться»: делегируйте шумную работу (чтение десяти файлов, запуск матрицы тестов) subagents, чтобы основной агент оставался сфокусированным. Session forking — связанный прием для ветвления уже идущего разговора.

Как интегрировать Jira или Shopify с Claude Agent SDK?

Вы интегрируете Jira, Shopify или любую внешнюю систему, добавляя ее MCP-сервер в mcp_servers в ClaudeAgentOptions — в SDK нет кода, специфичного для Jira, он работает с открытым Model Context Protocol, а Atlassian и Shopify поставляют MCP-серверы. Это ответ на самые частые вопросы об интеграции ("как подключить Jira/Shopify к Claude Agent SDK"): специального коннектора нет, вы регистрируете MCP-сервер и разрешаете его инструменты.

Шаблон одинаков для обоих случаев. Укажите SDK MCP-сервер (локальную команду или удаленный URL), затем разрешите инструменты, которые он предоставляет:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

Замените блок сервера на @shopify/mcp-server (с вашим токеном Shopify), и тот же агент сможет читать заказы или обновлять товары. Важно правильно настроить две вещи: имена инструментов следуют соглашению mcp__<server>__<tool>, поэтому записи в allowed_tools должны совпадать точно, и каждому MCP-серверу нужны собственные учетные данные в env. Если агент говорит, что инструмент недоступен, это почти всегда несовпадение имени или отсутствующий токен, а не ошибка SDK.

Если поставщик размещает удаленный MCP-сервер вместо локальной команды, зарегистрируйте его по URL, а не через command/args — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — и SDK подключится по сети. Локальные (stdio) серверы проще для разработки и хранят токен на вашей машине; удаленные (URL) серверы избавляют от необходимости что-либо устанавливать. В любом случае правила для allowed_tools и учетных данных для каждого сервера остаются теми же.

Как запустить Claude Agent SDK через шлюз?

Установите ANTHROPIC_BASE_URL на корневой адрес вашего шлюза, и SDK будет отправлять туда каждый запрос вместо api.anthropic.com — без изменения кода. SDK учитывает стандартные переменные окружения Anthropic, поэтому подойдет любой бэкенд, который предоставляет Anthropic Messages API (/v1/messages): корпоративный прокси, региональный мост или унифицированный шлюз.

Мы протестировали это с [Velokey](https://api.velokey.ai), который предоставляет Anthropic-совместимый эндпоинт /v1/messages. Живой запрос к нему вернул стандартный ответ Messages (stop_reason: end_turn, usage в формате Anthropic), что именно и ожидает SDK:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

Зачем вообще маршрутизировать агента через шлюз? Один ключ вместо отдельной учетной записи Anthropic, тарифа и настройки 30-дневного хранения; кредитная биллинговая модель, для которой можно задать лимит; и тот же ключ дает доступ к [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5) и другим моделям, которые вы можете использовать в других местах. Если вашему прокси нужен bearer token вместо заголовка x-api-key, задайте ANTHROPIC_AUTH_TOKEN, а не ANTHROPIC_API_KEY. Это та же идея drop-in-замены, что и при указании шлюза для OpenAI-совместимого инструмента — см. наше руководство по Qwen CLI для эквивалента в формате OpenAI.

Сколько стоит Claude Agent SDK?

Сам SDK бесплатный и с открытым исходным кодом — вы платите за токены Claude API, которые потребляет агент, а агенты потребляют их много. Каждый ход заново отправляет растущую беседу, каждый результат инструмента возвращается в контекст, и одна задача "fix this bug" может занять десять с лишним ходов. В этом и заключается неожиданность стоимости: код занимает десять строк, но счет за токены масштабируется в зависимости от того, насколько активно агент исследует задачу.

Три рычага помогают держать это под контролем, и самый важный из них SDK встраивает за вас:

Последняя строка реальна, а не теоретична: в нашем тестовом запросе ответ сообщил о десятках тысяч cache_read_input_tokens, что означает, что большой системный промпт был отдан из кэша примерно за одну десятую цены входных токенов, а не тарифицировался заново на каждом ходе. Это главная причина, по которой затраты на агентов не такие жесткие, как можно было бы подумать по числу ходов. Полную математику токенов по каждой модели см. в нашем руководстве по ценам Claude API; если вам нужен рабочий одиночный вызов модели Claude перед подключением агента, основы описаны в статье как вызвать Claude с API key.

Часто задаваемые вопросы

Что такое Claude Agent SDK?

Это официальная библиотека Anthropic для создания AI-агентов на Python или TypeScript, использующая тот же автономный агентный цикл, на котором работает Claude Code. Она берет на себя цикл вызова инструментов, файловые операции, выполнение команд и интеграции MCP, поэтому вы описываете цель и инструменты, а не оркестрацию. Вы платите только за токены Claude API.

Claude Agent SDK — это то же самое, что Claude Code SDK?

Да — это переименованная версия. Anthropic переименовала claude-code-sdk в claude-agent-sdk в конце 2025, а ClaudeCodeOptions стал ClaudeAgentOptions. Функциональность сохранилась; изменились только имена пакета и класса. Если в руководстве импортируются старые имена, оно было написано до переименования, и эти импорты не будут работать с текущим пакетом.

Как установить Claude Agent SDK?

Запустите pip install claude-agent-sdk (Python 3.10+) или npm install @anthropic-ai/claude-agent-sdk для TypeScript, затем задайте ANTHROPIC_API_KEY. Поскольку SDK запускает встроенный Claude Code CLI как подпроцесс, вам также нужен установленный Node.js, даже для пакета Python — отсутствие Node является самой распространенной причиной сбоя установки.

Как подключить Jira или Shopify к агенту Claude Agent SDK?

Добавьте MCP-сервер поставщика в mcp_servers в ClaudeAgentOptions и разрешите его инструменты. И Atlassian (Jira), и Shopify публикуют MCP-серверы, поэтому писать собственный коннектор не нужно — вы регистрируете сервер с его API-токеном и перечисляете его инструменты (с именами mcp__<server>__<tool>) в allowed_tools.

Работает ли Claude Agent SDK с gateway или proxy?

Да. Он учитывает переменную окружения ANTHROPIC_BASE_URL, поэтому направляет запросы на любой backend, который предоставляет Anthropic Messages API (/v1/messages), без изменения кода. Мы проверили живой запрос к Anthropic-совместимому endpoint Velokey. Используйте ANTHROPIC_API_KEY для proxy с x-api-key или ANTHROPIC_AUTH_TOKEN для proxy с bearer-token.

Какие модели использует Claude Agent SDK?

Он использует модели Claude через любой endpoint, на который вы его направите, — по умолчанию последнюю модель Anthropic, а конкретную можно задать через опцию model (например, claude-sonnet-5 или claude-opus-4-8). Через gateway можно выбрать любую модель Claude, которую обслуживает этот gateway, что удобно для использования более дешевой модели при рутинных запусках агента.

Claude Agent SDK бесплатен?

SDK бесплатен и имеет открытый исходный код, но запуск агента стоит токенов Claude API, а многоходовые агентные циклы быстро их расходуют. Контролируйте расходы, выбирая более дешевую модель для рутинной работы, задавая max_turns и ограничивая доступ к инструментам, — и полагайтесь на встроенное кэширование промптов, которое обслуживает повторяющийся системный промпт примерно за десятую часть цены входных токенов.