AI-агенты: проектирование, инструменты и внедрение

Основы AI-агентов и архитектурные паттерны

Что такое AI-агент

AI-агент — это программная система, которая:

получает цель или задачу от пользователя или другой системы

сама планирует шаги решения

выполняет действия во внешней среде через инструменты

наблюдает результат и корректирует поведение

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

Когда нужен агент, а когда достаточно модели

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

многошаговая и требует промежуточных проверок

требует доступа к данным и действиям вне контекста одного сообщения

предполагает неопределённость и необходимость адаптации по ходу выполнения

Не стоит начинать с агента, если задача:

решается одним запросом к модели

не требует инструментов и внешних данных

не имеет ясных критериев успеха или безопасного пространства для ошибок

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

Базовый цикл работы агента

Большинство архитектур сводится к повторяющемуся циклу:

Понять контекст: вход пользователя, состояние задачи, ограничения.

Сформулировать следующий шаг: выбор стратегии или плана.

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

Проверить результат: валидация, тест, сопоставление с критериями.

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

Завершить или продолжить: пока не достигнута цель или не исчерпаны лимиты.

!Базовый цикл: планирование → действие → проверка → обновление состояния

Обязательные компоненты агентной системы

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

Цель и критерии успеха

Цель — что нужно получить.

Критерии успеха — как понять, что задача решена правильно (формат ответа, ограничения, тесты, бизнес-правила). Чем они точнее, тем проще построить надёжного агента.

Состояние

Состояние — структурированная информация о ходе решения: что уже сделано, какие данные получены, какие шаги остались.

Состояние обычно хранит:

текущий шаг или статус

результаты вызовов инструментов

промежуточные артефакты (черновики, файлы, ссылки)

ошибки и попытки исправления

Инструменты

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

Типовые инструменты:

поиск и чтение документов

запросы к базам данных

вызовы внутренних сервисов через API

выполнение кода в песочнице

отправка сообщений и создание задач в системах управления

Важно: инструмент должен иметь понятный контракт (входы/выходы) и ограничения (таймауты, права доступа).

Память

Под памятью в агентных системах обычно понимают несколько уровней:

контекст диалога (последние сообщения)

долговременная память (сохранённые факты, предпочтения, история)

рабочая память (промежуточные результаты конкретной задачи)

На практике долговременную память часто строят через поиск по базе знаний (например, по эмбеддингам), но важно помнить: память — это не магия, а управляемое хранилище фактов и артефактов.

Наблюдаемость и контроль

Если агент делает действия, нужны механизмы контроля:

журнал шагов и вызовов инструментов

лимиты на число шагов и бюджет

обработка ошибок и повторные попытки

политика безопасности (что можно и нельзя делать)

Архитектурные паттерны AI-агентов

Ниже — практичные паттерны, которые часто комбинируют.

Реактивный агент

Идея: агент выбирает действие сразу из текущего контекста, без явного долгого планирования.

Подходит для:

простых автоматизаций

диалоговых ассистентов с небольшим числом инструментов

Риски:

сложнее удерживать стратегию в длинных задачах

больше вероятность «блужданий» и лишних вызовов инструментов

Планировщик–исполнитель

Идея: разделить систему на две роли.

Планировщик формирует план шагов.

Исполнитель выполняет шаги и собирает результаты.

Плюсы:

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

проще логировать и дебажить

Минусы:

план может устаревать при новой информации

нужен механизм пересборки плана

!Как роли планировщика и исполнителя взаимодействуют в цикле

ReAct: рассуждение + действие

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

Практический смысл паттерна:

модель не пытается «угадать всё сразу»

вместо этого делает проверяемые действия и опирается на факты

Источник: ReAct: Synergizing Reasoning and Acting in Language Models.

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

Агент с поиском по знаниям (RAG-агент)

RAG (retrieval augmented generation) — подход, при котором ответ формируется на основе найденных фрагментов из базы знаний.

RAG-агент отличается тем, что поиск становится инструментом в агентном цикле: агент сам решает, когда искать, что уточнить, какие источники достать и когда остановиться.

Плюсы:

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

проще объяснять ответ ссылками на источники

Риски:

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

нужны правила цитирования и проверки источников

Иерархический агент (менеджер–воркеры)

Идея: один агент-менеджер декомпозирует задачу и делегирует подзадачи специализированным агентам.

Примеры воркеров:

агент-поисковик

агент-аналитик

агент-кодер

агент-проверяющий

Плюсы:

масштабируемость по сложности задач

специализация повышает качество

Минусы:

сложнее синхронизировать состояние и ответственность

требуется протокол обмена результатами

Мультиагентная система (кооперация или конкуренция)

Идея: несколько агентов работают параллельно.

Типовые схемы:

кооперация (каждый делает часть, затем объединение)

конкуренция (несколько решений, затем выбор лучшего)

Риски:

стоимость и задержки

возможные противоречия, нужен арбитр или правило выбора

Агент с проверкой и самокоррекцией

Идея: после получения результата запускается отдельный этап проверки, который может:

выявить несоответствия формату

прогнать тесты

проверить факты через инструменты

потребовать исправление

Проверка может быть:

правилом (валидатор JSON, бизнес-правила)

отдельной моделью (критик)

комбинацией

Этот паттерн часто даёт максимальный рост надёжности при минимальном усложнении.

Сравнение паттернов

