@mallocbaal/agent-framework (TypeScript)

TypeScript-библиотека с функционалом, аналогичным Go agent-framework: event-driven агенты с RabbitMQ и saga-логированием.

Требования: Node.js >= 20

Установка

npm install @mallocbaal/agent-framework
# или из монорепо
pnpm add @mallocbaal/agent-framework

Быстрый старт

import { loadConfig, App, type EventHandler, type Event } from '@mallocbaal/agent-framework';

class MyAgent implements EventHandler {
  async handle(_ctx: AbortSignal | undefined, event: Event): Promise<void> {
    switch (event.eventType) {
      case 'CLI_FLOW_INIT':
        return this.handleInit(event);
      case 'CLI_FLOW_CONTINUE':
        return this.handleContinue(event);
      case 'CLI_FLOW_END':
        return;
    }
  }

  private async handleInit(_event: Event): Promise<void> {
    // инициализация диалога
  }

  private async handleContinue(_event: Event): Promise<void> {
    // обработка сообщения или action
  }
}

async function main() {
  const config = loadConfig();
  const handler = new MyAgent();
  const app = await App.create({ config, handler });
  await app.run(); // до Ctrl+C или abort
}
main().catch(console.error);

Структура (аналог Go)

| Модуль | Назначение | |---------------|-------------------------------------| | events | Типы событий CLI_FLOW_* | | config | Загрузка конфигурации из env | | dispatcher | Маршрутизация INIT/CONTINUE/END | | rabbitmq | Consumer с retry | | saga | SagaLogger, MinIO, типы событий саги| | communicator| Клиент Communicator (GraphQL) | | pipeline | Processing + PostProcessing stages | | app | Жизненный цикл, health, bot register|

Конфигурация (env)

• PORT — порт health (по умолчанию 8091)
• COMMUNICATOR_URL — URL сервиса communicator
• RABBITMQ_URL, RABBITMQ_EXCHANGE, RABBITMQ_QUEUE, RABBITMQ_BINDINGS, RABBITMQ_PREFETCH, RABBITMQ_MAX_RETRIES
• MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_USE_SSL
• BOT_KEY, BOT_NAME, BOT_EVENT_STREAM, BOT_STREAMING_ENABLED

EventProcessor + Dispatcher

Вместо одного EventHandler можно реализовать EventProcessor и обернуть в Dispatcher:

import { Dispatcher, type EventProcessor, type Event } from '@mallocbaal/agent-framework';

class MyProcessor implements EventProcessor {
  async handleInit(_ctx, ev: Event) { /* ... */ }
  async handleContinue(_ctx, ev: Event) { /* ... */ }
}

const processor = new MyProcessor();
const dispatcher = new Dispatcher(processor);
const app = await App.create({ config, handler: dispatcher });

Pipeline

Использование паттерна Processing → Communicator → PostProcessing:

import {
  Pipeline,
  createProcessingFunc,
  createPostProcessingFunc,
  createCommunicatorClient,
  loadConfig,
  App,
  type ProcessingStage,
  type PostProcessingStage,
  type Event,
} from '@mallocbaal/agent-framework';

class MyStage implements ProcessingStage, PostProcessingStage {
  async processInit(_, ev) {
    return { contents: [{ type: 'text', order: 0, data: { text: 'Hello!' } }] };
  }
  async processContinue(_, ev) {
    return { contents: [{ type: 'text', order: 0, data: { text: 'You said: ' + (ev.message ?? '') } }] };
  }
  async postProcessInit() {}
  async postProcessContinue() {}
}

const config = loadConfig();
const comm = createCommunicatorClient(config.communicator.baseURL);
const pipeline = new Pipeline(comm, {
  processing: createProcessingFunc(new MyStage()),
  postProcessing: createPostProcessingFunc(new MyStage()),
}, 'my-agent');
const app = await App.create({ config, handler: pipeline });
await app.run();

Health

• GET /healthz — 200 OK
• GET /readyz — 200 если RabbitMQ доступен, иначе 503

Сборка

npm run build

Генерируется dist/ с ESM и декларациями.