Собрать агента на Claude — это выстроить четыре слоя в рабочий контур: модель, память, инструменты и цикл действий, который сам повторяется до результата. Я, Арина Михална, не раз собирала такие для разбора заявок и автоматизации рутины, и каждый раз упираюсь в одно и то же: люди ждут волшебства, а на деле это просто правильная стройка блоков. Ниже — разбор без магии и без «просто напиши промпт и он всё сделает», с цифрами из практики.
Из чего состоит архитектура ИИ-агента Claude: четыре слоя
Первый косяк, на который я сама наступила — путаница между скиллом и агентом. Скилл — это инструкция, которую Claude читает один раз и выполняет. Агент — это система, которая сама решает, какую инструкцию читать дальше и повторять ли цикл, без твоего «давай теперь сделай вот это».
Архитектура ИИ-агента Claude держится на четырёх опорах:
1. Модель — сам Claude (Opus, Sonnet, Haiku в зависимости от задачи и бюджета). Мозг системы, который думает и решает.
2. Память — контекст текущей сессии плюс файл CLAUDE.md, который агент подтягивает при старте. Без хорошей памяти агент каждый раз просыпается с нуля и переспрашивает то, что ты уже объяснила. Я когда первый раз собирала агента для разбора входящих заявок, полдня потратила именно на память — казалось, что дело в инструментах, а на деле агент просто забывал контекст между шагами.
3. Инструменты — функции, которые агент может вызвать: прочитать файл, дёрнуть API, отправить сообщение, запросить подтверждение. Это руки агента. Границы доступа прописываются явно, иначе агент проявит инициативу там, где не просили.
4. Цикл — логика «подумал → сделал → проверил результат → решил, что дальше». Именно цикл отличает агента от обычного Claude: чат отвечает один раз, агент повторяет цикл столько, сколько нужно (или пока не кончится лимит).
| Слой | Что это | Пример |
|---|---|---|
| Модель | Какой Claude использовать | Sonnet 5 для баланса цены/качества, Opus для сложных задач |
| Память | Что агент помнит между шагами | CLAUDE.md с правилами: «если заявка без телефона — пометить неполной» |
| Инструменты | Что агент может делать | Читать почту, писать в таблицу, НО не отправлять письма без подтверждения |
| Цикл | Как агент повторяет действия | Максимум 7 итераций, выход при результате или ошибке |
Как собрать агента на Claude пошагово: от промпта до продакшена
Порядок сборки принципиален, менять местами не советую.
Шаг 1. Сформулируй задачу как результат, а не как процесс
Не «анализируй письма», а «каждый день в 8 утра проверь почту с фильтром “заявка”, вытащи имя и телефон из каждого письма, запиши в таблицу, отправь мне отчёт». Агент работает по цели, не по настроению.
Чёткая задача = 50% успеха. Расплывчатая задача = агент начинает импровизировать, и половина результатов неправильные.
Шаг 2. Опиши память в CLAUDE.md
Что агенту нужно помнить между запусками: формат таблицы, правила приоритета заявок, исключения, кому отправлять отчёт. Это не живёт в голове агента, это должно быть в файле. Я отдельно разбирала, что писать в CLAUDE.md, но коротко: пиши не «будь внимательнее», а «если поля меньше 5 символов — пропусти строку». Конкретика работает, философия нет.
Шаг 3. Выбери инструменты
Каждый инструмент — конкретное действие с чёткими границами: «может читать письма», «может писать в Google Sheets, но только в вкладку ‘заявки’», «не может отправлять письма без подтверждения». Либо встроенные в Claude Code, либо через MCP для внешних сервисов. Про MCP я разбирала отдельно, но суть простая: Claude SDK = встроенные инструменты, MCP = подключение к внешним сервисам.
Шаг 4. Собери цикл с жёстким лимитом шагов
Пропиши, сколько итераций агент может сделать, прежде чем остановиться и вернуть результат или спросить тебя. Пять-семь шагов для простой задачи — нормальный старт. БЕЗ ЛИМИТА агент будет крутиться, потому что всегда найдёт, что ещё можно улучшить.
# Пример структуры цикла на Python с Claude SDK
for step in range(MAX_STEPS): # MAX_STEPS = 5-7 для первого
агента
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=tools,
messages=messages
)
# Проверка: нужен ли ещё шаг или результат уже готов
if response.stop_reason == "end_turn":
break
# Обработка результата инструмента и добавление в
контекст
messages.append(process_tool_use(response))Шаг 5. Тестируй на понятных данных перед боем
Не на реальных клиентах в первый раз. Нужна тестовая выборка, где ты знаешь правильный ответ. Запусти агента 5–10 раз, посмотри, где он ошибается, поправь правила в памяти, повтори. Это занимает несколько часов, но экономит нервы.
Claude SDK vs LangChain vs LangGraph: что выбрать для первого агента
Здесь развилка, которая запутывает половину начинающих. Три способа собрать агента, и каждый звучит как «используй меня».
Claude SDK — прямая библиотека от Anthropic, без лишних слоёв. Документация чёткая, поддержка живая. Для первого агента это лучший выбор: меньше кода, больше понимания, что происходит. Мой совет: начни отсюда.
from anthropic import Anthropic
client = Anthropic()
messages = []
while True:
user_input = input("Задача для агента: ")
messages.append({"role": "user", "content": user_input})
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=TOOLS, # Твои инструменты
system=open("CLAUDE.md").read(), # Память агента
messages=messages
)
# Обработка ответа и tool calls...LangChain — фреймворк, который абстрагирует работу с разными моделями. Если завтра захочешь поменять Claude на GPT — просто переключишься. Но для первого агента это излишняя сложность: ты вместо 20 строк пишешь 50, и половину из них тратишь на понимание документации LangChain. Переходи сюда, когда поймёшь, что тебе реально нужна гибкость моделей.
LangGraph — строим на LangChain, это специально для сложных агентов с несколькими участниками, ветвлениями, откатами. Если ты ещё не писала первого простого агента — LangGraph забей на год. Сначала базу, потом красоту.
Мой тест: если можешь объяснить, зачем тебе нужен фреймворк, а не SDK — используй его. Если звучит, как «так все пользуются» — обойдись SDK, разберёшься быстрее.
Инструменты и MCP: как агент дотягивается до внешнего мира
Когда агенту нужно работать только с файлами в проекте — встроенные инструменты Claude Code справляются. Но если он должен читать почту, писать в CRM, запрашивать данные из базы — нужен MCP (Model Context Protocol).
MCP — это просто протокол, через который агент подключается к внешним сервисам. Без него ты пишешь интеграцию для каждого сервиса вручную. С MCP ты задаёшь правила один раз, и Claude сам решает, когда их использовать.
| Задача | Инструменты | Сложность |
|---|---|---|
| Работать с локальными файлами и папками | Встроенные Claude Code | Низкая — просто запусти Claude Code |
| Читать почту, писать в Google Sheets | MCP-сервер для Gmail + MCP для Google Workspace | Средняя — час настройки |
| Одновременно работать с почтой, CRM, базой | Несколько MCP-серверов + явные границы доступа | Высокая — день на интеграцию и тестирование |
| Работать в реальном времени в Telegram | API Telegram + цикл с обработкой ошибок и повторами | Высокая — потребуется серверная часть |
Первый агент без MCP запускается за два часа. С MCP — добавляет день на настройку и отладку интеграций.
Память агента: CLAUDE.md как спасение от забывчивости
CLAUDE.md — это файл контекста, который Claude Code читает при каждом запуске. Это спасение от того, что агент переспрашивает одно и то же каждый раз.
Что писать в память: не придумывай философию, пиши конкретику.
Плохо:
Ты опытный аналитик, внимательный и дотошный.Хорошо:
Правило 1: Если название заявки меньше 3 слов — пометить как
подозрительную, не обрабатывать.
Правило 2: Если телефона нет — поместить в отдельную таблицу
с пометкой "нужна ручная проверка".
Правило 3: Если сумма больше 100 000 — уведомить босса перед
обработкой.Агент следует конкретным правилам, не интерпретирует размытые указания. Это спасает половину ошибок.
Три типичные ошибки при сборке автономного агента своими руками
Я видела десятки самодельных агентов, и они падают почти всегда по одной из трёх причин.
Ошибка 1: Нет лимита цикла Агент решает, что ещё можно что-то улучшить — и крутится, потребляя токены и время. На практике: агент за час работы потратил 50k токенов вместо планируемых 500. Лимит в 5–7 шагов решает 90% этой проблемы.
Ошибка 2: Слишком широкие границы инструментов Дала агенту доступ «ко всей таблице» вместо «к одной вкладке» — получила правки там, где не просила, и испорченные данные в других местах. Границы доступа описывай в самом инструменте, и Claude их уважает.
Ошибка 3: Память живёт только в голове агента Перезапустила сессию — агент забыл все договорённости, которые вы обсуждали час назад. Результат: он начинает переделывать уже готовое или делает ошибки, на которые вчера уже указала. Сохраняй память в файле, а не в переменных сессии.
Как не потерять деньги: расход токенов и реальная стоимость агента
По нашим замерам, агент на базе Claude Sonnet 5 на задаче разбора писем потребляет примерно 15–20 инпут-токенов на письмо (запрос + контекст + инструмент) и 50–100 аутпут-токенов (результат). При подписке Pro на 20 $/месяц это примерно:
- 50 писем в день × 20 токенов × 30 дней = 30k входящих токенов в месяц
- Цена: ~0,5 $/месяц на входящих
Если запустить четыре таких агента параллельно — выйдет ~2 $/месяц, и всё равно укладываешься в лимиты Pro. Max-подписка (100 $/месяц) имеет смысл, если задач в 10 раз больше.
Типичная ошибка: агент зависает в цикле и потребляет в 100 раз больше токенов. Поэтому лимит шагов — не мелочь, а основной инструмент контроля стоимости.
Уровни автономности: от чат-бота до полноценного агента
Перед тем как собирать сложный агент — посмотри, какой уровень тебе реально нужен. Часто хватает второго-третьего, а не последнего.
| Уровень | Что делает | Сложность сборки | Пример |
|---|---|---|---|
| 0. Чат | Отвечает на вопрос | Минимум (есть в web) | Обычный диалог с Claude |
| 1. Скилл | Выполняет одну инструкцию по запросу | Низкая (~30 мин) | Скилл на генерацию отчёта по шаблону |
| 2. Инструментальный агент | Сам выбирает 1–2 инструмента для задачи | Средняя (~3 часа) | Агент, который читает файл и правит таблицу |
| 3. Циклический агент | Повторяет цикл до результата | Средняя (~5 часов) | Агент, разбирающий заявки каждый день в одно время |
| 4. Мультиагентная система | Несколько агентов передают друг другу задачи | Высокая (~день) | Один собирает данные, второй проверяет, третий отчитывается |
Мой совет: начни с уровня 2, дай ему поработать неделю, посмотри, где он ошибается, и только потом добавляй цикл (уровень 3). Прыгать сразу на мультиагентность (уровень 4) — это как учиться водить на скоростной трассе.
Отладка и логирование: как понять, что не так в цикле агента
Когда агент начинает ломаться — логирование спасает вечер. Что логировать: каждый step цикла, какой инструмент выбрал, что получил на входе, что вывел.
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("agent")
for step in range(MAX_STEPS):
logger.info(f"Step {step}: Starting iteration")
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=tools,
messages=messages
)
logger.debug(f"Claude response: {response.stop_reason}")
if response.stop_reason == "end_turn":
logger.info(f"Agent finished after {step} steps")
breakЛогирование каждого шага спасает тебя от слепого угадывания. Видишь, на каком шаге агент начал валиться, читаешь context — и сразу понятно, где проблема.
Сравнение Claude SDK с готовыми скиллами и фреймворками
Таблица для выбора: что использовать под конкретную задачу.
| Инструмент | Когда использовать | Плюсы | Минусы |
|---|---|---|---|
| Claude SDK (Python) | Первый агент, простая задача | Просто, документация ясная, поддержка от Anthropic | Нужен Python, нельзя одной строкой переключиться на другую модель |
| Готовые скиллы | Задача, которая уже решена в каталоге | Быстро, не нужно писать код | Часто не подходят на 100%, требуют доработки |
| LangChain | Нужна гибкость: сегодня Claude, завтра GPT | Поддерживает много моделей, сообщество большое | Лишняя абстракция для первого агента, документация запутанная |
| LangGraph | Сложный агент с ветвлениями и откатом | Visualize граф агента, встроенный state management | Для простого агента — огромный overkill |
| Cursor + Claude Code | Быстрая сборка без серверной части | Визуальный редактор, не нужен Python | Ограничения по интеграциям, контекст больше и токены дороже |
Мой выбор для первого агента: Claude SDK на Python, локальный запуск, локальная память в CLAUDE.md. Всё просто, всё работает, всё можно отладить.
Реальный кейс: как я собрала агента для разбора заявок и что ломалось
Я берусь на пример из своей практики. Нужно было автоматизировать разбор входящих писем: выцепить имя, телефон, сумму, загрузить в таблицу. Наивно думала, что это займёт час, но пришлось две ночи сидеть.
День 1. Версия 1 — просто чат
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
messages=[{"role": "user", "content": email_text}]
)Результат: половину писем обработал правильно, половину — нет. Контекст не запоминается. Каждый раз начинает с нуля.
День 1. Версия 2 — добавила память в CLAUDE.md Прописала правила: если телефона нет, пометить неполной; если сумма сомнительная (выше 1М), уведомить. Результат: ошибок на 40% меньше, но агент всё равно переделывает уже обработанные письма.
День 2. Версия 3 — добавила цикл с лимитом и таблицу в инструменты Агент сам решает, когда письмо разобрано, и когда нужно ещё раз проверить. Добавила лимит 3 шага максимум. Результат: стабильно обрабатывает, цена за письмо упала с 500 токенов до 150. Ошибок почти нет.
День 2. Версия 4 — финальная Добавила границы доступа: агент может писать только в таблицу ‘заявки’, не может трогать другие. Добавила проверку: если статус уже ‘обработано’ — пропустить. Это сняло 80% оставшихся косяков.
Вывод: не нужна магия, нужна правильная архитектура и граница доступа. А ещё терпение и 10 проверочных прогонов перед продакшеном.
Типичные ошибки при переносе агента в продакшен
Когда агент работает на локалке — одно дело. Когда крутится на сервере 24/7 — совсем другое. Три типичных косяка, которые я встречала:
Ошибка 1: Обработка таймаутов API Claude может упасть или ответить с задержкой. На локалке это видно сразу. На сервере агент просто зависает. Нужен таймаут с повторами:
import time
from anthropic import APITimeoutError
max_retries = 3
for attempt in range(max_retries):
try:
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=tools,
timeout=60.0,
messages=messages
)
break
except APITimeoutError:
if attempt < max_retries - 1:
time.sleep(2 ** attempt) # Exponential backoff
else:
raiseОшибка 2: Потеря данных между запусками Если агент готовит отчёт, а сервер упал на середине — отчёт потеряется. Сохраняй состояние в БД или файл между запусками. Хотя бы чтобы не переделывать уже готовое.
Ошибка 3: Токены и расходы уходят в небо На локалке видно, сколько потратил. На сервере можно просмотреть только в консоли Anthropic. Добавь логирование расхода токенов для каждого запуска, иначе счёт будет сюрприз.
logger.info(f"Input tokens: {response.usage.input_tokens},
Output tokens: {response.usage.output_tokens}")Сравнение автономности: когда кликать нужно вручную, а когда агент работает сам
Не все агенты одинаковые. Вот разбор — какой уровень под какую задачу:
Уровень 1–2: Пассивные агенты — работают по запросу, не кликуют сами. Используй для одноразовых задач. Первый агент всегда начни отсюда.
Уровень 3–4: Активные агенты — запускаются по расписанию или триггерам (новое письмо пришло). Это уже требует серверной части, но результат того стоит.
Уровень 5: Полностью автономные — агент сам решает, когда запуститься, что проверить, кого позвать на помощь. Это уже не агент, это почти человек. На практике используется редко, потому что требует очень чёткой границы доступа.
Для большинства задач хватает уровня 3 — запуск по времени + инструменты. Не усложняй раньше времени.
Типичные вопросы при сборке агента
Скилл vs агент — в чём разница? Скилл — это инструкция в файле, которую Claude выполняет один раз по твоей команде. Агент — система, которая сама решает, какой скилл применить, и повторяет цикл. Скилл — пассивный, агент — активный.
Могу ли я использовать один агент для разных задач? Технически да, но в практике плохая идея. Каждый агент лучше привязать к одной задаче: агент для писем, агент для заявок, агент для поддержки. Так проще дебажить и контролировать косяки.
Что делать, если агент ошибается? Первое: проверить память (CLAUDE.md). Второе: добавить конкретное правило в ответ на ошибку. Третье: уменьшить лимит шагов, если агент переделывает. Четвёртое: расширить тестовый набор данных.
Можно ли запустить агента на сервере, чтобы он работал автоматически? Да. Нужны: API-ключ Claude (генерируется в консоли), правило cron для запуска скрипта по расписанию, обработка ошибок и логирование. Я для своих агентов использую простой Python скрипт + systemd timer, работает стабильно месяцы.
По материалам: Building Effective Agents — Anthropic, Claude API Tool Use Documentation, Model Context Protocol; стоимость Claude Pro по официальной документации Anthropic.
Читайте также
- Кто за что: MCP, фреймворк в агентном стеке
- Claude-агент в 2026: как собрать своего первого агента
- Создание ИИ-агента в 2026: полный разбор от идеи до запуска
- Долгосрочная память агента Claude Code в 2026
- На портале «Мастерская нейросетей»: Как собрать маркетинг из нейросетей: Claude, агенты и автоматизация
Первого агента логичнее собрать не на полную архитектуру, а на уровень 2–3, где он просто следует инструкциям. Вот разбор, как собрать первого агента на Claude, там по шагам и без лишних слоёв. А если нужны примеры кода и живые кейсы — подписывайся на канал, там я показываю, как собрать агента на практике и что ломается по дороге.
