5. Инструментирование агентов

5.1 Обзор

AI-нативная разработка требует явного управления поведением, возможностями и ограничениями AI-агента. Данный раздел определяет, как организации ОБЯЗАНЫ конфигурировать и версионировать средства контроля поведения AI-агента.

Инструментирование агентов действует на трёх уровнях:

Каждый уровень ОБЯЗАН быть под контролем версий и подчиняться управлению изменениями (см. Section 10.14).

5.2 Профили агентов

Профиль агента — конкретный набор скриптов, разрешений и контекста для AI-агента, выполняющего определённую функцию.

Организации ОБЯЗАНЫ определить как минимум следующие профили:

Разделение ответственности: профиль Ревьюера НЕ ДОЛЖЕН иметь права записи в проверяемые артефакты. Это — основа состязательного ревью: один и тот же агент не может одновременно генерировать и утверждать собственный вывод.

Организации МОГУТ определять дополнительные профили. Один физический AI-агент МОЖЕТ переключаться между профилями в рамках сессии при условии, что каждое переключение профиля журналируется.

NOTE: В Начальной конфигурации (Foundation) (1–3 Пары) организации МОГУТ использовать менее пяти профилей. Требование 5 профилей является РЕКОМЕНДУЕТСЯ для Начальной, ОБЯЗАТЕЛЬНО для Командная+. Команды Начальной конфигурации обычно объединяют Генератор и Ревьюер в меньшее число профилей, соответствующих их совмещённой ролевой структуре (Section 4.8, Section 11.1).

Командная конфигурация (Team): организации ОБЯЗАНЫ определить все пять профилей с принудительными границами разрешений. Корпоративная конфигурация: организации ОБЯЗАНЫ определить все пять профилей с принудительными границами разрешений и аудиторским следом переключений профилей.

5.3 Операционные скрипты

Операционный скрипт — структурированная инструкция на естественном языке, определяющая, как AI-агент выполняет конкретное действие. Скрипты — основной механизм кодификации организационного процесса в поведение агента.

5.3.1 Структура скрипта

Каждому скрипту РЕКОМЕНДУЕТСЯ содержать:

• Триггер: когда скрипт вызывается (команда, событие, условие)
• Предусловия: что должно быть истинным перед выполнением
• Алгоритм: пронумерованные шаги с точками принятия решений
• Постусловия: что должно быть истинным после выполнения
• Выходные данные: что скрипт производит (артефакты, изменения состояния, отчёты)

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

Скрипты определяют поведение агента — изменение скрипта равнозначно изменению производственного процесса. Операционное правило управления изменениями скриптов см. в Section 10.14.

ОБЯЗАТЕЛЬНО (все конфигурации):

• операционные скрипты хранятся в системе контроля версий
• изменения скриптов проверяются перед развёртыванием (как изменения кода)
• решение об изменении скрипта фиксируется в базе знаний с обоснованием

ОБЯЗАТЕЛЬНО (конфигурации Командная+):

• изменения скриптов тестируются на изолированном проекте перед распространением на все проекты
• ведётся реестр активных скриптов с идентификаторами версий
• обеспечивается возможность отката: любое изменение скрипта может быть возвращено к предыдущей версии
• ведётся аудиторский след изменений скриптов

РЕКОМЕНДУЕТСЯ:

• скрипты имеют критерии приёмки (что скрипт делает, не делает, граничные случаи)
• эффективность скриптов отслеживается через метрики (например, FPSR задач, выполненных под управлением данного скрипта)

5.4 Программный интерфейс

Программный интерфейс определяет инструменты, API и автоматизированные действия, доступные AI-агенту.

5.4.1 Инвентарь инструментов

Организации ОБЯЗАНЫ поддерживать инвентарь инструментов, доступных каждому Профилю агента:

• какие API-эндпоинты доступны
• какие операции с файловой системой разрешены
• какие внешние сервисы достижимы
• какие действия требуют подтверждения человеком

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

Каждый Профиль агента ОБЯЗАН иметь доступ только к инструментам, необходимым для его функции:

• Ревьюер НЕ ДОЛЖЕН иметь доступа на запись в продакшен-код
• Генератор НЕ ДОЛЖЕН иметь доступа к учётным данным развёртывания
• Верификатор НЕ ДОЛЖЕН иметь доступа к изменению результатов шлюзов качества

5.4.3 Автоматизированные действия (хуки)

Организации МОГУТ определять автоматизированные действия, запускаемые событиями:

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

Хуки ОБЯЗАНЫ быть под контролем версий наряду со скриптами.

5.5 Границы безопасности

5.5.1 Защита от инъекций промптов

Организации ОБЯЗАНЫ обеспечить, чтобы AI-агенты не обрабатывали ненадёжный пользовательский контент как инструкции. Когда агент читает внешние данные (пользовательский ввод, содержимое файлов, ответы API), они ОБЯЗАНЫ рассматриваться как данные, а не как команды. Операционным скриптам РЕКОМЕНДУЕТСЯ включать явные границы инструкций.

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

a) промпты агентов ОБЯЗАНЫ чётко разграничивать системные инструкции и пользовательские данные; b) внешние данные, загружаемые агентами (ответы API, содержимое файлов, записи базы данных), НЕ ДОЛЖНЫ интерпретироваться как команды агента или модификации поведенческого контракта агента; c) организациям РЕКОМЕНДУЕТСЯ тестировать конфигурации агентов на известные паттерны инъекций промптов в рамках Обзоров качества (Section 7.4).

5.6 Структурированный протокол инструментов

Организации ОБЯЗАНЫ предоставлять возможности платформы через структурированный самоописывающийся протокол инструментов, а не через CLI-команды или прямой доступ к базе данных. Выбранному протоколу РЕКОМЕНДУЕТСЯ обеспечивать:

a) самоописывающиеся схемы — агент получает определения инструментов с типами параметров и описаниями, что снижает число галлюцинированных аргументов; b) атомарные операции — каждый вызов инструмента представляет собой единую транзакцию, исключая режим отказа «цепочки команд»; c) структурированный ввод/вывод — исключение ошибок парсинга текстового CLI-вывода; d) журналирование аудита — каждый вызов инструмента записывается с параметрами и результатами.

NOTE: Примеры подходящих протоколов: Model Context Protocol (MCP), вызов функций OpenAI, пользовательские REST/gRPC API инструментов.

CLI как резерв: CLI-командам РЕКОМЕНДУЕТСЯ оставаться доступными, когда структурированный протокол инструментов недоступен. Организации ОБЯЗАНЫ документировать, какие операции имеют CLI-резерв, а какие работают только через протокол.

Прямой доступ к базе данных: AI-агенты НЕ ДОЛЖНЫ использовать прямой доступ к базе данных для операций записи. Операции чтения МОГУТ использовать прямой доступ для отладки, но продуктивные рабочие процессы ОБЯЗАНЫ использовать абстракции протокола или CLI.

5.7 Диспетчеризация агентов и изоляция выполнения

Диспетчеризация агентов — делегирование Задачи или подзадачи отдельному экземпляру AI-агента — несёт специфические риски:

a) делегированный агент работает с ограниченным контекстом (нет истории сессии, ограниченные знания); b) несколько делегированных агентов могут одновременно модифицировать одни и те же файлы; c) Супервайзер не может наблюдать за ходом рассуждений делегированного агента в реальном времени.

Организации, использующие диспетчеризацию агентов, ОБЯЗАНЫ:

1. Изолировать: делегированным агентам РЕКОМЕНДУЕТСЯ работать в изолированных рабочих копиях для предотвращения конфликтов файлов; NOTE: Примеры механизмов изоляции: рабочие деревья системы контроля версий, отдельные клоны репозитория, контейнеризованные среды сборки, эфемерные облачные пространства.
2. Ограничить область: промпты диспетчеризации ОБЯЗАНЫ включать явные границы — какие файлы модифицировать, какие оставить без изменений;
3. Проверить: все результаты делегированных агентов ОБЯЗАНЫ проходить Состязательное ревью L3 (Section 10.15) — диспетчеризация агентов является сценарием с наивысшим риском скрытых дефектов. Для Начальной конфигурации допускается замена на Ревью L2 с чеклистом высокого уровня, если независимый доступ к агенту недоступен (Section 10.15);
4. Контекст: промптам диспетчеризации РЕКОМЕНДУЕТСЯ включать релевантные Стандарты кода, архитектурные ограничения и известные проблемы из базы знаний;
5. Лимитировать: организации ОБЯЗАНЫ определить максимальное число параллельных диспетчеризаций на Супервайзера (применяется Section 10.7).

