Когда ставить ИИ-агента, а когда скрипт с API-запросом?

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

Главная ошибка при проектировании ИИ-интеграций — считать агентом любой вызов языковой модели. Если приложение выбирает запись из базы, отправляет её в API, валидирует результат и публикует его, это не агент. Это обычный программный процесс с недетерминированной функцией внутри.

Если следующий шаг выбирает код — это скрипт или workflow. Если следующий шаг выбирает модель — это агент.

Anthropic проводит такое же архитектурное различие: в workflow модель и инструменты движутся по заранее заданным кодом маршрутам, а в агенте LLM динамически управляет собственным процессом и использованием инструментов. При этом практический совет остаётся консервативным: начинать с самого простого составного решения и усложнять систему только тогда, когда это действительно улучшает результат.

Что такое скрипт с API-запросом

В самом простом варианте языковая модель работает как функция:

входные данные
→ API модели
→ структурированный результат

Например:

текст статьи
→ сократить до 1 000 знаков
→ вернуть заголовок, анонс и основной текст

Приложение заранее знает:

• какие данные взять;
• какой промпт использовать;
• какую модель вызвать;
• в каком формате должен прийти ответ;
• как проверить результат;
• куда его сохранить;
• что делать при ошибке.

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

Типичная реализация:

async function rewriteArticle(articleId: string) {
const source = await getArticle(articleId);

const result = await generateStructuredText({
schema: RewrittenArticleSchema,
prompt: buildRewritePrompt(source),
});

const article = RewrittenArticleSchema.parse(result);

await saveDraft({
...article,
sourceArticleId: source.id,
});

return article;
}

Даже если модель внутри использует reasoning, с точки зрения архитектуры это остаётся одним API-вызовом, а не агентом.

Несколько вызовов модели — тоже не обязательно агент

Допустим, процесс выглядит так:

выбрать текст
→ определить тематику
→ написать новую версию
→ проверить факты
→ исправить замечания
→ сохранить

Если каждый следующий шаг вызывается кодом, это детерминированный LLM-workflow:

const category = await classify(source);
const draft = await rewrite(source, category);
const review = await reviewDraft(draft);

const finalDraft = review.approved
? draft
: await repairDraft(draft, review);

Здесь может быть три или четыре вызова модели, но модель не управляет маршрутом целиком. Код определяет операции, порядок, условия повторного вызова, максимальное число попыток и критерий успешного завершения.

Такой подход подходит для большинства контентных пайплайнов, каталогов, импортов, классификаторов и задач обогащения данных.

Что добавляет ИИ-агент

Агент появляется, когда модели передают часть управления процессом.

Вместо команды:

Перепиши этот текст.

модель получает цель и инструменты:

Найди в базе подходящие материалы и подготовь новую статью.

Инструменты:

• search_texts
• get_text
• find_related
• check_duplicate
• submit_draft

Теперь модель сама может решить:

1. сначала поискать тексты по теме;
2. открыть несколько найденных материалов;
3. изменить поисковый запрос;
4. посмотреть связанные записи;
5. проверить, не публиковалась ли похожая статья;
6. подготовить результат;
7. вызвать submit_draft.

Harness или agent runtime обслуживает цикл:

модель
→ вызов инструмента
→ результат инструмента
→ снова модель
→ новый инструмент
→ снова модель
→ финальный результат

OpenAI описывает agent run как цикл, продолжающийся до условия выхода: финального ответа, специального output-инструмента, ошибки или лимита шагов. Практический совет тот же: сначала максимально использовать возможности одного ограниченного агента и только затем переходить к multi-agent архитектуре.

Главный критерий: неопределённость результата или неопределённость маршрута

Результат заранее неизвестен, но маршрут известен

• неизвестно, какой заголовок напишет модель;
• неизвестно, к какой категории она отнесёт карточку;
• неизвестно, как именно будет переписан абзац;
• неизвестно, какие сущности будут извлечены из документа.

Но процесс известен:

получить данные
→ вызвать модель
→ проверить JSON
→ сохранить

Здесь достаточно функции с API-запросом.

Неизвестно, как именно добраться до результата

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

Это уже хороший кандидат на bounded agent — ограниченный агентный узел.

Неопределённость текста ещё не требует агента. Агент нужен при неопределённости процесса.

Лестница сложности ИИ-интеграций

Рациональнее двигаться снизу вверх и останавливаться на самом простом уровне, который решает задачу.

