Перейти к основному содержимому

Руководство для разработчиков: от промпта до продакшна

Введение​

⚠️ Важно: ИИ-агенты — это программное обеспечение, к которому применяются все правила и стандарты разработки ПО.

Это означает:

  • Версионирование кода и промптов
  • Тестирование и CI/CD
  • Мониторинг и наблюдаемость
  • Безопасность и управление доступом
  • Документирование и поддержка

Шаги создания ИИ-агента​

Для создания ИИ-агента необходимо пройти несколько последовательных этапов — от выбора модели до настройки интеграций и тестирования автономных действий:

1. Подключение к LLM​

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

  • Внутренняя корпоративная модель
  • Внешний API

2. Выбор SDK/фреймворка​

Определите технологический стек для реализации логики агента.

Рекомендуемый фреймворк: LangGraph (Python), расширяющий возможности LangChain для построения графов агентов и реализации мультиагентных сценариев.

Важно: Возможность выбора дополнительного фреймворка для JVM-экосистемы (Java / Kotlin).

3. Настройка системного промпта​

Создайте системный промпт — базовое описание роли и поведения агента:

  • Описать личность и цель агента
  • Форматы ввода-вывода
  • Ограничения и прочие инструкции

Промпт оформляется с учётом лучших практик Prompt Engineering.

4. Определение инструментов (Tools) или MCP-серверов​

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

  • API-вызовы
  • Базы данных
  • Файловые системы
  • MCP-сервера
  • Внутренние сервисы

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

  • ✅ Чёткое имя и описание
  • ✅ Сигнатуру вызова (input/output schema)
  • ✅ Политику доступа

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

5. Интеграция с корпоративными системами​

Настройте взаимодействие агента с внутренними системами:

  • Базы данных
  • Поисковые сервисы
  • Иные источники знаний

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

6. Observability и управление ошибками​

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

Включите следующие компоненты:

  • Tracing — отслеживание цепочки действий и вызовов инструментов
  • Logging — подробные логи reasoning-процессов, запросов и ответов
  • Monitoring — контроль метрик производительности и успешности задач
  • Error handling & retry logic — обработка ошибок и повторные вызовы внешних систем при сбоях

7. Внутренние итерации и проверка корректности​

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

Компоненты ИИ-агентов​

Input Handler (обработчик ввода)​

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

Основные функции:

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

Пример: Пользователь вводит: «Какая погода в Париже?». Handler удаляет невидимые символы и формирует структуру.

Тип: ✅ обязательный

Agent Orchestrator (контроллер агента)​

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

Основные функции:

  • Инициализация цикла Reason → Act → Observe
  • Координация данных между модулями
  • Принятие решения о завершении или продолжении сессии
  • Управление памятью агента (Memory API)

Архитектурные варианты реализации:

Оркестратор может быть реализован в разных архитектурных стилях — в зависимости от задач и платформы:

  1. LLM-Orchestration (основной подход): классическая схема на основе большой языковой модели, где LLM управляет планом и вызовами инструментов.

  2. BERT-based/Embedding based Orchestration: оркестрация через эмбеддинги и классификацию намерений, когда агент не "думает", а выбирает из предопределенных сценариев на основе векторного сходства.

  3. Hybrid LLM + Deterministic Fallbacks: комбинированный подход, где LLM взаимодействует с детерминированными правилами и fallback механизмами.

Пример: Пользователь задал вопрос. Orchestrator вызывает reasoning(), получает план от Planner, затем передаёт задачу Action Selector.

Тип: ✅ обязательный

Planner (планировщик)​

Назначение: Разбивает задачу на подзадачи и формирует план действий.

Основные функции:

  • Декомпозиция пользовательской задачи
  • Формирование списка шагов и инструментов
  • Передача плана Orchestrator или Executor

Пример: Запрос: «Сколько будут 100 USD в рублях?» Планировщик строит план: Получить курс доллара → Умножить → Вернуть результат.

Тип: ⚙️ опциональный (рекомендуется для сложных сценариев)

Memory (Память)​

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

Основные функции:

  • Сохраняет контекст диалога и промежуточные результаты
  • Предоставляет доступ к прошлым данным другим модулям (Reasoning, Orchestrator)
  • Поддерживает кратко-, средне- и долгосрочную память

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

Тип: ✅ обязательный

Reasoning Module (модуль рассуждения)​

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

Основные функции:

  • Анализ контекста и истории
  • Генерация рассуждений и гипотез (Chain-of-Thought)
  • Выбор следующего действия

Тип: ✅ обязательный

Action Selector (выбор действия)​

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

Основные функции:

  • Интерпретирует рассуждение LLM и выделяет требуемое действие
  • Выбирает тип операции: вызов API, запрос к БД, генерация ответа и др.
  • Формирует команду для исполнения и передаёт её в Action Executor

Пример: Агент получает мысль: "Нужно узнать погоду в Париже." Action Selector выбирает инструмент weather_search и передаёт команду на его вызов.

Тип: ✅ обязательный

Action Executor (исполнитель действий)​

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