| Паттерн | Когда использовать | Главный плюс | Главный риск | |---|---|---|---| | Реактивный | короткие сценарии, небольшой набор инструментов | простота | нестабильность на длинных задачах | | Планировщик–исполнитель | сложные задачи с понятными этапами | управляемость | план может требовать частых пересборок | | ReAct | задачи, где нужно чередовать поиск/действия и вывод | опора на факты | риск лишних шагов без лимитов | | RAG-агент | корпоративные знания, ответы с источниками | актуальность | мусор на входе поиска → мусор на выходе | | Иерархический | комплексные проекты, разные типы работ | специализация | сложность координации | | Самопроверка | почти любой продакшен-агент | рост надёжности | плохой валидатор может блокировать верные ответы |

Как выбрать архитектуру под задачу

Полезная последовательность выбора:

Определите границы действий: что агенту разрешено делать, а что запрещено.

Опишите критерии успеха и формат результата.

Составьте список инструментов и их контракты.

Выберите базовый паттерн:

- если шагов мало и всё линейно, начните с реактивного - если нужна предсказуемость, берите планировщик–исполнитель - если нужно часто обращаться к данным, используйте ReAct и/или RAG-агента

Добавьте проверку (валидаторы, тесты, лимиты) как обязательный слой.

Только после этого думайте про иерархию и мультиагентность.

Типичные ошибки при проектировании агентов

Нет явных критериев успеха: агент не понимает, когда остановиться.

Инструменты без контрактов: неясные входы/выходы → хаос в состоянии.

Отсутствие лимитов: бесконечные циклы и рост стоимости.

Смешивание ролей: планирование, исполнение и проверка в одном шаге → сложно отлаживать.

Слепая вера в память: если не управлять тем, что сохраняется, качество падает.

Практический итог

AI-агент — это управляемый цикл планирование → действие → проверка, который опирается на инструменты и состояние. Архитектурные паттерны помогают выбрать степень сложности: от реактивных сценариев до иерархий и мультиагентных систем. В продакшене почти всегда выигрывает комбинация: базовый паттерн (например, планировщик–исполнитель или ReAct) + строгая проверка + лимиты.

Что будет дальше в курсе

В следующих материалах логично углубиться в:

проектирование инструментов и контрактов (API, функции, схемы данных)

память и работа с корпоративными знаниями (поиск, RAG, политики хранения)

безопасность, лимиты, наблюдаемость и оценку качества агентных систем

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

Как эта тема связана с предыдущей статьёй

В статье про основы AI-агентов и архитектурные паттерны мы разобрали, что агент — это управляемый цикл планирование → действие → проверка → обновление состояния и что паттерны вроде планировщик–исполнитель, ReAct и RAG-агент задают форму этого цикла.

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

планировать шаги так, чтобы не блуждать и не тратить бюджет

хранить полезную информацию между шагами и сессиями, не превращая её в свалку

собирать контекст для модели так, чтобы он был коротким, релевантным и проверяемым

Эта статья даёт практический каркас для трёх тем: планирование, память и управление контекстом.

Планирование в агентных системах

Что такое план

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

задача многошаговая и требует декомпозиции

есть дорогие инструменты и нужно минимизировать вызовы

есть риск ошибиться, поэтому важны точки проверки

Важно отличать:

цель: что в итоге нужно получить

план: как идти к цели

состояние: что уже сделано и какие факты получены

Уровни планирования

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

высокоуровневый план: 3–7 крупных этапов (ориентир и контроль прогресса)

низкоуровневые шаги: конкретные действия, часто завязанные на инструменты

Так проще:

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

не терять стратегию при длинном диалоге

Стратегии планирования

#### Линейный план-чеклист

Подходит, если:

этапы понятны заранее

среда стабильна

Риск:

план быстро устаревает, если новые данные меняют ситуацию

#### Итеративное планирование с пересборкой

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

Подходит, если:

есть неопределённость

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

Это хорошо сочетается с ReAct.

Источник идеи чередования рассуждения и действия: ReAct: Synergizing Reasoning and Acting in Language Models.

#### Иерархическое планирование

Менеджер формирует подзадачи, воркеры решают их (поиск, анализ, код, проверка).

Подходит, если:

задача комплексная

нужны разные компетенции и разные инструменты

Риск:

растёт сложность синхронизации состояния и ответственности

#### Планирование как поиск по вариантам

Вместо одного плана агент рассматривает несколько альтернативных веток и выбирает лучшую по критерию.

Практический смысл:

полезно в задачах, где легко пойти не туда

удобно, если есть валидатор или тест, который может оценить качество варианта

Один из известных подходов в этой линии: Tree of Thoughts: Deliberate Problem Solving with Large Language Models.

Представление плана в состоянии

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

логировать прогресс

валидировать формат

безопасно резать контекст и восстанавливать картину из состояния

Пример минимального состояния агента с планом:

Ключевой принцип: в состоянии храните результаты и решения, а не длинные рассуждения.

Когда план нужно пересобирать

План стоит обновлять, если:

инструмент вернул новые факты, меняющие стратегию

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

пользователь уточнил требования

лимиты бюджета или времени изменились

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

Память агента

Память и состояние — не одно и то же

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

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

Если смешать их, агент начинает:

тащить в контекст лишнее

ссылаться на устаревшие факты

запоминать ошибки как истину

Слои памяти

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

контекст диалога: последние сообщения и ответы инструментов

рабочая память задачи: текущее состояние, артефакты, промежуточные решения

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

Долговременная память часто делается через извлечение релевантного из хранилища (в том числе векторного), то есть через подход retrieval.

Базовая работа с извлечением знаний близка к идее RAG: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks.

