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

ADR-001: Конвейер сообщений для задач агента

  • Статус: Принято
  • Дата: 14 апреля 2026
  • Автор: CTO Agent (KALA-107)

Контекст​

Handlers входящих каналов изначально владели слишком большой частью ассистент-флоу. WhatsApp- и Telegram-хендлеры нормализовали транспортный payload, искали разговоры, проверяли на prompt injection, классифицировали intents, вызывали RAG, оценивали confidence и маршрутизировали в HITL или outbound-доставку.

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

  • каждый канал мог отклоняться от других;
  • длинные LLM- и RAG-операции жили внутри channel-специфичных воркеров;
  • в тестовом режиме для проверки пайплайна требовались реальные зависимости каналов;
  • триггеры эскалации были размазаны между конфигурацией пользователя и control flow канала;
  • видимость прогресса ограничивалась финальными результатами на стороне канала.

Решение​

Использовать agent-tasks как каноническую границу асинхронного выполнения ответов ассистента.

Channel workers делают только работу, специфичную для транспорта:

  1. парсят входящий payload WhatsApp Cloud API или Telegram;
  2. находят или создают User, Conversation и входящий Message;
  3. создают AgentTask;
  4. ставят BullMQ-задачу в очередь agent-tasks.

Agent executor worker владеет ассистент-пайплайном:

  1. inject_profile — подгружает system prompt namespace и контекст профиля сотрудника;
  2. rag_search — запускает OpenAiRagPipeline или fallback-адаптер, если RAG-зависимость не подключена;
  3. generate — формирует ответ канала;
  4. confidence_check — управляет маршрутизацией injection guard, триггерами persona escalation, intent-классификацией, fallback по уверенности и обходом матрицы доверия;
  5. воркер маршрутизирует в outbound-доставку, ждёт approval или уходит в persona escalation.

Каждый шаг сохраняется как AgentToolCall, чтобы API-клиенты и WebSocket-подписчики видели прогресс.

Последствия​

Плюсы​

  • Один пайплайн управляет WhatsApp, Telegram и будущими каналами.
  • Channel-адаптеры остаются сфокусированы на транспортных задачах.
  • Статус agent task и ход tool-call можно наблюдать через REST API и WebSocket.
  • Persona escalation оценивается в том же месте, что и trust gate.
  • В тестовом режиме можно использовать детерминированные adapter-зависимости без запуска реальных channel-ботов.

Минусы​

  • Воркеру нужны явные outbound-зависимости для каждого поддерживаемого канала.
  • Путь через fallback-адаптер должен оставаться согласованным с полным RAG-путём, иначе тесты скроют production-only поведение.
  • Строки AgentTask становятся частью критического пути — нужна регулярная retention/cleanup-политика.

Заметки по реализации​

  • Имя очереди: agent-tasks.
  • Воркер: src/agent-runner/worker.ts.
  • Fastify-плагин: src/plugins/agent-runner.ts.
  • REST API: GET /api/v1/agent-tasks, GET /api/v1/agent-tasks/:id, GET /api/v1/agent-tasks/stats.
  • WebSocket API: ws://<host>/ws/agent-tasks.
  • Конфиг namespace-адаптера: Namespace.config.agentRunner.activeAdapter.

Старый channel-owned RAG-путь больше не основной пайплайн сообщений. OpenAiRagPipeline остаётся retrieval/generation компонентом, который использует agent runner и POST /api/v1/rag/draft для ручного тестирования RAG.