Claude Agent SDK:собираем своего агента

Этот гайд — для тех, кто уже освоился с Claude Code в терминале и хочет шаг дальше: встроить агента в собственный продукт. Telegram-бот, который сам чинит баги по тикету. Скрипт, который ночами разбирает входящие письма. Сервис, где агент — часть бэкенда. Всё это собирается через Claude Agent SDK — библиотеку, которая даёт движок Claude Code в виде кода. Тема техническая, поэтому термины разберём по дороге, но предполагается, что код ты хотя бы читаешь.

Часть 1 · Понятие

Что такое Agent SDK

Разберём слова. SDK (software development kit) — это набор кода, который ты подключаешь к своей программе как библиотеку, чтобы пользоваться чужой функциональностью. Agent — сам Claude, который умеет читать файлы, запускать команды и править код. Сложив, получаем: Claude Agent SDK даёт тебе того же агента, что живёт в Claude Code, но управляешь ты им из кода — вызовом функции, а не набором в терминале.

SDK выходит в двух вариантах под популярные языки. Для TypeScript/JavaScript — пакет @anthropic-ai/claude-agent-sdk, ставится через npm. Для Python — пакет claude-agent-sdk, ставится через pip. API в обоих почти зеркальный, поэтому выбираешь язык, на котором уже пишешь свой продукт.

# TypeScript / JavaScript — через npm
npm install @anthropic-ai/claude-agent-sdk

# Python — через pip (в виртуальном окружении)
pip install claude-agent-sdk

Терминал — это ты за рулём. SDK — это твоя программа за рулём, агент внутри неё.

Часть 2 · Разница

SDK против терминала

Когда ты работаешь в Claude Code из терминала, цикл простой: ты пишешь — агент отвечает — ты смотришь — пишешь снова. Через SDK этот цикл берёт на себя код. Твоя программа отправляет запрос, получает поток сообщений от агента и сама решает, что с ними делать: показать пользователю, записать в базу, дёрнуть следующий шаг.

Терминал и SDK — в чём отличие

Часть 3 · Код

Первый агент за пять строк

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    # Опции: системный промт, режим прав, рабочая папка
    options = ClaudeAgentOptions(
        system_prompt="Ты аккуратный Python-разработчик",
        permission_mode="acceptEdits",   # сам принимает правки файлов
        cwd="/home/user/project",
    )

    # query() возвращает поток сообщений — обходим его в цикле
    async for message in query(prompt="Сделай простой веб-сервер", options=options):
        print(message)


asyncio.run(main())

Тот же агент на TypeScript выглядит почти так же — меняются только синтаксис и имена опций (в TS они в camelCase):

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

// Поток сообщений обходим через for await
for await (const message of query({
  prompt: "Сделай простой веб-сервер",
  options: {
    systemPrompt: "Ты аккуратный разработчик",
    permissionMode: "acceptEdits",
    cwd: "/home/user/project",
  },
})) {
  console.log(message);
}

Часть 4 · Инструменты

Свои инструменты для агента

Настоящая сила SDK — когда агент умеет не только править код, но и выполнять твои действия. Это делается через инструменты (tools): обычные функции, которые ты помечаешь как доступные агенту. Он сам решает, когда их вызвать. Вот инструмент-калькулятор на Python:

from claude_agent_sdk import tool, create_sdk_mcp_server


# Помечаем функцию как инструмент: имя, описание, какие принимает аргументы
@tool("calculate", "Считает математическое выражение", {"expression": str})
async def calculate(args):
    result = eval(args["expression"], {"__builtins__": {}})
    return {"content": [{"type": "text", "text": f"Результат: {result}"}]}


# Собираем инструменты в локальный MCP-сервер — отдаём его агенту
my_server = create_sdk_mcp_server(name="utils", version="1.0.0", tools=[calculate])

Дальше этот сервер передают агенту в опциях и разрешают конкретные инструменты — что не разрешено, агент вызвать не сможет. Тема прав отдельно важна для безопасности, про неё — в гайде про права Claude Code. А что такое MCP вообще — в гайде про MCP-серверы.

Часть 5 · Граница

Когда SDK оправдан

SDK — мощный, но не бесплатный по сложности: это код, который надо писать и поддерживать. Чтобы не строить ракету ради поездки в магазин, держи в голове, где он реально окупается:

• Агент — часть продукта. Бот, сервис, веб-приложение, где Claude работает внутри без человека за клавиатурой.
• Нужна своя логика вокруг агента. Обработка каждого сообщения, ветвления, запись в базу, свои инструменты.
• Массовый поток задач. Сотни тикетов, писем, заявок, которые агент разбирает по расписанию.

Вопросы

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

Читать дальше

Соседние гайды