!Иллюстрация, что память состоит из нескольких уровней и что RAG — это механизм извлечения в контекст

Что можно и нельзя сохранять

Полезно сохранять:

проверенные факты с источником или способом проверки

предпочтения пользователя, если это разрешено политикой

шаблоны успешных решений: структуры писем, чеклисты, варианты промптов

ссылки на артефакты, а не сами артефакты целиком (например, идентификатор документа)

Опасно сохранять:

неподтверждённые предположения модели

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

результаты, которые зависят от быстро меняющейся реальности, без срока годности

Политика записи в память

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

Записывать только то, что прошло проверку.

Хранить происхождение факта: откуда он взят.

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

Разделять память на категории:

1. профиль пользователя 2. факты домена 3. операционные параметры 4. кейсы и решения

Если у вас есть инструмент поиска по документам, полезно сохранять не «факт», а ссылку на первоисточник плюс краткое резюме.

Управление контекстом

Что такое контекст и почему он ограничен

Контекст — это всё, что вы отправляете модели в конкретном вызове: инструкции, сообщения, состояние, результаты инструментов, найденные документы.

Контекст ограничен по объёму. Если пытаться «засунуть всё», возникают проблемы:

стоимость и задержка растут

релевантность падает

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

Отдельная наблюдаемая проблема длинных контекстов описана, например, здесь: Lost in the Middle: How Language Models Use Long Contexts.

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

Цель не в том, чтобы сделать контекст максимально большим, а в том, чтобы сделать его:

коротким: без лишнего

релевантным: только то, что нужно для следующего шага

проверяемым: с опорой на результаты инструментов и источники

Основные стратегии

| Стратегия | Идея | Когда применять | Основной риск | |---|---|---|---| | Обрезка истории | держать последние сообщений и важные системные правила | простые диалоги, короткие задачи | потеря ранних требований | | Сводка истории | поддерживать краткое резюме того, что уже произошло | длинные многошаговые диалоги | сводка может исказить детали | | Извлечение по запросу | доставать в контекст только релевантные фрагменты из хранилища | работа с документами, RAG | нерелевантный поиск ведёт к ошибкам | | Структурированное состояние | вместо «полотна текста» передавать компактный state | почти всегда в продакшене | требует дисциплины схем | | Нормализация результатов инструментов | превращать сырые ответы API в краткие факты | когда инструменты многословны | можно выкинуть важную деталь |

Практика: контекстный пакет

Удобная инженерная идея — собирать на каждый шаг контекстный пакет: минимальный набор данных, который нужен модели прямо сейчас.

Состав пакета обычно такой:

цель и критерии успеха в одном коротком блоке

текущий шаг плана и ожидаемый результат шага

компактное состояние: ключевые факты и прогресс

выжимка истории: резюме + последние 1–3 сообщения

извлечённые знания: 3–10 фрагментов, строго релевантных шагу

результаты инструментов только для текущего шага

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

Как не утонуть в документах

Если агент работает с большим массивом текстов, типичная ошибка — вставлять в контекст целые документы. Более надёжный подход:

Делать поиск и доставать только небольшие фрагменты.

Требовать от агента ссылаться на фрагменты при формулировке выводов.

Хранить в состоянии список использованных источников.

Это дисциплинирует RAG-агента и упрощает аудит.

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

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

Определите схему состояния:

1. цель и критерии успеха 2. план и статусы шагов 3. факты с пометками источника 4. журнал инструментов 5. лимиты и политика остановки

На каждом шаге собирайте контекстный пакет из состояния, а не из «всего диалога целиком».

Встраивайте извлечение знаний как инструмент:

1. запрос в хранилище 2. получение фрагментов 3. краткая нормализация в факты

После действия запускайте проверку:

1. формат 2. бизнес-правила 3. при необходимости — перепроверка фактов через инструменты

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

Такой процесс даёт три эффекта:

агент становится предсказуемее за счёт явного плана

качество стабилизируется за счёт памяти, но без «самоотравления»

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

Практический итог

Планирование делает многошаговые задачи управляемыми и снижает блуждание.

Память полезна только при политике записи: храните проверенное, с источниками и сроками актуальности.

Контекст нужно не расширять, а упаковывать: состояние + текущий шаг + релевантные извлечённые знания.

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

Инструменты, функции и интеграции с внешними системами

Зачем агенту инструменты

В предыдущих статьях мы разобрали, что AI-агент — это цикл планирование → действие → проверка → обновление состояния, а также как план, память и контекстный пакет делают этот цикл управляемым.

Инструменты — это то, что превращает модель из «генератора текста» в систему, которая может:

получать факты из внешних источников

выполнять операции в системах (создать заявку, выставить счёт, обновить карточку клиента)

проверять гипотезы через вычисления и тесты

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

Термины: инструмент, функция, интеграция

Инструмент — вызываемая агентом операция с чётким контрактом входа и выхода.

Функция — инженерная форма инструмента в коде (например, def crm_create_lead(...)). В системах с function calling модель выбирает функцию и аргументы по схеме.

Интеграция — соединение инструмента с внешней системой: авторизация, сетевые вызовы, очереди, ретраи, лимиты, трансформации данных.

Важно: «инструмент» в агентном дизайне — это не обязательно прямой вызов внешнего API. Часто лучший инструмент — это ваш сервис-обёртка, который делает вызов безопасным и предсказуемым.

Контракт инструмента: главный объект проектирования

Что должно быть в контракте

Минимальный контракт инструмента включает:

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

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

выход: структура результата, статусы, полезные поля

ошибки: коды, сообщения, условия ретрая

