Design a supervisor that routes without absorbing every specialty

Pattern 04 companion: Python example · Behavioral tests · Example license

Route according to a real capability boundary

A checkout incident can require latency analysis or availability analysis. The specialists may use different evidence, rubrics and access scopes. A supervisor chooses the applicable specialist and packages the minimum context it needs. The design is useful when that boundary is genuine. If both specialists receive the same prompt, data and permissions, splitting them may only add latency and an extra place to lose context. Start by naming the distinct question each specialist answers.

Our original teaching supervisor accepts a typed ticket containing incident, service and symptom. The symptom is used for routing. Only incident and service cross into the selected specialist's envelope. The result is a fixture reference for review. The supervisor does not merge unlimited conversations or let specialists recursively delegate. This constrained arrangement makes the routing and handoff contract easier to inspect before adding more sophisticated model-driven behavior.

Architecture and request sequence

Component diagram for Design a supervisor that routes without absorbing every specialty — Original reference architecture by Sandeep Belgavi. Arrows show the responsibilities and transitions described below.

Request sequence for Design a supervisor that routes without absorbing every specialty — Illustrative sequence for this design; failure and recovery variants are explained in the article.

Authorize the ticket before asking for a route

The service must belong to the caller's allowed set before routing begins. This prevents a model from deciding whether the caller may investigate a service. In a production system, the allowed set comes from authenticated policy, not an untrusted request field. The routing model can propose latency or availability only after that check. An unfamiliar proposal becomes escalation rather than a dynamically created specialist with unknown privileges.

Separate permission to choose a specialist from permission to execute its tools. A valid latency route does not grant access to every latency dataset in the organization. The specialist receives the scoped service and must enforce it at its connector boundary. The companion module illustrates the envelope but does not implement real identities or connector authorization. A production design needs both; otherwise the supervisor's careful ticket check can be undone by an overly broad specialist credential.

Make the handoff smaller and more explicit

A useful handoff includes incident identity, authorized service, task question, evidence time window and expected result schema. Do not send the entire supervisor conversation simply because it is available. That can expose irrelevant customer data, conflicting instructions and decisions the specialist should not inherit. The small fixture sends only incident and service to demonstrate minimization, so a real implementation would need to add an explicit question and window before meaningful analysis.

The result contract should identify evidence, limitations and whether more information is required. The supervisor validates it before presenting a package for review. In the demo, validation merely requires a string beginning with fixture:. That is a syntax check, not proof that the referenced observation exists. A production resolver must retrieve the object under authorized access and verify service identity and capture time. Keep those stages separate in logs and acceptance tests.

Plan fallback without routing loops

Unknown symptoms, unavailable specialists and worker failures are different conditions. An unknown route should ask for clarification or escalate. A missing deployed specialist should produce a configuration alert. A worker error may be transient or may indicate a contract violation. Do not send all three to another general model and hope it finds an answer. A fallback needs an explicit purpose, scope and remaining budget.

For a first deployment, use at most one specialist invocation per ticket and make unresolved outcomes visible. Later, permit a second route only when a documented rule explains why the original route was insufficient. Carry a visited-route list and parent ticket identity so the system cannot bounce between latency and availability forever. A specialist asking for additional evidence is not permission to delegate to an arbitrary worker. The supervisor remains accountable for the overall investigation budget.

Size capacity by specialist demand

Assume an illustrative intake of sixty tickets per hour, with three quarters routed to latency and one quarter to availability. Allocating equal worker pools can leave latency queued while availability sits idle. Observe route distribution, duration and rejection rate before choosing capacity. Reserve admission headroom for incident bursts and a manual path for unknown cases. The supervisor's own latency is only one part of the user-visible delay; queueing at the selected specialist often dominates.

Track classification errors and specialist usefulness separately. A specialist can perform correctly on the wrong ticket, while a correct route can still return poor evidence. Evaluate routing on labeled symptoms, including ambiguous cases that should escalate. Evaluate specialists on scoped tasks with independently checked evidence. Do not optimize only for fewer escalations; a lower escalation rate can mean the router is becoming overconfident about cases outside the supported taxonomy.

Sources and scope

The contracts here are original designs by Sandeep Belgavi, reflected in the supervisor fixture. The Evals collection provides measurement prerequisites. The example is not a vendor routing API or a deployed multi-agent platform. Capacity figures are assumptions, and the syntax-only result check must not be presented as verified evidence retrieval.