@reaatech/agent-handoff-routing

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Intelligent agent routing engine for selecting the best target agent during a handoff. Implements a weighted scoring algorithm with a route/clarify/fallback decision tree and an in-memory agent registry.

Installation

npm install @reaatech/agent-handoff-routing
# or
pnpm add @reaatech/agent-handoff-routing

Feature Overview

• Weighted scoring algorithm — skill match 40%, domain match 30%, load factor 20%, language match 10%
• Three-part decision tree — primary route, clarification when ambiguous, fallback when no match
• Ambiguity detection — triggers clarification when top two agents score within threshold
• Agent registry — in-memory Map<string, AgentCapabilities> with register/unregister/getAll
• Compatibility filter — excludes offline or overloaded agents before scoring
• Pluggable — implements HandoffRouter from @reaatech/agent-handoff

Quick Start

import { CapabilityBasedRouter, AgentRegistry } from '@reaatech/agent-handoff-routing';
import type { HandoffPayload, AgentCapabilities } from '@reaatech/agent-handoff';
 
const router = new CapabilityBasedRouter({
  minConfidenceThreshold: 0.7,
  ambiguityThreshold: 0.15,
  maxAlternatives: 3,
  policy: 'best_effort',
});
 
const registry = new AgentRegistry();
registry.register({
  agentId: 'ts-agent',
  agentName: 'TypeScript Specialist',
  skills: ['typescript', 'architecture'],
  domains: ['frontend', 'backend'],
  maxConcurrentSessions: 5,
  currentLoad: 1,
  languages: ['en'],
  specializations: [],
  availability: 'available',
  version: '1.0.0',
});
 
const decision = await router.route(payload, registry.getAll());
// decision.type: 'primary' | 'clarification' | 'fallback'

Exports

Router

Routing Policies

Scoring Formula

Each agent receives a weighted score (0–100):

score = (skillMatch × 0.4) + (domainMatch × 0.3) + (loadFactor × 0.2) + (languageMatch × 0.1)

• Skill match: Jaccard similarity between requiredSkills and agent’s skills
• Domain match: Jaccard similarity between message context and agent’s domains
• Load factor: 1 - (currentLoad / maxConcurrentSessions), scaled to 0–100
• Language match: 100 if user language matches agent, 50 for partial, 0 for no match

Decision Types

Agent Registry

Related Packages

• @reaatech/agent-handoff — Core types, errors, utilities
• @reaatech/agent-handoff-compression — Context compression strategies
• @reaatech/agent-handoff-protocol — Full orchestration layer

License

MIT