Делегированные агенты НЕ ДОЛЖНЫ:

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

Паттерн: Супервайзер делегирует → агент работает в изолированной копии → агент возвращает результат → Супервайзер проверяет → Супервайзер сливает в основную ветку.

5.8 Федерация — масштабирование SENAR на несколько проектов

Когда организация управляет несколькими проектами («федерация»), практики SENAR масштабируются с дополнительными требованиями к координации.

5.8.1 Независимость проектов

Каждый проект в федерации ОБЯЗАН поддерживать собственные:

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

5.8.2 Межпроектная координация

Федерации РЕКОМЕНДУЕТСЯ назначить координационный проект (аналог Release Train Engineer в SAFe), ответственный за:

• межпроектное отслеживание зависимостей
• маршрутизацию знаний в федерации (паттерн, обнаруженный в Проекте A, затрагивающий Проект B)
• агрегированные метрики (пропускная способность, стоимость, качество на уровне федерации)
• общие Стандарты кода и критерии ревью

5.8.3 Маршрутизация знаний

Записи знаний ОБЯЗАНЫ быть типизированы по области:

• Проектные: паттерны, известные проблемы и решения, релевантные только одному проекту — хранятся в базе знаний этого проекта;
• Межпроектные: паттерны, затрагивающие несколько проектов (изменения контрактов API, обновления общих библиотек) — хранятся в координационном проекте и маршрутизируются в затронутые проекты;
• Глобальные: методологические инсайты — хранятся в координационном проекте, доступны всем.

Организации ОБЯЗАНЫ определить правила маршрутизации: какие типы знаний распространяются автоматически, какие — с ручным повышением.

Межпроектные записи знаний ОБЯЗАНЫ требовать одобрения Супервайзера принимающего проекта перед включением в активный контекст этого проекта. Глобальные записи знаний ОБЯЗАНЫ требовать одобрения Супервайзера координационного проекта. Записи знаний, касающиеся тем безопасности (аутентификация, авторизация, шифрование, секреты, CORS, CSRF, разрешения), ОБЯЗАНЫ помечаться для проверки человеком независимо от правил маршрутизации.

5.8.4 Метрики федерации

Метрики уровня федерации агрегируют метрики проектов:

Организации НЕ ДОЛЖНЫ сравнивать «сырые» значения метрик между проектами с разными стеками, размерами команд или уровнями зрелости. Для сравнения РЕКОМЕНДУЕТСЯ использовать нормализованные метрики (например, стоимость на стори-поинт с учётом сложности).

5.9 Портируемость

Стандарт не привязан к конкретному AI-агенту, инструменту или платформе.

Операционные скрипты РЕКОМЕНДУЕТСЯ писать на структурированном естественном языке, интерпретируемом любым AI-агентом достаточной мощности:

• чёткие алгоритмические шаги (не платформоспецифичные вызовы SDK)
• явные входные и выходные данные на каждом шаге
• условная логика, выраженная на естественном языке
• никаких допущений о конкретных реализациях инструментов

Программный интерфейс МОЖЕТ быть платформоспецифичным (структурированные протоколы инструментов, API вызова функций и т.д.), но Поведенческий контракт и Операционные скрипты ОБЯЗАНЫ быть портируемыми между реализациями AI-агентов.

При миграции между AI-платформами организации ОБЯЗАНЫ:

• убедиться, что все Операционные скрипты корректно выполняются на новой платформе
• рекалибровать базовые значения метрик (Section 10.13: Управление моделью AI)
• обновить уровень Программного интерфейса, сохранив уровни Контракта и Скриптов