Уровень	Архитектура	Кто управляет маршрутом
0	Обычный код без LLM	Код
1	Один structured API call	Код
2	Несколько LLM-вызовов по фиксированной схеме	Код
3	Ограниченный агентный узел	Модель внутри заданных границ
4	Долгоживущий агент с состоянием и возобновлением	Модель + оркестратор
5	Multi-agent система	Несколько моделей или агентов

Большинство прикладных веб-функций заканчиваются на уровнях 1–3. Уровни 4–5 нужны заметно реже.

Критерии выбора между скриптом и агентом

Можно ли заранее описать порядок действий

Если процесс легко представляется в виде:

A → B → C → D

или даже:

A
├─ условие 1 → B
└─ условие 2 → C

его лучше оставить в коде. Наличие большого количества if само по себе не доказывает необходимость агента. Если ветки известны, воспроизводимы и тестируемы, обычная бизнес-логика надёжнее.

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

Нужен ли модели доступ к инструментам

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

• искать записи;
• открывать документы;
• выбирать источник;
• несколько раз уточнять запрос;
• сравнивать результаты;
• вызывать внешние API;
• проверять промежуточный результат;
• менять стратегию после ошибки.

Но наличие инструментов ещё не означает, что модель должна выбирать их сама. Код вполне может вызвать поиск, передать найденное модели и получить результат.

Нужно ли повторять действия до достижения цели

Агент полезен, когда недостаточно сделать одну попытку. Например:

найти компанию
→ проверить официальный сайт
→ найти страницу тарифов
→ если она не найдена, попробовать документацию
→ если сведения конфликтуют, открыть дополнительные источники
→ сформировать карточку

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

Насколько важна предсказуемость

Чем жёстче требования к повторяемости, тем сильнее аргумент в пользу кода. Скрипт позволяет гарантировать:

• порядок шагов;
• число вызовов;
• обязательность валидации;
• выполнение транзакции;
• применение бизнес-правил;
• отсутствие запрещённых действий.

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

Оценивать агента сложнее, потому что он вызывает инструменты, изменяет состояние и адаптируется к результатам. Ошибка на раннем шаге может изменить всю последующую траекторию.

Какой ожидается объём операций

Для массовой обработки однотипных объектов почти всегда выгоднее workflow.

• 100 000 товарных карточек;
• ежедневный импорт 20 000 записей;
• генерация метаописаний для всего каталога;
• классификация новостей;
• перевод большой базы;
• извлечение полей из документов.

У агента количество model turns заранее неизвестно. Одна запись может потребовать один вызов, другая — пять. Это затрудняет прогнозирование цены, времени и нагрузки.

Для массовых процессов лучше использовать дешёвый детерминированный happy path, а агенту отдавать только исключения.

Есть ли строгие требования к задержке

У обычного API-вызова задержка относительно предсказуема:

один запрос к модели + один ответ

У агента:

модель
→ инструмент
→ модель
→ инструмент
→ модель

Каждый новый turn добавляет сетевую задержку, обработку tool results и новый контекст. Для интерфейса с жёстким SLA это может быть критично; для фоновой исследовательской задачи — нет.

Есть ли опасные или необратимые действия

Чем выше цена ошибки, тем меньше свободы нужно отдавать агенту. Особенно осторожно следует относиться к инструментам:

• публикации;
• отправки сообщений;
• удаления данных;
• оплаты и возврата средств;
• изменения прав доступа;
• выполнения SQL;
• деплоя;
• запуска shell-команд.

Модель может подготовить предложение операции, но применять её должен обычный код:

Agent → submit_candidate
↓
schema validation
↓
business rules
↓
approval / idempotency
↓
actual action

Неудачная схема:

Agent → execute_sql
Agent → publish_anything
Agent → run_arbitrary_http

Нужно ли продолжать работу после перезапуска

Сам agent loop и надёжное выполнение задач — разные вещи. Небольшой runtime может выполнить задачу внутри текущего Node.js-процесса. Но если задача должна пережить рестарт, ждать подтверждения, продолжиться позже, повториться после сбоя или гарантированно выполнить каждый этап, нужен durable orchestration: очередь, checkpointer, workflow engine или собственная таблица задач.

LangGraph.js позиционируется как низкоуровневый runtime для долгоживущих stateful-процессов с durable execution, persistence и human-in-the-loop. Он позволяет смешивать детерминированные и LLM-узлы в одном графе.