побочные эффекты: что изменится во внешнем мире

ограничения: таймаут, лимиты, права доступа, стоимость

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

Схемы данных: JSON Schema и OpenAPI

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

JSON Schema — стандарт описания структуры JSON

OpenAPI Specification — стандарт описания API (эндпоинты, схемы, авторизация)

Даже если вы не публикуете OpenAPI наружу, внутренняя спецификация помогает:

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

автоматически генерировать клиентский код

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

Function calling и выбор инструмента моделью

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

какую функцию вызвать

какие аргументы передать

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

Как описывать инструмент так, чтобы модель выбирала его правильно

Хорошее описание инструмента:

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

перечисляет ключевые ограничения

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

Плохое описание:

«универсальный инструмент для любых задач»

дублирование назначений нескольких инструментов

Практическое правило: один инструмент — одна бизнес-операция

Если инструмент пытается делать «всё сразу», агенту сложнее:

планировать шаги

проверять результат

откатываться при ошибках

Вместо crm.updateAnything(payload) лучше иметь маленькие операции:

crm.create_lead

crm.update_lead_status

crm.add_note

Дизайн инструментов под агентный цикл

Идемпотентность: защита от двойных действий

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

Полезная стратегия — идемпотентные ключи:

рантайм генерирует idempotency_key на шаг

инструмент гарантирует: повтор с тем же ключом не создаст новый объект

Это особенно важно для:

платежей

создания заявок

отправки писем

Модель ошибок: что агент должен знать

Ошибки инструментов должны быть структурированы. Минимально:

error_code: стабильный код

message: человекочитаемое описание

retryable: можно ли безопасно повторить

details: поля для отладки

Так агент может в цикле проверка → обновление состояния принять решение:

повторить

выбрать альтернативный инструмент

запросить уточнение у пользователя

остановиться

Нормализация выхода: инструмент возвращает факты, не «простыни»

Если внешний API возвращает 200 полей, не нужно тащить их все в контекст. Лучший подход из статьи про управление контекстом:

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

в состояние и контекстный пакет класть нормализованную выжимку

Пример: из ответа CRM оставить lead_id, status, next_action.

Безопасность инструментов: политика важнее промпта

Разделение прав: агент не должен иметь «права администратора»

Даже если модель «умная», инструмент — это реальное действие. Поэтому нужны:

минимальные права доступа по принципу least privilege

разделение окружений: тестовое и прод

ограничения по типам операций

Для интеграций с пользовательскими аккаунтами обычно применяют OAuth2:

RFC 6749: The OAuth 2.0 Authorization Framework

Политика разрешённых действий

Полезно иметь слой правил, который проверяет запрос до вызова внешней системы:

разрешён ли инструмент

разрешена ли операция для этого пользователя

не превышены ли лимиты

нет ли запрета на работу с определёнными полями

Это должно быть реализовано кодом, а не только текстовыми инструкциями.

OWASP как чеклист для API-инструментов

Для типичных рисков (авторизация, утечки, инъекции, избыточные данные) используйте:

OWASP API Security Top 10

Интеграционные паттерны: как подключать внешние системы

Прямой синхронный вызов

Подходит, когда:

операция быстрая

важен результат прямо сейчас

можно надёжно настроить таймауты и ретраи

Риски:

длинные задержки ухудшают UX

каскадные падения при проблемах внешней системы

Асинхронная очередь задач

Подходит, когда:

операция долгая

нужна надёжная доставка

допустимо получить результат позже

Типовая схема:

агент вызывает инструмент enqueue_task

воркер выполняет реальную интеграцию

результат сохраняется в хранилище и доступен по task_id

Фасадный сервис (anti-corruption layer)

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

Фасад делает:

авторизацию

преобразование форматов

кеширование

ретраи

нормализацию ответов

безопасное логирование

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

Наблюдаемость: как дебажить инструментальный агент

В агентных системах «просто смотреть на финальный ответ» недостаточно. Нужны логи уровня действий.

Минимальный набор для каждого шага:

trace_id всей сессии и step_id шага

имя инструмента

входные аргументы после валидации (с маскированием секретов)

результат: успех или ошибка, error_code, retryable

длительность, таймаут

влияние на состояние: какие факты записаны

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

Тестирование инструментов: без этого агент «не внедряется»

Тестировать нужно не только промпты.

Что тестировать в первую очередь

валидацию входов по схеме

обработку типовых ошибок внешней системы

идемпотентность

маскирование секретов в логах

корректность нормализации выхода

Контрактные тесты

Если у вас есть OpenAPI, полезно иметь контрактные тесты:

инструмент принимает только то, что описано в схеме

инструмент возвращает структуру, которую ожидает агент

Практический пример: инструмент для создания заявки в helpdesk

Ниже пример контракта инструмента в формате, близком к JSON Schema (упрощённо).

Ключевые моменты, которые помогают агенту:

additionalProperties: false снижает вероятность «лишних полей»

enum задаёт допустимые значения

idempotency_key защищает от дублей

Пример структурированного ответа инструмента с ошибкой

Такой ответ легко встроить в этап проверка: агент понимает, что это не «плохие данные пользователя», а временное ограничение.

Как связать инструменты с планом, памятью и контекстом

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

В состоянии храните:

- текущий шаг плана - какой инструмент выбран и почему - нормализованный результат и ключевые факты

Перед вызовом инструмента:

- валидируйте аргументы по схеме - применяйте политику доступа - добавляйте idempotency_key

После вызова:

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

В контекстный пакет на следующий шаг включайте:

