Перейти до основного вмісту

ADR-001: Agent-Tasks Message Pipeline

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

Контекст​

Раніше inbound-хендлери каналів тримали у себе забагато логіки асистента. WhatsApp і Telegram-хендлери нормалізували транспортний payload, шукали розмови, запускали prompt-injection-перевірки, класифікували наміри, викликали RAG, оцінювали confidence і маршрутизували у HITL або на outbound-доставку.

У такій формі основну поведінку асистента було важко спостерігати та переюзовувати:

  • кожен канал міг дрейфувати відносно інших;
  • довгі LLM- і RAG-операції жили всередині channel-воркерів;
  • тест-режим потребував реальних канальних залежностей, щоб прогнати pipeline;
  • тригери ескалації були розкидані між persona-конфігом і control flow каналу;
  • видимість прогресу обмежувалась фінальними результатами на стороні каналу.

Рішення​

Використовуємо agent-tasks як канонічну межу асинхронного виконання для відповідей асистента.

Channel-воркери виконують тільки транспортну роботу:

  1. парсять inbound WhatsApp Cloud API / Telegram;
  2. знаходять або створюють User, Conversation і inbound Message;
  3. створюють AgentTask;
  4. ставлять BullMQ-джоб у чергу agent-tasks.

Agent runner worker володіє assistant-pipeline:

  1. inject_profile завантажує system prompt простору імен і контекст employee profile;
  2. rag_search запускає OpenAiRagPipeline або fallback-адаптер, коли RAG-залежність відсутня;
  3. generate форматує відповідь каналу;
  4. confidence_check керує injection-маршрутизацією, тригерами ескалації персони, intent-класифікацією, confidence-fallback і обходом матриці довіри;
  5. воркер маршрутизує на outbound-доставку, очікування схвалення або staff-ескалацію.

Кожен крок зберігається як AgentToolCall, тож API-клієнти та WebSocket-підписники можуть спостерігати прогрес.

Наслідки​

Позитивні​

  • Єдиний pipeline керує WhatsApp, Telegram і майбутніми каналами.
  • Канальні адаптери лишаються сфокусованими на транспортних задачах.
  • Статус agent task і прогрес tool-call спостережні через REST та WebSocket API.
  • Ескалація персони оцінюється в тому самому місці, що й trust- і confidence-гейти.
  • Тест-режим може використовувати детерміновані adapter-залежності без запуску реальних каналів.

Негативні​

  • Воркеру потрібен чіткий outbound-залежний канал для кожного підтримуваного каналу.
  • Шлях fallback-адаптера має лишатись узгодженим із повним RAG-шляхом, щоб тести не приховували лише прод-поведінку.
  • Рядки AgentTask стають частиною critical path і потребують регулярного 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 adapter config: Namespace.config.agentRunner.activeAdapter.

Старий channel-owned RAG-шлях більше не є основним message pipeline. OpenAiRagPipeline лишається retrieval/generation-компонентом, який використовує agent runner, а також POST /api/v1/rag/draft для ручних RAG-тестів.