Быстрая таблица выбора

Характеристика задачи	Скрипт / workflow	ИИ-агент
Порядок шагов известен	Да	Обычно нет
Нужна одна текстовая трансформация	Да	Нет
Нужно гарантированное число API-вызовов	Да	Нет
Высокий объём одинаковых задач	Да	Обычно нет
Строгий SLA по времени	Да	Осторожно
Модель должна сама выбирать источники	Иногда	Да
Нужен повторный поиск с изменением стратегии	Сложно	Да
Количество шагов заранее неизвестно	Неудобно	Да
Много неформализуемых исключений	Неудобно	Да
Есть необратимые действия	Кодом	Только через ограничения
Нужна воспроизводимость	Да	Хуже
Требуется исследование открытой среды	Ограниченно	Да
Нужна работа с файлами, shell и тестами	Сложный скрипт	Coding/computer agent

Сценарий 1. База текстов, рерайт и RSS

Рассмотрим конкретный процесс:

1. В базе хранятся исходные тексты.
2. Система выбирает подходящие записи.
3. Модель пишет новые части или делает рерайт.
4. Результат сохраняется.
5. Материал появляется в RSS.

Для такого процесса агент обычно не нужен.

Оптимальная архитектура

cron или ручной запуск
↓
выбор исходников SQL-запросом
↓
блокировка выбранной записи
↓
один structured LLM call
↓
Zod-валидация
↓
проверка длины, ссылок и сходства
↓
при ошибке — один repair call
↓
сохранение draft / published
↓
RSS endpoint читает опубликованные записи

Правила выбора лучше детерминировать:

• статус записи;
• дата последнего использования;
• тематика;
• приоритет;
• минимальная длина;
• качество источника;
• максимальное число повторных использований;
• отсутствие недавно опубликованного похожего текста.

Например:

SELECT id, title, body
FROM source_texts
WHERE status = 'ready'
AND topic = $1
AND used_at IS NULL
ORDER BY priority DESC, created_at DESC
LIMIT 3;

Модель получает уже выбранные материалы и возвращает структуру:

const GeneratedArticleSchema = z.object({
title: z.string().min(20),
description: z.string().min(80),
content: z.string().min(800),
sourceIds: z.array(z.string()).min(1),
});

После этого код проверяет результат, сохраняет его, отмечает исходники использованными, меняет статус публикации и инвалидирует RSS-кеш либо отправляет ping. Ни один из этих этапов не требует, чтобы модель выбирала следующий инструмент.

Когда агент всё-таки может понадобиться

Найди в базе группу связанных, но ещё не использованных материалов. Определи, какой темы не хватает в опубликованном контенте. При необходимости выполни несколько разных поисков. Сравни источники, выбери формат статьи, собери структуру и подготовь черновик.

Тогда модели можно дать инструменты:

• search_texts
• get_text
• find_related_texts
• get_recent_publications
• check_similarity
• submit_draft

Агент сможет сам менять запросы и исследовать базу. Но даже здесь ему не стоит давать publish_to_rss. Правильная граница:

агент исследует и готовит draft
→ код валидирует
→ код публикует

Сценарий 2. Наполнение агрегатора карточек

Когда достаточно API-функции

Если нужно скачать известную страницу, извлечь Open Graph и JSON-LD, передать очищенный текст модели, получить название, описание и категорию, а затем сохранить результат, маршрут известен.

fetch
→ parse
→ LLM extraction
→ Zod
→ deduplicate
→ save

Когда нужен bounded agent

Агент становится полезен для неоднозначных карточек:

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

Тогда можно использовать гибрид:

обычный импорт
↓
confidence ≥ 0,85 → сохранить
↓
confidence < 0,85 → bounded agent
├─ search_catalog
├─ inspect_page
├─ inspect_pricing
├─ get_categories
└─ submit_candidate

Это один из лучших сценариев для небольшого встроенного agent runtime.

Сценарий 3. Поддержка пользователей

Скрипт и один вызов

Агент не нужен для определения темы обращения, оценки тональности, извлечения номера заказа, составления проекта ответа, суммаризации переписки или поиска одного документа по известному фильтру.

Агентный узел

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

1. найти пользователя;
2. посмотреть его заказы;
3. проверить статус платежа;
4. открыть правила возврата;
5. определить применимую политику;
6. при недостатке информации задать вопрос;
7. подготовить решение.

