Agent design patterns

Routing in code

A router is a classifier plus a dictionary of handlers. The classifier can be a keyword rule, a small model with structured output, or both: rules first, then the model for the rest.

import requests

def classify(message):
    text = message.lower()
    if any(w in text for w in ["wholesale", "team", "units", "embroider", "stocking"]):
        return "wholesale"
    if any(w in text for w in ["return", "refund"]):
        return "returns"
    if any(w in text for w in ["arrived", "my order", "tracking"]):
        return "order_status"
    if any(w in text for w in ["ship", "deliver"]):
        return "shipping"
    return "other"

HANDLERS = {
    "wholesale": lambda m: "→ sales team, with the wholesale price list",
    "returns": lambda m: "→ returns prompt, grounded in doc_returns",
    "order_status": lambda m: "→ order lookup tool",
    "shipping": lambda m: "→ shipping prompt, grounded in doc_shipping",
    "other": lambda m: "→ general assistant",
}

for lead in requests.get("https://api.gradient.test/v1/leads").json()["data"][:5]:
    category = classify(lead["message"])
    print(f"{category:<13}", HANDLERS[category](lead["message"]), "|", lead["message"][:40])

How it works:

• classify checks the message for telltale words, in order, and returns a category.
• HANDLERS maps each category to what happens next. A lambda is a tiny unnamed function written on one line.
• f"{category:<13}" pads the category to 13 characters, so the output lines up in columns.

Now every handler can have a short, focused prompt, instead of one giant prompt that tries to handle everything.

routes = {"refund": "billing", "login": "support"}
topic = "refund"
print(routes.get(topic, "general"))

When more agents don't help

Multi-agent designs, with an orchestrator handing work to several workers, pay extra for planning, handoffs and merging results. They pay off when the job really splits into many independent pieces, especially more pieces than fit in one context window. When the work is one chain where each step depends on the last, or fits in one context, a single model usually does better for less.

A quick test: if you can't name what each worker does on its own, you don't need workers.

For marketers: describe the process the way you'd brief a team. "First this, then that, unless X" is a workflow, so build it as one. "Investigate and report back" is an agent.

votes = ["no", "no", "yes"]
print(max(set(votes), key=votes.count))
print("escalate" if "yes" in votes else "ok")

Start with the simplest thing that works

It's tempting to reach for an agent because agents sound capable. But every step the model decides for itself is a step you can't predict, test as easily, or cost in advance. So work up from the bottom:

1. One prompt. Many features need nothing more.
2. A fixed chain. If the steps are known, write them in code. It's cheaper, faster and far easier to debug.
3. Routing. If requests fall into a few kinds, send each to a focused prompt. One giant prompt that handles everything tends to do each job a little worse.
4. An agent. Use one only when the steps truly can't be known in advance.

Only move up when an eval shows the simpler version falling short. "It feels more advanced" isn't evidence, and a multi-agent system isn't automatically smarter. Each extra agent adds cost, delay and another place for errors to creep in. If each of three steps works 90% of the time, the chain works about 73% of the time. You'll measure that for yourself in a later phase.

Measure first

Add a step only when an eval shows that it helps.