Основные функции:

  • Исполняет команды от Action Selector (API-вызовы, SQL-запросы, скрипты)
  • Обрабатывает ошибки и выполняет повторные попытки при сбоях
  • Возвращает результат в унифицированном формате для дальнейшего анализа

Пример: Executor получает команду вызвать API погоды для города Париж, выполняет запрос и возвращает данные: "+22°C, солнечно."

Тип: ✅ обязательный

Response Generator (генератор ответа)​

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

Основные функции:

  • Объединяет результаты reasoning и вызовов инструментов в связный текст
  • Применяет форматирование и стили (Markdown, эмодзи, структура сообщений)
  • Отбирает релевантную информацию, скрывая внутренние детали рассуждений

Пример: Агент получил факт: «Париж: +22°C, солнечно». Response Generator формирует сообщение: «В Париже сейчас +22°C, ясно и без осадков ☀️».

Тип: ✅ обязательный

Reflector (рефлектор)​

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

Основные функции:

  • Анализ логов reasoning/action
  • Обнаружение неэффективных шагов
  • Коррекция стратегии или повтор запроса

Пример: Агент использовал старый курс валют. Reflector инициирует повторный вызов API.

Тип: ⚙️ опциональный (для надежных сценариев)

Observation Handler (обработчик наблюдений)​

Назначение: Получает результат от Action Executor и преобразует его в удобную форму для дальнейшего анализа и рассуждения LLM.

Основные функции:

  • Принимает данные от инструментов (текст, JSON, таблицы и др.)
  • Суммирует или преобразует объёмные результаты в краткое, релевантное описание
  • Обновляет память агента (Memory) для использования на следующих шагах reasoning

Пример: Агент получил от API большой прогноз погоды. Observation Handler извлекает только текущие условия — «Париж, +22°C, солнечно» — и сохраняет их в память как новое Observation.

Тип: ✅ обязательный

Output Handler (обработчик вывода)​

Назначение: Отвечает за доставку финального ответа пользователю и его корректное отображение во внешнем интерфейсе. Это мост между ядром агента и внешним миром.

Основные функции:

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

Пример: агент сформировал сообщение «В Париже сейчас +22°C и солнечно». Output Handler форматирует его под интерфейс веб-чата банка, добавляет фирменное оформление и отправляет пользователю.

Тип: ✅ обязательный

Guardrails (система безопасности)​

Назначение: Защищает агента от опасных или запрещённых действий.

Основные функции:

  • Проверка промптов и действий на нарушения
  • Блокировка опасных команд
  • Мониторинг аномалий и аудит

Пример: Запрос: "Сколько денег на счёте клиента X?" Guardrails блокирует действие и формирует отказ с уведомлением службы безопасности.

Тип: ✅ обязательный для production-среды

Ключевые технические метрики ИИ-агента​

КритерийМетрикаОписаниеЦелевое значение
Качество reasoning и ответов1. accuracy
2. confidence_score
3. consistency_rate		1. Совпадение с эталонным ответом
2. Самооценка уверенности LLM
3. Доля логически согласованных ответов		Зависит от задачи
Производительность1. Время ответа
2. token_efficiency
3. RPS		1. Время ответа агента
2. Расход токенов
3. Количество запросов		Зависит от SLA
Надежность1. error_rate
2. availability		1. Ошибки LLM
2. Доступность сервиса		error_rate < 5%
availability > 99%

Протоколы взаимодействия​

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

Протоколы связи​

Тип взаимодействияИспользуемый протоколПрименениеФормат данных
Синхронное (запрос–ответ)REST API over HTTP(S)Для мгновенного отклика пользователю или цепочки коротких операцийJSON
Асинхронное (событийное)Kafka / RabbitMQ / NATSДля долгих процессов, обмена между агентами, буферизации и обеспечения отказоустойчивостиJSON / Avro / Protobuf
Streaming / RealtimeWebSocket / SSE / gRPC-streamДля стриминговых ответов (например, потоковый вывод от LLM)Текст / JSON-chunks

📝 Рекомендация​

Выбирайте протокол исходя из паттерна работы агента:

  • REST — быстрые операции и интерфейс с пользователем
  • Message Broker — фоновые задачи, цепочки Reason→Act→Observe
  • Streaming — интерактивные интерфейсы и "thinking traces"

Производительность и параллелизм​

ИИ-агенты — в основном I/O-bound системы, где время уходит на ожидание ответа от моделей, API и баз данных. Поэтому базовая архитектура должна быть асинхронной.

Рекомендации:

  • Используйте asyncio / FastAPI / aiohttp (Python) или Project Reactor / Kotlin coroutines (JVM)
  • Взаимодействие с LLM выполняется через OpenAI-compatible API — это позволяет быстро переключаться между моделями разных вендоров (включая корпоративные)
  • Продумайте очередь reasoning-итераций, чтобы агент мог параллельно обрабатывать несколько контекстов без взаимных блокировок

Технологический стек​