Но возврат денег, отмену заказа или изменение тарифа лучше оформлять как отдельный action tool с проверками и подтверждением.

Сценарий 4. Поиск и исследование

Исследовательская задача часто не имеет заранее известного маршрута:

найти информацию
→ оценить качество источников
→ уточнить запрос
→ открыть первоисточник
→ обнаружить пробел
→ выполнить новый поиск
→ сравнить данные
→ подготовить вывод

Это естественная среда для агента.

Но внешние страницы и документы нужно считать недоверенными данными. Скрытые инструкции внутри веб-страницы могут попытаться изменить поведение модели. Prompt injection остаётся одной из ключевых проблем для агентов, работающих с браузером и совершающих действия во внешней среде.

Поэтому исследовательский агент должен иметь:

• read-only инструменты по умолчанию;
• allowlist доменов или API;
• разделение данных и инструкций;
• запрет на публикацию и отправку;
• лимит шагов;
• полный лог источников;
• проверку итоговых утверждений.

Сценарий 5. Финансы и аналитика

Расчёты, агрегации и сверку лучше выполнять обычным кодом или SQL.

Плохая идея:

Передать модели 10 000 транзакций и попросить посчитать итог.

Лучше:

SQL считает суммы и отклонения
→ код выявляет аномалии
→ модель объясняет результаты

Агент может пригодиться для расследования аномалии:

получить операцию
→ найти связанный счёт
→ открыть договор
→ проверить историю контрагента
→ сравнить правила
→ подготовить объяснение

Но итоговые цифры, лимиты, проводки и транзакции должны оставаться детерминированными.

Сценарий 6. RAG и поиск по базе знаний

Простой RAG не обязательно является агентом:

вопрос
→ embedding / search
→ несколько найденных фрагментов
→ ответ модели

Здесь код всегда выполняет один поиск и один вызов модели.

Agentic RAG появляется, когда модель может:

• решить, нужен ли поиск вообще;
• выбрать одну из нескольких баз;
• сформировать разные запросы;
• повторить retrieval;
• отфильтровать противоречивые результаты;
• открыть исходный документ;
• запросить дополнительные данные.

Для небольшой FAQ-системы это обычно избыточно. Для исследования большой разнородной базы — полезно.

Сценарий 7. CRM, уведомления и публикации

Событие вида:

новый лид
→ определить отрасль
→ написать персонализированное письмо
→ сохранить draft

реализуется workflow.

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

При этом фактическая отправка сообщений должна учитывать разрешения, лимиты, расписание, отписки, антиспам-правила, дедупликацию и idempotency key. Эти ограничения надёжнее реализовать кодом, а не системным промптом.

Сценарий 8. Разработка, DevOps и работа с компьютером

Coding agents — пример задач, где агентная архитектура действительно оправдана.

Чтобы исправить ошибку, модель может:

1. исследовать репозиторий;
2. найти нужные файлы;
3. прочитать конфигурацию;
4. изменить код;
5. запустить тест;
6. получить ошибку;
7. внести новое исправление;
8. повторить тест.

Маршрут зависит от результатов каждого шага, поэтому простой вызов generateText() недостаточен.

Для таких задач существуют полные harness-системы с файлами, shell, сессиями и контекстом. Claude Agent SDK, например, предоставляет программный доступ к agent loop и инструментам Claude Code: чтению и редактированию файлов, запуску команд, hooks, permissions, subagents, MCP и сессиям.

Для рерайта статьи такой harness будет избыточным. Для автономной работы с репозиторием — уместным.

Три практических архитектурных паттерна

Паттерн 1. Детерминированная оболочка вокруг LLM

код получает данные
→ модель выполняет семантическую операцию
→ код проверяет результат
→ код совершает действие

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

Паттерн 2. Фиксированный workflow с LLM-узлами

select
→ enrich
→ generate
→ review
→ repair if needed
→ save

Некоторые узлы — обычный код, некоторые — вызовы моделей. Такой процесс остаётся управляемым, тестируемым и предсказуемым. Он часто лучше агента, даже если содержит много шагов.

Паттерн 3. Agent fallback

обычный pipeline
↓
результат валиден? ── да → save
↓ нет
bounded agent
↓
validated candidate
↓
save или manual review

Для каталогов, импорта, контента и SEO-автоматизаций это обычно оптимальный компромисс.

Каким должен быть bounded agent

Ограниченный агент — это не «делай всё, пока не получится». У него должны быть явные рамки:

const result = await runAgent({
input,
tools: {
searchTexts,
getText,
findRelated,
submitDraft,
},
maxTurns: 4,
timeoutMs: 45_000,
maxToolCalls: 8,
maxCostUsd: 0.20,
});

При этом:

• инструменты узкие;
• произвольного SQL нет;
• произвольного HTTP нет;
• shell отсутствует;
• итог передаётся через submitDraft;
• публикация выполняется отдельно;
• состояние можно не сохранять после завершения;
• при исчерпании лимита задача уходит в error или manual review.

Такой агент вполне может жить внутри существующего Node.js-контейнера.

Agent runtime не обязательно означает новый сервис

Встраиваемый агентный узел может выглядеть как обычная функция:

существующий Node.js / Hono контейнер
├── API
├── PostgreSQL
├── бизнес-логика
├── LLM-функции
└── runBoundedAgent()

Для него не обязательны отдельный микросервис, Redis, vector database, отдельная память, MCP-сервер, новый контейнер или новая административная панель.

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

Примеры встраиваемых agent runtimes для Node.js

Ниже приведена практическая оценка архитектурного масштаба, а не сравнение размера node_modules.

Pi Agent Core

Pi состоит из нескольких уровней:

• @earendil-works/pi-ai — работа с разными LLM-провайдерами;
• @earendil-works/pi-agent-core — agent loop, tools, состояние и события;
• @earendil-works/pi-coding-agent — готовый терминальный coding agent;
• pi-tui — терминальный интерфейс.

Для встроенного агента в веб-сервисе интерес представляет именно pi-agent-core, а не полный coding agent. Core предоставляет stateful agent runtime, tool execution, streaming events, последовательное и параллельное выполнение tools, hooks до и после вызова, остановку после turn и низкоуровневый agentLoop. Persistence и SQLite не обязательны для одноразового узла.

Pi подходит, если:

• нужен небольшой контролируемый agent loop;
• используются разные провайдеры;
• агент встраивается в существующий Node.js backend;
• persistence и очереди уже реализуются приложением;
• нужны собственные hooks и политика tool calls;
• не нужна большая готовая платформа.

Pi избыточен, если модель только переписывает текст, нужен один structured response, порядок операций известен и tool calling не требуется.

Vercel AI SDK и ToolLoopAgent

Vercel AI SDK — provider-agnostic TypeScript toolkit, работающий не только с Next.js, но и с обычным Node.js. ToolLoopAgent создаёт переиспользуемого агента, способного генерировать и стримить ответы, вызывать tools в несколько шагов и продолжать reasoning-and-acting loop. Читать полный обзор сервиса Vercel.

В AI SDK предусмотрены stopping conditions, изменение параметров между шагами и approval-паттерны для tools.

Подходит, если AI SDK уже используется для обычных LLM-вызовов, нужен минимальный переход от generateText() к агенту, проект написан на TypeScript и важен streaming в пользовательский интерфейс.

OpenAI Agents SDK for TypeScript

OpenAI Agents SDK позиционируется как лёгкий SDK с небольшим числом базовых примитивов. Он включает agent loop, tools, agents-as-tools, handoffs, guardrails, structured outputs, tracing, streaming и sessions.

Агент может запускаться непосредственно в процессе приложения. Для памяти доступны process-local sessions, hosted conversation state или собственная реализация интерфейса Session на базе существующей БД.

Подходит, если основным провайдером является OpenAI, нужны встроенные traces и guardrails, планируются handoffs или agents-as-tools и требуется официальный runner.

Mastra

Mastra — более широкий TypeScript-фреймворк, объединяющий агентов, workflows, tools, memory и observability. Агенты могут работать напрямую или быть встроены в workflow-узлы.

Разработчики Mastra проводят полезную границу: agents — для открытых задач с заранее неизвестными шагами, workflows — для предопределённых многоэтапных процессов с явным control flow.

Mastra подходит, если в одном проекте нужны и workflows, и агенты, требуется единый framework для memory, logging и observability. Для одного agent loop в одном endpoint он может быть избыточен.

LangGraph.js

LangGraph.js предназначен не столько для одного простого агента, сколько для orchestration сложных stateful-процессов. Его сильные стороны:

• графы выполнения;
• смешивание обычного кода и LLM-узлов;
• persistence;
• checkpointing;
• durable execution;
• streaming;
• human-in-the-loop;
• пауза и возобновление.

