ACAgentic Craft

Intermediate~14 minHazelJS

Router

Route intents to specialized agents or subgraphs with AgentGraph conditional edges or SupervisorAgent.

Authors
editorial-team
Published
Last reviewed

Problem

One monolithic agent underperforms across heterogeneous intents and over-exposes tools.

Context

Products with distinct domains (billing vs shipping vs FAQ) that need cheap classification before specialized handling.

Forces and constraints

  • Specialization improves quality and shrinks tool surfaces
  • Mis-routing wastes steps and budget
  • Routers themselves need evals

Recommended design

Classify first with a narrow router (SupervisorAgent/createSupervisor or AgentGraph addConditionalEdge), then invoke a specialist with a curated ToolRegistry. Keep the router read-mostly; deny write tools on the router identity.

Minimal pseudocode

import { createSupervisor, createGraph } from '@hazeljs/agent';

// Option A — supervisor router
const supervisor = createSupervisor({
  agents: [billingAgent, shippingAgent, faqAgent],
});

// Option B — conditional graph edge
const g = createGraph();
g.addNode('router', routerAgent);
g.addNode('billing', billingAgent);
g.addConditionalEdge('router', (state) =>
  state.intent === 'billing' ? 'billing' : 'faq',
);

Failure modes

  • Router has write tools and acts instead of routing
  • No fallback specialist for unknown intents
  • Router prompt drift without describeAgent coverage

Security considerations

  • Least-privilege ToolRegistry per specialist
  • Capabilities scoped per agent identity

Observability signals

  • Log chosen specialist + confidence
  • Metric: misroute rate from evals

Evaluation approach

Golden intents → expected specialist; forbidden-tool tests on router.

Trade-offs

  • Extra hop latency vs better specialization
  • More agents to version and observe

Sources

Related patterns