- минимальные факты из результата - статус шага и критерий завершения

Практический итог

Инструменты нужно проектировать как контракты: входы, выходы, ошибки, ограничения.

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

Безопасность обеспечивается кодом: права, политики, валидация, маскирование, лимиты.

Надёжные интеграции обычно требуют фасадного сервиса и хорошей наблюдаемости.

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

Оценка качества, тестирование и наблюдаемость агентов

Зачем это нужно именно агентам

В предыдущих статьях курса мы построили каркас агентной системы:

архитектурные паттерны и базовый цикл планирование → действие → проверка → обновление состояния

план, память и контекстный пакет как способ управлять многошаговостью

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

Следующий шаг до внедрения — сделать агента измеримым и отлаживаемым. Для этого нужны три слоя:

оценка качества: как понять, что агент решает задачу правильно и стабильно

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

наблюдаемость: как видеть, что происходит внутри цикла шагов, и быстро находить причины сбоев

Главная идея: в продакшене вам нужно контролировать не только финальный текст ответа, но и процесс: план, выбор инструментов, результаты вызовов, обновление состояния, проверки и остановку.

Что значит «качество агента»

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

Результативность

Успех задачи: достигнут ли критерий успеха (например, тикет создан, данные обновлены, ответ соответствует политике).

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

Формат: соответствует ли результат требуемой схеме (JSON, шаблон письма, поля формы).

Эффективность

Задержка: время до первого полезного ответа и до завершения задачи.

Стоимость: количество шагов, токены, число вызовов инструментов, объём retrieval.

Стабильность: одинаково ли агент работает на похожих кейсах и при небольших вариациях входа.

Безопасность и комплаенс

Политики действий: не делает ли агент запрещённых операций.

Конфиденциальность: не утекли ли секреты и персональные данные в логи или ответ.

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

Полезная практика — заранее зафиксировать, какие метрики считаются must-have, а какие nice-to-have, иначе вы получите вечный спор «качество выросло или упало».

Артефакты, которые нужно уметь оценивать

У агента есть несколько уровней результата, и тесты должны покрывать их все.

| Уровень | Что оцениваем | Типичная проверка | |---|---|---| | Финальный результат | соответствует ли цели и формату | валидатор схемы, бизнес-правила, проверка ссылок | | Шаги и решения | не блуждает ли агент, корректно ли выбирает инструменты | проверка траектории: шаги, ретраи, причины ошибок | | Инструменты | корректны ли контракты и обработка ошибок | контрактные тесты, идемпотентность, ретраи | | Контекст и память | не «засоряется» ли контекст, не пишется ли мусор в память | политика записи, TTL, проверка источников | | Наблюдаемость | можно ли дебажить по логам и трассам | наличие trace_id, step_id, структурные события |

Оценка качества: офлайн и онлайн

Офлайн-оценка (до продакшена)

Офлайн-оценка отвечает на вопрос: на типовых кейсах агент работает лучше/хуже после изменений?

Что обычно делают:

Набор эталонных сценариев (golden set): реальные или синтетические кейсы с ожидаемыми результатами.

Чёткие рубрики: критерии, по которым ставится оценка (формат, полнота, корректность действий, безопасность).

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

Что важно учесть для агентов:

тестируйте не только финальный ответ, но и траекторию действий

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

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

Если вы используете автоматического «судью» на базе модели, относитесь к этому как к эвристике и старайтесь сочетать:

детерминированные проверки (схемы, правила)

проверку по источникам (цитирование/ссылки на документы)

выборочную ручную валидацию сложных кейсов

Систематический обзор подходов к оценке языковых моделей (полезно как ориентир для рубрик и измерений): Holistic Evaluation of Language Models (HELM).

Онлайн-оценка (в продакшене)

Онлайн-оценка отвечает на вопрос: что реально происходит у пользователей и почему?

Типовые практики:

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

Качество по прокси: доля обращений к оператору, повторные обращения, отмены действий.

Выборочный аудит: сэмплирование сессий и ручной разбор траекторий.

A/B-тесты: сравнение версий агента по выбранным метрикам, если бизнес-процесс это допускает.

Ключевой момент: онлайн-метрики должны быть привязаны к вашей схеме состояния и логам инструментов, иначе вы увидите только «плохо», но не поймёте где ломается цикл.

Стратегия тестирования: «пирамида» для агентов

Удобно мыслить тестированием как слоями — от дешёвых и быстрых к дорогим и реалистичным.

Тесты инструментов (самые дешёвые и обязательные)

Это продолжение статьи про инструменты и контракты.

Покрывайте тестами:

валидацию входов по JSON Schema или аналогичной схеме

нормализацию выхода (возвращаем факты, а не «простыню»)

модель ошибок (error_code, retryable, детали)

идемпотентность для операций с побочными эффектами

маскирование секретов в логах

Если у вас описан API, полезны контрактные проверки через спецификацию: OpenAPI Specification.

Юнит-тесты агентной логики вокруг модели

В продакшен-агенте много кода, который не является моделью:

сборка контекстного пакета

применение политик (что разрешено)

маршрутизация инструментов и ретраи

обновление состояния и правила остановки

Это должно тестироваться детерминированно, без вызова LLM.

Интеграционные тесты агента с моками инструментов

Чтобы проверить многошаговость, но не зависеть от внешних систем:

подменяйте инструменты моками, которые возвращают заранее заданные ответы

прогоняйте сценарии, где ответы меняются по ходу шагов

проверяйте, что агент корректно обновляет состояние и пересобирает план