Подходит, если процесс работает долго, его надо восстанавливать после сбоя, есть несколько agentic и deterministic узлов, нужны approvals посередине и состояние требуется сохранять между шагами. Для функции «выбрать текст → переписать → отправить в RSS» почти наверняка будет лишним.

Google Genkit Agents

Genkit — full-stack framework от Google для AI- и agentic-приложений. Agents API объединяет model loop, историю, tools, streaming и persistence, при этом агент можно вызывать как внутри процесса, так и через HTTP.

Документация Genkit рекомендует flows и обычный generate() для request-response задач, scheduled jobs и явных backend-workflows, а agents — для разговорных, итеративных и возобновляемых процессов, approvals и multi-turn generation.

Claude Agent SDK

Claude Agent SDK — более полноценный harness, построенный вокруг возможностей Claude Code. Он предоставляет работу с файлами, shell-команды, web search, hooks, subagents, MCP, permissions, sessions, skills и плагины. Читать полный обзор сервиса Claude Code.

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

n8n AI Agent Node

n8n относится к другой категории. Это не маленькая npm-библиотека для существующего приложения, а workflow-платформа с визуальным AI Agent node. К нему подключаются chat model и инструменты, после чего агент сам решает, какие tools вызывать.

n8n удобен, когда автоматизации уже построены в n8n, важен визуальный редактор и интеграции преимущественно внешние. Но если цель — не превращать небольшой агрегатор в дополнительный сервис с новой инфраструктурой, встраиваемый pi-agent-core, AI SDK или обычная функция будут проще.

Сводное сравнение agent runtimes

Инструмент	Масштаб	Отдельный сервис обязателен	Лучший сценарий
Обычный provider SDK	Минимальный	Нет	Один structured API call
Vercel AI SDK ToolLoopAgent	Низкий	Нет	Несколько встроенных agent nodes
Pi Agent Core	Низкий	Нет	Собственный контролируемый multi-provider loop
OpenAI Agents SDK	Низкий–средний	Нет	OpenAI-ориентированные агенты, tracing, handoffs
Mastra	Средний	Нет	Общая среда agents + workflows + memory
LangGraph.js	Средний–высокий	Нет, но durability требует хранилища	Долгие графы, pause/resume, human-in-the-loop
Genkit Agents	Средний	Нет	Full-stack conversational agents
Claude Agent SDK	Средний–высокий	Нет, но желателен sandbox	Файлы, shell, coding и computer use
n8n AI Agent Node	Платформенный	Нужен n8n runtime	Визуальные интеграционные процессы

Что выбрать для существующего Node.js/Hono-проекта

Нужен рерайт, классификация или извлечение

provider SDK
или
Vercel AI SDK Core

Архитектура:

function → structured LLM call → Zod

Нужны два-три адаптивных agent nodes

Pi Agent Core
или
Vercel AI SDK ToolLoopAgent

Они могут работать внутри уже существующего контейнера.

Проект преимущественно на OpenAI

OpenAI Agents SDK

Особенно если нужны tracing, sessions, handoffs и guardrails.

Нужны и агенты, и детерминированные workflows

Mastra

Процесс долгий и должен возобновляться

LangGraph.js
или
собственный durable workflow + маленький agent node

Агенту нужны файлы, shell и полноценная рабочая среда

Claude Agent SDK
полный Pi coding agent
или другой computer / coding harness

Как безопасно встраивать агента

Давать узкие инструменты

Хорошо:

• search_articles(query, limit)
• get_article(id)
• get_allowed_categories()
• submit_draft(candidate)

Плохо:

• execute_sql(query)
• http_request(any_url)
• run_bash(command)
• update_any_record(table, data)

Tool должен выражать бизнес-операцию, а не предоставлять модели универсальный административный интерфейс.

Разделять чтение и действия

read
→ получить данные

propose
→ предложить изменение

commit
→ реально изменить систему

Большинство агентов должны иметь свободный доступ к read, ограниченный доступ к propose и не иметь прямого доступа к commit.

Ограничивать цикл

• maxTurns;
• timeout;
• max tool calls;
• token budget;
• cost budget;
• ограничение параллелизма;
• запрет повторять один инструмент бесконечно.

Для маленького бизнес-агента часто достаточно трёх-пяти turns.

Валидировать результат вне модели

Промпт не является механизмом обеспечения целостности. После агента должны работать:

• Zod или JSON Schema;
• проверки обязательных полей;
• ACL;
• лимиты;
• allowlist;
• бизнес-правила;
• транзакции;
• idempotency;
• дедупликация.

Логировать не только финальный текст

input
→ model response
→ tool call
→ tool result
→ следующий model response
→ final output

Кроме итогового ответа следует измерять:

• какие инструменты выбирались;
• сколько было turns;
• стоимость;
• задержку;
• число ошибок tools;
• долю ручных вмешательств;
• конечное состояние в БД.

Оценивать следует не только слова агента, но и фактический outcome: сообщение «заказ оформлен» не доказывает, что запись действительно появилась в базе.

Когда нужен multi-agent

Multi-agent архитектура оправдана значительно реже, чем кажется. Она может потребоваться, если:

• один prompt содержит слишком много разных политик;
• инструменты разных доменов пересекаются и путают модель;
• нужны независимые специалисты;
• отдельные части требуют разных моделей;
• контексты должны быть изолированы;
• задачи естественно распараллеливаются.

Но не стоит создавать отдельного агента для каждой функции:

агент-поисковик
→ агент-классификатор
→ агент-рерайтер
→ агент-проверяющий
→ агент-публикатор

Если порядок фиксирован, это обычный workflow, только более дорогой и сложный. Сначала лучше развивать одного агента с хорошо определёнными tools; разделять систему на несколько агентов стоит, когда инструкции становятся слишком сложными или агент стабильно выбирает неправильные пересекающиеся инструменты.

Распространённые ошибки

Называть агентом один API-вызов

Structured generation — полезная ИИ-функция, но не агент.

Отдавать модели весь control flow

Факт использования LLM не означает, что модель должна управлять SQL, публикацией, очередями и транзакциями.

Добавлять память без необходимости

Для одноразового рерайта не нужны conversation history, vector memory, session storage и long-term memory.

Давать агенту универсальные tools

Чем шире инструмент, тем сложнее проверить и ограничить его применение.

Сразу строить multi-agent систему

Один bounded agent почти всегда проще в тестировании, эксплуатации и отладке.

Использовать агента для массового happy path

Лучше обрабатывать большинство записей обычным workflow, а агенту отдавать редкие неоднозначные случаи.

Полагаться на самопроверку модели

Фраза «проверь результат перед публикацией» не заменяет schema validation, тесты и бизнес-правила.

Итоговый алгоритм принятия решения

Нужна только семантическая трансформация?

Да → один API-вызов

Шагов несколько, но их порядок известен?

Да → детерминированный workflow с LLM-узлами

Модель должна сама выбирать инструменты, повторять поиск и менять стратегию?

Да → bounded agent

Задача должна переживать рестарты, approvals и долгие паузы?

Да → durable orchestration + agent node

Один агент не справляется из-за разделения доменов или пересечения tools?

Только тогда → multi-agent architecture

Вывод

ИИ-агент — не улучшенная версия API-запроса и не обязательный следующий этап любой LLM-интеграции. Его главное свойство — передача модели права выбирать маршрут выполнения задачи.

Маршрут известен
→ скрипт или workflow.

Нужна только работа с текстом
→ structured API call.

Маршрут зависит от промежуточных результатов
→ bounded agent.

Нужны паузы, восстановление и сложное состояние
→ orchestration runtime.

Нужны файлы, shell и автономное исследование среды
→ полноценный agent harness.

Для системы с базой текстов, рерайтом и RSS правильная начальная архитектура — детерминированный выбор записей, один structured LLM call, валидация, при необходимости один repair call и обычная публикация.

Pi Agent Core или похожий runtime стоит добавлять не вместо этого пайплайна, а рядом с ним — как ограниченный fallback для задач, где модели действительно приходится несколько раз обращаться к данным, оценивать промежуточные результаты и самостоятельно выбирать дальнейшие действия.

Источники и документация

• Anthropic — Building Effective Agents
• OpenAI — A Practical Guide to Building AI Agents
• Anthropic — Demystifying Evals for AI Agents
• Anthropic — Prompt Injection Defenses
• Pi — GitHub repository
• Vercel AI SDK — ToolLoopAgent
• Vercel AI SDK — Loop Control
• OpenAI Agents SDK for JavaScript
• Mastra — Agents Overview
• LangGraph.js — Overview
• Google Genkit — Agents Overview
• Anthropic — Claude Agent SDK
• n8n — AI Agent node