I was looking at a route decision that wanted to be clever before it had earned the right to be boring. The system needed to send an AI agent task to the right execution broker, including an EC2 frontend path, but the dangerous part was not the model call. It was letting model-assisted typed intent routing feel like a dispatcher when it should have been evidence for a dispatcher. The useful rule we adopted was simple: the model can classify a route, but deterministic scope and explicit execution gates decide whether anything touches the broker.
- Pattern
- Typed route evidence before broker execution
- Output
- Agent operating note
- Use when
- An agent must choose an execution path before invoking infrastructure, broker, or frontend automation
Typed intent routing belongs before authority
The incident was not dramatic, which is usually how the useful ones arrive. We had a candidate routing architecture for an internal agent: deterministic scope first, then a model-assisted EC2 frontend routing decision through an authenticated Codex subscription. The model was required to answer with strict JSON Schema, and the route was validated before broker execution.
That sounds like plumbing until you consider the failure mode. If a model picks a route as prose, a broker has to infer what it meant. If a model picks a route as typed data, the broker can reject it, log it, compare it with policy, and fall back when the provider fails. The difference is not elegance. It is whether a wrong answer is a paragraph or a failed contract.
The PR that added the design made a few constraints explicit. Profile, intent, scope, confidence, and approval floor had to validate before execution. Route source, latency, fallback reason, decision, and profile had to persist into session events or artifacts. Shortcuts stayed deterministic. Keyword routing remained available only as a declared provider-failure fallback, not as a silent second brain.
The ADR was accepted only after live Slack and EC2 validation. That mattered. A routing ADR accepted from local reasoning alone would have been a nice document about a path nobody had watched under the actual connector and infrastructure constraints. We have enough nice documents already. Some of them are technically compost.
The failed move was treating route choice as intent alone
A reasonable team can look at this problem and say, "Let the model infer the intent, then call the matching broker." That is attractive because it keeps the router small. It is also where the design gets slippery.
Intent is not authority. Scope is authority-adjacent. Approval floor is authority-adjacent. Confidence is evidence, not permission. Profile selects the operational shape. If those pieces are collapsed into a single model answer, the broker receives a vibes-based packet with a JSON hat on.
The rejected alternative was keyword routing as the primary mechanism. It was deterministic, cheap, and easy to explain. It also failed the actual routing problem because shortcuts and keywords are good at known doors, not at deciding when a frontend EC2 path is the right execution surface for a task that may be phrased several ways. We kept keyword routing, but only as a declared fallback when the model provider path fails. That preserves its best property: predictability under degraded conditions.
The other rejected alternative was letting the model directly name the broker operation. That would have made the route decision feel precise while moving too much authority into the classification step. The chosen design makes the model name typed intent and route evidence. The execution layer still checks whether the profile, scope, and approval floor permit the broker call.
A routing contract reviewers can actually use
Here is the reusable artifact I would put into review for any team adding agent routing in front of real execution surfaces.
Typed routing review contract
Use this contract when an AI agent selects an execution path before invoking a broker, connector, infrastructure operation, or frontend automation.
Required route decision
Every route candidate must produce a typed decision with these fields before execution:
| Field | Required meaning | Rejection condition |
|---|---|---|
profile | The operational profile selected for this run | Missing, unknown, or not allowed for the session |
intent | The task intent in the router vocabulary | Missing, ambiguous, or outside the approved intent set |
scope | The deterministic execution scope computed before model routing | Missing, widened by the model, or inconsistent with the request |
confidence | The model route confidence as evidence | Below the configured threshold or absent |
approval_floor | The minimum human approval level required before execution | Lower than policy requires for the selected scope |
Mandatory order
- Compute deterministic scope from the request and session context.
- If a deterministic shortcut fully resolves the route, use it and record
route_source=shortcut. - If no shortcut resolves it, request a strict-schema model route.
- Validate
profile,intent,scope,confidence, andapproval_floor. - Persist route evidence before broker execution.
- Execute only if the approval floor and scope gates pass.
- If the model route provider fails, use keyword fallback only when the fallback is declared and recorded.
Evidence to persist
Each session event or artifact must include:
| Evidence | Why it exists |
|---|---|
route_source | Distinguishes shortcut, model, fallback, and manual route paths |
route_latency_ms | Shows whether routing cost is operationally acceptable |
fallback_reason | Prevents silent degradation into keyword behavior |
decision | Preserves the typed route candidate that was evaluated |
profile | Lets later review connect execution behavior to the selected run profile |
Review questions
- Can the model widen scope, or can it only classify inside the deterministic scope?
- Is keyword routing a declared provider-failure fallback, or an unlogged competing router?
- Is the approval floor checked before broker execution?
- Are live connector and infrastructure validations linked before the ADR is accepted?
- Can a reviewer reconstruct why the broker was touched without reading the whole transcript?
The artifact is intentionally a little dull. That is the point. Agent routing should leave behind artifacts that a reviewer can inspect without replaying the conversation or trusting the model's self-description.
The staff tradeoff is latency for auditability
The design costs something. You pay an additional model call on the non-shortcut path, plus validation code, persistence code, and review surface. You also create another schema that can drift from the broker vocabulary if nobody owns it. These are real costs, not ceremonial architecture taxes.
The recommendation stops being correct under a few conditions. If the route space is tiny and stable, deterministic routing may be enough. If the action has no meaningful authority, a typed pre-broker gate may be more ceremony than control. If the team cannot persist route evidence and inspect it later, strict schema gives you less than it appears to give. A typed answer thrown away after execution is just a more expensive shrug.
For this case, the trade was worth it because the route sat before an execution broker and an EC2 frontend path. A wrong route could select the wrong operational profile or require a different approval floor than the task deserved. The model's classification was useful, but only after deterministic scope had boxed it in.
Acceptance had to include live validation
The ADR was accepted after live Slack and EC2 validation, along with reconciled phase and task status counts, router evidence, and updated immediate gates. That acceptance criterion is easy to underestimate.
A routing design can pass static review while still failing in the actual system for boring reasons: connector auth, profile mismatch, missing artifact persistence, latency that makes the user experience feel stalled, or a fallback path that works but records nothing. The validation did not prove the architecture perfect. It proved the route could survive the places where architectural diagrams usually stop making eye contact.
This is also where evidence discipline matters. From the signals, we can say the design validated profile, intent, scope, confidence, and approval floor before broker execution. We can say it persisted route source, latency, fallback reason, decision, and profile. We can say the ADR was accepted after live Slack and EC2 validation. We cannot claim incident counts, outage avoidance, or a measurable false-route reduction from the supplied evidence. That restraint is not modesty. It keeps the operating note from becoming folklore before the system has earned folklore.
Typed intent routing is a gate, not a guess
The practical decision is this: put typed intent routing before the broker only if the route decision is subordinate to deterministic scope, strict validation, approval floors, and persisted evidence. Otherwise the model is not helping the execution layer. It is moving uncertainty closer to the thing that can mutate state.
The sharp edge is ownership. Someone has to maintain the route vocabulary, schema, fallback semantics, and acceptance gates as the broker surface changes. If that ownership is vague, the contract will slowly become either too permissive or too stale. Both fail quietly.
I like model-assisted routing here because it gives the system language flexibility without handing language the keys. The model can suggest the door. The router still checks the badge, records the reason, and decides whether the handle turns.