Плюс такого подхода: вы тестируете траектории и обработку ошибок стабильно и быстро.

End-to-end тесты с реальными системами (дорого и ограниченно)

Оставьте небольшой набор E2E на тестовом окружении:

минимальный happy path

1–2 критичных негативных кейса (например, rate limit, отказ по правам)

Главная цель E2E — убедиться, что интеграции, авторизация и политики действительно работают вместе.

Тестирование поведения модели: регрессии, недетерминизм, «дрейф»

В отличие от обычного софта, поведение LLM недетерминировано и может меняться при обновлении модели, параметров или retrieval.

Практики, которые помогают:

Регрессионные наборы с допусками

Вместо «строго совпало слово в слово» используйте:

проверку структуры (валидный JSON, нужные поля)

проверку ключевых фактов (наличие обязательных утверждений)

проверку запрещённых вещей (не упомянуты секреты, нет запрещённых действий)

Тестирование траекторий, а не только ответа

Фиксируйте ожидания вида:

«для этого кейса агент обязан вызвать kb.search не более 2 раз»

«при ошибке RATE_LIMIT агент должен подождать/запросить повтор, а не создавать дубликат»

«для операции с побочным эффектом должен быть idempotency_key»

Это напрямую связано с материалами про план и инструменты.

Версионирование всего, что влияет на результат

Чтобы результат был воспроизводимым при разборе инцидентов, логируйте:

версию промпта и системных инструкций

версию схем инструментов

конфигурацию retrieval (индекс, top-k, фильтры)

модель и параметры генерации

Негативные тесты и red teaming

Для агентных систем особенно важны негативные сценарии:

prompt injection из документов и веб-страниц

попытка заставить агента обойти политику действий

утечки секретов через логи

Как чеклист по типовым уязвимостям API-интеграций полезен: OWASP API Security Top 10.

Наблюдаемость: что логировать и как дебажить

Наблюдаемость нужна, чтобы отвечать на вопросы:

почему агент сделал именно эти шаги

где случилась ошибка: модель, инструмент, политика, контекст, память

почему выросли стоимость и задержка

Три сигнала наблюдаемости

Классическая модель:

логи: событийная история (что произошло)

метрики: агрегированные числа (сколько и как часто)

трейсы: связанный путь запроса через шаги и сервисы

Один из стандартов для распределённой трассировки и метрик: OpenTelemetry.

События, которые стоит логировать на каждом шаге

Чтобы это работало системно, договоритесь о едином событии шага (step event). Минимальный набор полей:

trace_id: идентификатор сессии/запроса

step_id: номер или UUID шага

goal: краткая цель (из состояния)

plan_step: текущий шаг плана и статус

tool_name: имя инструмента или none

tool_input_summary: нормализованная выжимка входов (без секретов)

tool_result_summary: нормализованный результат или код ошибки

state_diff: какие факты добавлены/изменены

stop_reason: почему остановились (успех, лимит, ошибка, политика)

timing_ms: длительность шага и инструмента

cost: число токенов и/или стоимость шага, если доступно

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

Метрики, которые обычно дают максимальную пользу

| Метрика | Что показывает | Что делать при деградации | |---|---|---| | Success rate | доля успешных завершений | разбор траекторий неуспеха по классам | | Steps per task | насколько агент «блуждает» | улучшить планирование, лимиты, подсказки выбора инструментов | | Tool error rate | стабильность интеграций | ретраи, таймауты, фасад, деградационные режимы | | Retry rate | качество обработки ошибок | различать retryable/не retryable, улучшить классификацию ошибок | | Cost per task | стоимость решения | уменьшить retrieval, нормализовать ответы инструментов, резать контекст | | Policy deny rate | частота отказов политикой | проверить UX, уточнение прав, ошибки маршрутизации |

Дебаг-процедура: от симптома к причине

Полезно иметь фиксированный порядок разбора инцидента.

Найдите сессии с плохим результатом по метрикам.

Откройте трейсы и восстановите траекторию шагов.

Определите класс сбоя:

1. неверная цель/критерии успеха 2. плохой план или остановка 3. неправильный выбор инструмента 4. ошибка инструмента или интеграции 5. плохой контекст (лишнее/нехватка) 6. загрязнение памяти 7. блокировка политикой

Для класса сбоя добавьте тест или мониторинг, чтобы он ловился раньше.

!Как наблюдаемость «прикрепляется» к каждому шагу агентного цикла и превращается в дашборды и разбор инцидентов

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

Самая рабочая модель — сделать так, чтобы одна и та же телеметрия использовалась и в тестах, и в продакшене.

Практический протокол:

Определите «схему шага» для логов (как выше) и используйте её везде.

Соберите golden set сценариев и прогоняйте агента в тестовом рантайме.

Для каждого прогона сохраняйте:

1. финальный результат 2. траекторию шагов 3. нормализованные вызовы инструментов

Стройте отчёт по метрикам качества и по метрикам процесса (шаги, стоимость, ошибки).

Перед релизом делайте регрессию на golden set.

В продакшене включайте сэмплирование трейсов и выборочный аудит тех же типов сценариев.

Так вы превращаете «агент ответил странно» в конкретное: на шаге p2 неверно выбран инструмент из-за неоднозначного описания или retrieval вернул нерелевантный фрагмент, и это видно по источникам.

Практический итог

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

Тестируйте агент «пирамидой»: инструменты и агентная логика детерминированно, затем интеграции с моками, затем небольшой набор E2E.

Оценивайте и регрессируйте не только финальный ответ, но и траекторию шагов.

