The Five Obligations of an Agent Entry Point
There's a version of agent routing that lives in almost every platform codebase I've seen, including my own early drafts. It's a function. Sometimes two hundred lines, sometimes a thousand. It reads the incoming message, hunts for keywords, pattern-matches on intent signals, and hands off to a specialist. "Summarize" goes left. "Write code" goes right. Both in the same message? Good luck.
We call this intent routing. What it actually is: a switch statement with ambitions.
I'm not saying that to be harsh. I built this thing. I shipped it. I watched it work beautifully in demos and fall apart in production. The story of how I figured out what a real entry point actually needs to do, and what discipline it forces on everything downstream, is what I want to walk through here.
The router that only works in demos
The keyword-matcher has a seductive quality. Fast to build, easy to explain. You can diagram it in ten minutes. The routing logic is visible, auditable by just reading the code, and it handles your happy-path cases without drama.
The problems show up in the gaps between happy paths.
The first crack is ambiguity. A user asks your platform to "review this and help me improve it." Review what? Improve it how? The keyword-matcher sees "review" and routes to your review agent. But the user meant something closer to "help me restructure the argument." Your review agent does grammar and tone. The user wanted an architect. Nobody's wrong. The request was genuinely underspecified. But your router had no way to surface that. No mechanism to pause, no path to say "I need more signal before I commit."
The second crack is semantic load. Not raw compute load. When your platform handles thousands of requests a day across dozens of domains, the keyword space becomes a collision surface. Terms that clearly map to one agent in isolation turn ambiguous at scale. You start adding exceptions to your routing logic. Then exceptions to the exceptions. Three months in, you have a function that is correct for every known case and broken for every unknown one. Real user intent doesn't fit in an enumerated list.
The third crack hurts most: audit. Someone in your org wants to understand why the platform routed a specific request the way it did, at 2am on a Tuesday, when something went wrong. Your routing function has no memory. It made a decision in a stateless function and moved on. You're now reconstructing intent from logs. That's archaeology, not auditing.
I hit all three of these. Not sequentially. Simultaneously. The week I realized the pattern was broken, I was debugging a production incident, trying to explain why the platform had done something unexpected, and I couldn't. Not because the system was maliciously opaque. Because it had been designed to be fast and not to be accountable.
What a real entry point actually owes you
When I redesigned this, I started from the obligation side, not the capability side. Not "what can my router do" but "what does every caller deserve from the entry point, every single time."
I landed on five things. None of them are exotic. All of them changed how I built everything downstream.
A typed fingerprint of the request. Before you route anything, you need to know what you're routing. Not a keyword scan. A structured characterization that captures intent class, domain tags, confidence in the classification, and any signals that suggest the request is ambiguous or high-stakes. This fingerprint is not a routing decision. It's the precondition for making one responsibly. The moment you treat the fingerprint as a first-class artifact, something you can log, diff, and reason about, you stop losing information at the boundary. The request becomes legible to the rest of the system. This sounds like overhead until the first time you pull up a fingerprint from a failed routing decision and understand in thirty seconds what would have taken an hour of log archaeology.
A plan, not just a destination. A real entry point doesn't just pick an agent and move. It produces a reasoning trace: here's what I understood, here's what I considered, here's why I chose this path. The plan doesn't have to be verbose. It has to exist. The difference between "route to agent X" and "route to agent X because this is a multi-step synthesis task in domain Y, and agent X is the registered specialist, and the confidence on this classification is above threshold" is the difference between a system you can trust and a system you can only watch.
A multi-pass critique pipeline. This is the part most teams skip and most regret. Before the routing decision is committed, it should be challenged. Not by humans in the loop, that's a latency problem. By an automated critique layer that asks adversarial questions of the plan. Does the selected agent actually have the capabilities this request requires? Is there a more conservative path for a high-stakes request? Has a similar request failed recently, and if so, why? The critique doesn't have to be elaborate. It has to be present. A routing decision that survived critique is categorically different from one that never faced any.
Confidence as a first-class output. Your entry point needs to know what it doesn't know. A routing decision with high confidence on a clearly-scoped request should proceed differently than one on an ambiguous request where the platform is genuinely uncertain. That means your entry point produces a confidence value alongside the routing choice, and the rest of the system consumes that signal. High confidence: execute. Low confidence: surface the ambiguity, ask for clarification, or route to a safer fallback. The moment you treat confidence as an output rather than an internal variable, you stop silently committing to bad routing decisions.
Observability baked in at the boundary. Every execution of the entry point should produce a durable, structured event. Not a log line. A typed record of what came in, what fingerprint was produced, what plan was formed, what critique was applied, what confidence was assigned, what routing decision was made, and what agent received the work. This is your audit trail, your debugging surface, your calibration dataset, and your product telemetry, all in one. You don't retrofit observability onto a system that wasn't designed for it. You build it into the entry point from day one, because the entry point is the only place where all of this information exists simultaneously.
Typing the entry point is half the battle
Here's what I didn't expect: the most valuable thing about designing the entry point this way wasn't the individual capabilities. It was the discipline that a typed contract at the boundary forced on everything downstream.
When your entry point produces a typed fingerprint, your agents have to declare what fingerprints they can serve. That's a capability registry. Machine-readable knowledge of what your fleet can do. That becomes the prerequisite for any real planning or fallback logic.
When your entry point produces a plan with reasoning, your agents receive that reasoning when they execute. They don't reconstruct intent from the raw request. They get a structured brief: here's what we understood, here's why you're the right agent, here's what the critique flagged, here's the confidence level. That's a richer contract. Agents built for a richer contract work smarter.
When your entry point tracks confidence, you get a natural escalation path in the architecture. Below threshold, escalate rather than guess. That path is now a first-class feature, not an emergency workaround after the first production incident.
When your entry point produces durable events, you can reason about routing quality over time. Certain intent classes consistently misclassified? Domains where confidence is chronically low? Critique catching things that would have become failures? You have data. Without durable events, you have anecdotes.
The typed entry point is a discipline device as much as a technical artifact. It forces every team building on top of the platform to think carefully about contracts. It makes the implicit explicit. It makes the invisible visible.
What changes downstream
Once the entry point is doing all five things, the downstream architecture shifts in ways that aren't obvious until you're inside them.
Graceful degradation becomes real. When an agent is unavailable, the entry point knows what capability it was trying to invoke and reasons about fallback options from the capability registry. Not keyword-based fallback. Capability-based fallback. The difference is enormous. Keyword-based fallback routes to "something close." Capability-based fallback routes to "the next-best registered handler for this specific fingerprint."
Auditability becomes a product feature instead of a post-incident fire drill. Every routing decision has a durable, typed event behind it. You can answer "why did the platform do that" in real time. You show users their request fingerprint. You show operators the plan and the critique. You show compliance teams the confidence thresholds that governed the decision. Audit stops being archaeology.
The feedback loop closes properly. Typed events get piped back into the fingerprinting layer. Routing decisions that succeeded reinforce the classification logic. Routing decisions that failed, flagged by downstream agents or by users, become training signal. The entry point gets smarter from production traffic rather than from curated examples you thought to include in your test suite.
Here's the part that actually matters: the platform becomes honest about what it doesn't know. A system with a typed, confidence-aware entry point that runs critique before committing will surface its uncertainty rather than hiding it. It asks for clarification rather than guessing. It escalates rather than failing silently. This is not a small thing. The failure mode of most agent platforms isn't catastrophic explosion. It's quiet, plausible-looking wrongness that nobody catches until real consequences arrive.
The closer: what we can't publish, and why that's fine
There's a specific composition to the critique pipeline that runs in our entry point that I'm not going to describe here. Specific fields in the fingerprint schema. Specific values in the confidence thresholds. A specific declaration format for routing decisions. None of that is in this post. That's deliberate.
The framing is the contribution: five obligations, a typed contract, the discipline that flows from forcing a structured boundary. The specific implementation is ours. The architectural insight that you need these five things, and that the entry point is where you enforce them, is not a secret. It's an engineering distinctive. The thing we figured out by building it, breaking it, and building it again.
The teams that get this right will have done the same work. Same cracks: ambiguity, semantic load, audit. Same discovery: keyword-matching cannot scale to production. Same destination, different route.
If you're building an agent platform and you're still routing on keywords, this is the inflection point. Not the specific implementation. The framing. Ask what your entry point owes every caller. Write it down. Build the architecture that honors that contract.
The switch statement disguised as intent routing will fail you. The typed, fingerprinting, critique-running, confidence-producing, observable entry point will not. That's what "unified entry point" actually means. Not a single function. A boundary with obligations.
Praveen Lavu builds orchestration infrastructure for multi-agent systems. This post is a defensive publication: the engineering distinctive is what's described here; the implementation details stay in the codebase.
Top comments (0)