КомпонентНазначениеТехнологии/подходы
Протокол связи с языковыми моделямиВзаимодействие с LLM (внутренние/внешние)LiteLLM, OpenAI API
Пайплайн обработки естественного языкаИсточники основных инструментовHuggingFace models
RAG / Knowledge ContextОбогащение агента даннымиVector DB: CUVS, Milvus, FAISS, Qdrant
Graph DB: Falcor, RedisGraph, memGraph, Apache AGE
Коннекторы к внутренним системамJira, Confluence, PowerBI, Email, CRM, ERP, трекеры, базы данных, календарьStreamable API (for Agents, LLM), Classic REST API + Inhouse ingress platforms
Tool-коннектор к внешним источникамВзаимодействие с экосистемамиMCP or A2A, or ACP

Прототипирование и шаблон агента​

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

Преимущества прототипа:​

  • ✅ Единая структура кода и логики исполнения (Reason → Act → Observe)
  • ✅ Упрощённая работа с ИИ-ассистентами при написании кода
  • ✅ Возможность описать задачу в промпте и явно указать, какую логику реализовать на каждом шаге

Чек-лист для продуктивизации​

Критерий
☑ Есть описание flow работы агента и бизнес-задачи
☑ Промпты версионированы и хранятся в репозитории
☑ Проведена оценка качества (eval) на основе golden set или human-eval, результаты задокументированы и приложены к артефактам релиза
☑ Настроены fallback-механизмы при падении критических компонентов
☑ API-контракты протестированы, есть retry-логика, идемпотентность, мониторинг
☑ На входе/выходе агента стоят guardrails и PII-маскинг
☑ Включён трейсинг, логирование reasoning-процесса
☑ Определен on-call ответственный за продакшн-агента

Список рекомендованных технологий​

КатегорияТехнологии
SDKLangchain-AI (Langgraph)
Сервис и протокол мониторинга/трейсингаOpen Telemetry protocol
Jaeger Tracing server
Выбранный RAG рецепт и средство оценки RAGRAG: FAISS, Milvus, CUVS or AlfaBank ARAG
QA: Ragas Framework
Взаимный hand-off механизмMCP
Механизм deploy (платформа или иное)1. LangGraph Server: The server defines an opinionated API and architecture that incorporates best practices for deploying agentic applications
2. Langchain-platform
LangGraph Platform
Выбранный guardrailGuardrails-AI или АльфаБанк Цензор-модуль
Метрики эффективности агентов после deploy1. tool_calls: The total number of tool calls
2. tool_call_errors: The total number of tool call errors
3. list_calls: The total number of list calls
4. read_resource_calls: The total number of read resource calls
5. get_prompt_calls: The total number of get prompt calls
6. agent_calls: The total number of agent calls
Agent Gateway Metrics
Согласовать допустимые внешние поставщики данныхYandex GPT, Yandex MCP, Gigachat
Защита от угроз: список процедур аудитаСогласно модели угроз
Протокол взаимодействия агентов с позиции gateway, шифрованияMCP with Encrypted TLS 1.2+ with issued private file certificate for both sides
Или СКЗИ согласно модели угроз с преимущественно аппаратной реализацией. Тип и класс применяемого СКЗИ определяется по результатам согласования модели угроз, при необходимости с учетом требований органов государственной власти

Мультиагентные системы​

Разница между AgentOps и мультиагентной системой​

ПараметрAgentOps системаМультиагентная система
НазначениеОперационная платформа для управления жизненным циклом агентовСовокупность агентов, совместно решающих бизнес-задачу
ФокусУправление, наблюдаемость, безопасность, CI/CD агентовВзаимодействие, распределение ролей и координация действий
Ключевые функцииТрейсинг, логирование, оркестрация, доступы, политики, мониторингПланирование, коммуникация, принятие решений между агентами
КомпонентыLangFuse / LangSmith / Phoenix, Guardrails, Policy Engine, DashboardLLM-агенты, планировщик, контексты, shared memory
Аналогия"DevOps для ИИ-агентов""Команда ИИ-сотрудников"

Кратко:​

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

Что необходимо для создания AgentOps-системы​

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

Необходимо создать единый операционный контур (AgentOps), который обеспечивает:

  • ✅ Унификацию подходов — общие стандарты взаимодействия, логирование reasoning-процессов, единый формат промптов и метаданных.

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

  • ✅ Соблюдение политик компании — автоматический мониторинг соблюдения правил безопасности, комплаенса и хранения данных.

  • ✅ Наблюдаемость и контроль качества — сквозной трейсинг, метрики, алерты и аудит reasoning-цепочек.

  • ✅ Масштабируемость и оркестрацию — возможность гибко распределять нагрузку между агентами, создавать новые экземпляры и обновлять их без простоев.

Иными словами, AgentOps — это не просто набор инструментов, а инфраструктура, объединяющая агентов, данные, пользователей и процессы в управляемую экосистему.

Создание AgentOps-системы — это переход от разработки отдельных ИИ-агентов к построению корпоративного стандарта управления их жизненным циклом.

Такой подход превращает набор экспериментов с LLM в устойчивую корпоративную платформу, обеспечивающую безопасность, управляемость и воспроизводимость ИИ-процессов.

Следующие шаги​