Наблюдаемость должна быть встроена в каждый шаг: структурные события, метрики и трейсы с trace_id и step_id.

Лучший результат даёт единый контур: телеметрия → офлайн-оценка → регрессии → продакшен-мониторинг → улучшения.

Безопасность, этика и внедрение в продукт

Как эта тема продолжает курс

В прошлых статьях мы собрали технический каркас агентной системы:

агентный цикл планирование → действие → проверка → обновление состояния

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

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

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

безопасность: как не дать агенту причинить вред, утечь данным и выполнить запрещённые действия

этика и комплаенс: как работать с данными и пользователями корректно, прозрачно и законно

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

!Слои контроля вокруг модели, которые делают агента внедряемым

Модель угроз для AI-агента

Почему угрозы у агента отличаются от угроз чат-бота

Чат-бот обычно говорит. Агент действует: вызывает инструменты, читает документы, пишет в системы, создаёт заявки, запускает процессы. Это расширяет поверхность атак.

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

Основные классы рисков

Инъекции инструкций: вредоносный текст пытается переопределить поведение агента.

Неправомерные действия: агент выполняет операцию, которую не должен выполнять (по правам или по политике).

Утечки данных: агент выдаёт персональные данные, секреты, внутренние документы или ключи.

Ошибочные действия из-за галлюцинаций: агент придумывает факт и действует на основе выдумки.

Злоупотребление инструментами: агент вызывает дорогие API, бесконечно ретраит, создаёт дубликаты.

Отравление знаний: в базу знаний попадают неверные или вредоносные документы, retrieval приносит их в контекст.

Полезный ориентир по типовым рискам для LLM-приложений: OWASP Top 10 for LLM Applications.

Prompt injection и атаки через знания

Что такое prompt injection

Prompt injection — это попытка встроить в входные данные (сообщение пользователя, документ, страницу, письмо) инструкции вида игнорируй правила, сделай X, раскрой Y, чтобы агент нарушил системные ограничения.

Особенно опасно это для RAG-агентов, потому что документы из retrieval попадают в контекст и конкурируют за “внимание” модели.

Как защищаться: практический набор мер

Разделяйте каналы данных

1. Системные правила и политика — отдельно. 2. Пользовательский запрос — отдельно. 3. Фрагменты из retrieval — отдельно, с метками источника. 4. Результаты инструментов — отдельно. Это помогает вашему рантайму применять разные правила доверия и фильтрации.

Считайте документы недоверенными

1. Документы — это данные, а не инструкции. 2. Любые “приказы” внутри документов игнорируются и не должны попадать в план.

Минимизируйте то, что попадает в контекст

1. Доставайте 3–10 релевантных фрагментов, а не целые документы. 2. Нормализуйте в факты, как в статье про управление контекстом.

Требуйте обоснование на источниках

1. Для ответов по документам — ссылки на фрагменты. 2. Для действий — ссылка на правило/разрешение/подтверждение пользователя.

Инструментальные политики важнее текста

1. Даже если модель “решила”, фактическое действие должно пройти кодовую проверку.

Политики действий: как ограничить агента

Принцип наименьших привилегий

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

Практические правила:

отдельные сервисные учётки для агента

раздельные доступы для чтения и записи

разделение окружений dev/stage/prod

запрет опасных операций по умолчанию

Политика “разрешено/запрещено” как код

Текстовая инструкция в промпте не может быть последней линией обороны. Нужен слой policy enforcement в рантайме.

Что обычно проверяет политика перед вызовом инструмента:

кто пользователь и какие у него права

разрешён ли этот инструмент в данном продукте/режиме

разрешена ли операция над конкретным объектом (например, доступ к клиенту)

не превышены ли лимиты стоимости/частоты

нет ли запретов на работу с определёнными полями (например, паспортные данные)

Эти правила должны быть проверяемы и тестируемы, как любая бизнес-логика.

Подтверждения и human-in-the-loop

Human-in-the-loop — режим, где критические действия требуют явного подтверждения человеком.

Типовые варианты:

подтверждение пользователем перед действием (например, “создать платёж на сумму X?”)

подтверждение оператором/администратором

двухфазные операции

Двухфазный шаблон выглядит так:

Агент формирует план действия и “черновик операции” (payload).

Политика определяет, нужен ли approval.

После approval рантайм выполняет инструмент.

Безопасность данных: конфиденциальность, хранение и логи

Какие данные считаются чувствительными

Минимальный набор, который стоит трактовать как чувствительный:

персональные данные (PII): ФИО, email, телефон, адрес, идентификаторы

секреты: токены, ключи, пароли, cookie

коммерческая тайна: цены, условия, внутренние документы

Если вы работаете с персональными данными, ориентируйтесь на требования законодательства и принцип минимизации данных. Базовый общеевропейский ориентир: Общий регламент по защите данных (GDPR).

Минимизация данных и хранение

Практические решения:

не отправляйте в модель то, что не нужно для текущего шага

не сохраняйте “всё подряд” в память

храните ссылки на документы и краткие выжимки вместо полных текстов

используйте TTL (срок жизни) для оперативных данных

Логи: наблюдаемость без утечек

Из статьи про наблюдаемость мы уже знаем, что нужны step-события и трассировка. Но логи — частый источник утечек.

Правила безопасного логирования:

маскировать секреты и PII (например, user@example.com → u*@example.com)

хранить “сырые” ответы инструментов отдельно и с доступом только для инженеров

в step-событии держать только tool_input_summary и tool_result_summary

ограничить доступ к логам ролями, включить аудит обращений к логам

Надёжность действий: предотвращение вреда от ошибок

Идемпотентность и защита от дублей

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

idempotency_key на операцию

проверка “уже выполнено?” перед созданием сущности

журнал действий (audit log)

Лимиты и остановка

Без лимитов агент может:

зациклиться

сделать слишком много вызовов retrieval

создать дорогостоящие или опасные действия

Минимальные лимиты:

максимум шагов на задачу

максимум вызовов инструментов определённого типа

бюджет токенов/стоимости

таймаут на задачу

Этика: прозрачность, справедливость, ответственность

Что такое “этичность” в контексте агента

Этика здесь — это не абстрактные лозунги, а продуктовые принципы, которые уменьшают вред:

прозрачность: пользователь понимает, что общается с AI и что будет сделано

контроль: пользователь может отменить/исправить действие

ответственность: понятно, кто отвечает за последствия (команда, владелец продукта)

недискриминация: агент не ухудшает качество сервиса для отдельных групп

Набор широко используемых принципов: OECD AI Principles.

Объяснимость на уровне продукта

Полная “объяснимость модели” часто недостижима, но продуктовую объяснимость можно сделать.

Практические элементы:

показывать что агент собирается сделать перед действием

показывать источники для ответов по документам

показывать результат инструмента понятным языком

фиксировать причину отказа (политика, нет прав, нужны данные)

Политика ошибок и отказов

Этичный агент не должен “заметать под ковёр” ограничения.

Хорошая политика отказа:

честно говорит, что действие запрещено или невозможно

предлагает безопасную альтернативу

запрашивает недостающие данные

Плохая политика отказа:

придумывает, что действие выполнено

скрывает, что не было доступа

“уговаривает” пользователя обойти правила

Governance: роли, процессы и контроль изменений

Кто владеет агентом в организации

Чтобы агент был внедряемым, нужны роли:

владелец продукта: отвечает за сценарии и метрики

инженерная команда: отвечает за рантайм, инструменты, наблюдаемость

безопасность: политики, права, аудит, threat modeling

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

поддержка/операторы: обработка сложных кейсов и эскалации

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

У агента меняются:

промпты и системные правила

модель и параметры

схемы инструментов

политика доступа

retrieval-индекс и документы

Практики контроля:

версионировать всё, что влияет на поведение

прогонять регрессии на golden set перед релизом

иметь kill switch (быстро отключить опасные действия)

Kill switch — это технический переключатель, который мгновенно отключает выбранные инструменты или весь агентный режим, оставляя продукт в безопасном состоянии.

Ориентир по управлению рисками AI на уровне организации: NIST AI Risk Management Framework (AI RMF 1.0).

Внедрение в продукт: путь от прототипа к продакшену

Выбор “первого сценария” для внедрения

Лучший первый сценарий обычно:

имеет понятный критерий успеха

не требует опасных действий (или действия легко ограничить)

допускает human-in-the-loop

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

Архитектура внедрения: рекомендуемый минимум

Минимальная продакшен-архитектура обычно включает:

агентный рантайм со схемой состояния и step-событиями

фасад инструментов с валидацией и политиками

слой retrieval с фильтрами и аудитом источников

контур тестирования и офлайн-оценки

мониторинг и алерты по ключевым метрикам

Стратегия релиза: безопасное расширение возможностей

Практический план релиза:

Read-only режим: агент только читает и отвечает, без записей во внешние системы.

Draft режим: агент формирует черновики действий и просит подтверждение.

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

Расширение прав и сценариев по мере стабильности метрик и результатов аудита.

!Этапы безопасного релиза агента в продукт

Инциденты: что делать, когда агент ошибся

В продакшене ошибки неизбежны, поэтому нужен процесс.

Минимальный набор:

классификация инцидента: утечка данных, запрещённое действие, финансовый риск, токсичный контент

быстрые меры: отключение инструмента через kill switch, блокировка сценария, деградация в read-only

разбор по трассам: на каком шаге и почему сработало

корректирующие действия: правка политики, улучшение контекстного пакета, усиление валидации, добавление тестов

Практический чеклист перед запуском

| Область | Вопрос | Минимальный признак готовности | |---|---|---| | Инструменты | Есть ли контракты, идемпотентность, модель ошибок? | JSON Schema/OpenAPI, idempotency_key, error_code/retryable | | Политики | Ограничены ли действия кодом, а не промптом? | policy enforcement до вызова инструмента | | Данные | Минимизируем ли контекст и память, есть ли TTL? | контекстный пакет, политика записи, сроки хранения | | Наблюдаемость | Можно ли восстановить траекторию по шагам? | trace_id, step_id, step events, метрики | | Тесты | Есть ли golden set и регрессии? | офлайн-прогоны, проверка траекторий | | UX и этика | Пользователь понимает, что происходит, и может отменить? | подтверждения, объяснения, безопасные отказы | | Инциденты | Можно ли быстро остановить вред? | kill switch, runbook, алерты |

Практический итог

Безопасный агент — это система, где инструменты, политики и наблюдаемость важнее, чем “правильный промпт”.

Главные угрозы — prompt injection, утечки данных, неверные действия и злоупотребление инструментами; защищаются они архитектурой: разделением доверия, валидацией, минимальными правами, лимитами и аудитом.

Этика в продукте проявляется в прозрачности, контроле, ответственности и честных отказах.

Внедрение стоит делать поэтапно: read-only → draft → ограниченные действия → расширение, постоянно опираясь на тесты, метрики и процессы реагирования.