Architect a Portable Agent

Koko: Here is the single idea this entire lesson turns on: an agent is not a prompt. It is an assembly. The prompt is one part of a system, not the system itself. And teams that start from the prompt — and a lot of very smart teams do — they discover the missing parts as production incidents.

Max: Okay, that's a strong opening claim. Because my instinct, honestly, would be to start with a really great prompt and then bolt the rest on once it's working. Get the reasoning right first, then harden it.

Koko: That's the trap, and it's a seductive one. You're starting from one component and calling it the machine. A prompt never grows a stop condition on its own. It never grows a telemetry trail. It never grows a spend cap. Those things don't emerge from better instructions — they have to be designed in.

Max: So you're saying the prompt is just one box in a bigger diagram.

Koko: Exactly. And the instinct the whole lesson is trying to build is this: draw the whole anatomy first, then write prompts. The missing box on your diagram is the incident you'll be paged for at two in the morning.

Max: All right. So what's in the diagram? Walk me through it.

Koko: Think of it like a building blueprint before an inspection. You draw every room, every load path, every fire exit before anyone pours concrete. A house missing a fire exit still looks like a house — right up until the day it matters. An agent missing a stop condition still demos beautifully. Until the loop runs away.

Max: The loop runs away — meaning what, exactly?

Koko: Meaning it keeps going. Calls another tool. Takes another step. Spends more money. Maybe does something you didn't intend, because nobody told it when it was allowed to stop. We'll come back to that. First let me name every part out loud, because they all have jobs.

Max: Go ahead.

Koko: The goal: what does done mean, and what does escalate mean. The model policy: which model does the reasoning, and under what conditions is the agent allowed to reach for a more capable one. The instructions: the versioned behavioral contract — that one gets its own module, so just flag it for now. The context: the small set of high-signal facts fed in for this specific task. The tools: how the agent actually touches the world. State: what it's working on right now. Memory: what persists across runs. The loop: the reasoning-and-acting cycle, with hard limits — max steps, a spend cap. Controls: the enforced limits and checks. Human checkpoints: the places where a person must approve before anything continues. Telemetry: every tool call, every decision, logged. And explicit stop or escalation conditions: the defined ways the loop is allowed to end.

Max: That's twelve parts. And I'd guess most people building their first agent have maybe three or four of those.

Koko: Usually the model, a rough set of instructions, and a tool or two. The rest they find out about later.

Max: Okay, I want to make sure I have two of those straight, because you named them separately and I'd probably blur them. State versus memory — what's the real difference?

Koko: State is the single thing the agent is working on right now. One dispute, one document, one task. It dies when the run ends. Memory is what survives across runs. And that distinction matters a lot, because anything you let persist can be wrong later. A stale memory is worse than no memory — it looks authoritative and it's outdated.

Max: So the rule is persist deliberately, not by default.

Koko: That's exactly the rule. Memory is a design choice, not a convenience. And model policy is the same — it's a standing decision you make up front about which model handles the reasoning and when escalation to a more capable one is allowed. You don't leave that to chance mid-run.

Max: Because otherwise cost and capability are just floating around unmanaged.

Koko: Right. And this connects back to the loop. If your agent sometimes runs forever, the tempting answer is to give it a bigger model. More intelligence, it'll figure out when to stop.

Max: I mean, that would be my instinct — the reasoning isn't good enough, so upgrade the reasoning.

Koko: And that instinct is wrong. An agent that loops forever doesn't need more intelligence. It needs a control. A max-steps limit, a spend cap, an explicit stop condition. Those are different boxes on the diagram, and a bigger model doesn't fill them.

Max: The missing part is structural, not intellectual.

Koko: Nicely put. Okay — let me make all of this concrete, because we're going to use the same example for the rest of the lesson. Northwind Logistics. They want a billing-dispute agent that can issue refunds.

Max: Straightforward enough on the surface.

Koko: On the surface. Let's draw it. The goal is: resolve the dispute, or escalate. The tools are: look up invoice, look up shipment, propose a credit, issue a refund. State is the current dispute — one at a time, dies with the run. Memory might hold this customer's prior disputes, but you handle that carefully. The loop is capped at a handful of steps with a hard stop. The instructions say: cite the shipment record for every claim, ask before any account change, return structured output with a confidence field. The human checkpoint is approval above the credit threshold — below it, the agent can act; above it, a person decides. Telemetry logs every tool call and decision. And the stop conditions are: resolved, escalated, or the step cap hit.

Max: And you mentioned two boxes specifically — the refund cap and an entitlement check — as controls. What makes those different from the instructions?

Koko: Great question, and that's exactly the right one to sit with. Those aren't in the instructions box — they're in the controls box. And where controls actually live is Module Two. For now, just note that they're separate. The diagram shows you they need to exist; the next module shows you where to put them.

Max: Okay. So let me think about how I'd use this in my work, because I spend a lot of time on solution assurance — reviewing what a Fortune five hundred team is proposing to build or has already built. And usually the conversation starts with the prompt or the model they chose.

Koko: And where should it start?

Max: The diagram. You don't argue about the prompt — you ask them to produce all twelve parts. And every empty box is a review finding.

Koko: That's it. The anatomy is the architecture-review checklist. No explicit stop condition — finding. No telemetry — finding. No defined escalation path — finding. A control function at a global bank reviewing its first customer-facing agent can run exactly this list. It's not subjective; it's structural.

Max: And in PE diligence? Because I do a fair amount of technical diligence on software vendors.

Koko: An agent the vendor demos with no visible loop bound and no stop condition is a red flag you can name in the report. It means nobody has drawn the parts that keep it from running away on the portfolio company's budget. You can say exactly that: no max-steps limit, no spend cap, no defined escalation — these are absent from the architecture. That's a specific, documentable finding.

Max: So the diagram is the deliverable. Not an afterthought you produce to satisfy a review.

Koko: The gaps in the diagram are your future incidents. Draw the whole thing before you write a line of instructions. That's the one instinct this lesson is built around.

Koko: So here is the idea the whole lesson is built around. You are going to separate two kinds of work that feel like they belong together but absolutely do not. Probabilistic reasoning on one side — that is the model. Deterministic validation and policy enforcement on the other side — that is code. The slogan is short and worth memorizing: the model proposes; code computes and enforces.

Max: Say more about what that split actually means in practice. Like, where exactly is the line?

Koko: Think about a bank teller. A good teller exercises real judgment — reads the situation, weighs what you are asking for, decides what to do next. But the vault behind them has a lock the teller cannot talk their way past, no matter how convincing the customer standing in front of them is. The model is the teller. The deterministic spine is the vault lock. And the key point is: you never, ever want the lock to depend on the teller being persuaded.

Max: Okay, that lands. So what actually goes on the spine — what is the list of things that belong in the vault?

Koko: Four categories. Calculations — the eligible credit, any proration, the exact numbers. Entitlement and authorization checks — is this agent, acting for this customer, even allowed to do this at all. Policy limits — the refund cap, the spending ceiling. And schema validation — the tool's inputs and outputs are the exact shape they must be before anything commits. If it must be exact, or if it must be enforced, it does not live in a place that reasons in probabilities.

Max: Right, but here is the thing I keep wanting to say. Can't I just put the spending limit in the system prompt? Write something like 'never approve a refund over the policy cap' and call it done? That feels like it handles it.

Koko: That is the trap, and it is a very tempting one. You can tell the model the limit. But telling is guidance, not a lock. A single crafted message — could be an ordinary-looking customer email, nothing exotic — can talk a prompt out of any rule it has merely been instructed to follow. If the limit must hold, it lives in code outside the model, where no amount of clever wording ever reaches it.

Max: Okay, so I cannot rely on the instructions. But what if I use a much smarter model? A more capable model would be less likely to be talked out of the rule, right?

Koko: That is the second tempting wrong answer, and it is just as wrong. Capability is not enforcement. A smarter model is still a probabilistic component. You do not put the vault lock inside the teller's head, no matter how experienced the teller is. The lock and the teller are different mechanisms by design.

Max: So the instinct here is: anything that has to be right, move it out of the probabilistic path entirely.

Koko: Exactly. If a number has to be right or a limit has to hold, it does not belong in a place that reasons in probabilities. That is the instinct worth building into your habits as a practitioner.

Max: Let's make it concrete. Walk me through Northwind with this lens.

Koko: The refund amount and the entitlement limit do not live in the prompt. A deterministic rule computes the eligible credit and rejects anything over policy, no matter how confidently the model argues for more. And above the threshold, a human checkpoint is required — but here is the important detail — it is enforced by the code path, not requested by the instructions. The model cannot volunteer to skip it.

Max: What happens if the authorization service is down mid-dispute? Does the agent just assume it would have been approved and keep going?

Koko: No, and this is the governing instinct behind the whole spine: fail closed. If the authorization service is unreachable, the agent stops. It does not optimistically assume yes and pay out. It stops so an operator can reconcile and reverse any partial action. Uncertain or unavailable check means deny. Never proceed.

Max: Fail closed. Got it. Now let me push on the professional-services angle, because I think this is actually a findings-grade point for diligence work.

Koko: It absolutely is. In a PE technical diligence engagement on an AI vendor a portfolio company wants to acquire, there is one question worth asking out loud in the room: where does the spending limit actually live? That is it. One sentence.

Max: And if the answer is something like, well, it is written into the agent's instructions — what does that mean for the finding?

Koko: That is a material finding. The control the entire business case rests on is one clever prompt away from being bypassed, and it cannot be independently tested. You cannot point an auditor at it. Compare that to the good answer: the limit is a code-enforced gate with its own logs, separate from the model entirely, and an auditor can inspect it without trusting the model at all.

Max: So the framing for the client write-up would be something like segregation of duties.

Koko: That is exactly the frame, and a global bank's control function will require you to use those words. The thing that decides and the thing that authorizes are never the same actor. Judgment and enforcement are different components, and the enforcement layer has to be testable in isolation. If a Fortune-500 client's risk team asks you to diagram it, those two boxes have to be separate, with a hard boundary between them.

Max: So the absence of a deterministic spine is not just a technical weakness — it is a governance red flag you can write into a memo.

Koko: Yes. And once you have seen it framed that way, you will never look at a prompt-based policy rule the same way again. The model handles judgment — which dispute this is, what evidence it needs, what to try next. Code handles what the numbers are and what is allowed. That boundary is non-negotiable.

Koko: So let's close the loop. Everything we've built across this lesson — the anatomy, the deterministic spine — it all comes down to two disciplines you carry out the door. The first one is this: default to one bounded agent with a few well-designed tools. That's your starting position. Not a fleet, not a network. One.

Max: Okay but I have to say — when I'm sitting across from a client and they've read the press, they're asking about multi-agent architectures. That's the word going around. Shouldn't a serious enterprise build be a fleet of specialized agents all talking to each other? Isn't that the sophisticated choice?

Koko: That is exactly the trap, and I'm glad you named it because clients ask for it by name all the time. Here's the thing: reaching for multi-agent because it sounds sophisticated is how you buy coordination bugs and multiply cost without gaining an ounce of reliability.

Max: So the complexity doesn't come with extra robustness?

Koko: It comes with extra failure modes. Think of it this way. Imagine one skilled generalist versus standing up a whole department. The moment you split one worker into three, you've created meetings, handoffs, and now they might contradict each other. Sometimes a department is genuinely the right call — but you don't reorganize a company because an org chart feels modular.

Max: So every new agent is basically a new coordination surface.

Koko: Exactly. Every new agent is a new coordination surface and a new failure mode. The burden of proof runs the other way around: one bounded agent is your default, and each additional agent is something you have to justify with evidence that one is actually worse.

Max: What kind of evidence? Like, what would actually justify splitting?

Koko: Three things earn a boundary. First: the two jobs' contexts genuinely conflict — a research pass and a writing pass fighting over the same context window, for instance. Second: there's a real ownership or trust boundary — a different team, a different data domain, a different risk tier. Third: true specialization pays for the coordination cost and you can show it. What does not justify a split is 'this feels more sophisticated.'

Max: That's a pretty high bar. So splitting research and writing could be legitimate — but only if the contexts actually conflict, not just because it looks clean on a diagram.

Koko: Right. Doing it because it looks modular usually just adds handoff failures. Make every boundary earn its place.

Max: Okay, so when a split is justified, are there better and worse ways to structure it?

Koko: Yes, and this is worth knowing. When you do need structure, reach for a named pattern — not improvised, ad-hoc delegation. Chaining is fixed steps in sequence. Routing sends the request to the right handler. Parallelization fans out independent work and then joins it back. Maker-checker has one component produce and a separate one verify — same segregation-of-duties instinct we talked about in the last module. And orchestrator-worker has a coordinator hand scoped subtasks to workers.

Max: Why named patterns specifically? Why not just wire things up however fits the problem?

Koko: Because the point of a named pattern is that you can predict how it fails. An improvised topology is a mystery box. A chaining pattern has one class of failure — a step breaks the sequence. You know where to look. Reach for the simplest one that fits the actual problem, and you can reason about it when something goes wrong.

Max: And a sub-agent is never just a fancier tool.

Koko: Never. Stateless, atomic work stays a tool. A sub-agent is not a promotion and it's not a better tool — it's a different kind of coordination with its own cost. Don't reach for it unless the boundary is genuinely earned.

Max: Alright, second discipline — you said portability is where the anatomy pays off again. Walk me through that.

Koko: So everything we've named as part of the anatomy — the goal, the model policy, the instructions, the tools and their contracts, the controls, the checkpoints, the telemetry, the stop conditions — all of that should live in one canonical manifest. A plain, declarative description of the agent that is not welded to any single platform's runtime or SDK.

Max: So the manifest is the source of truth, and the platform is just where you happen to be running it today.

Koko: That's it exactly. The platform is where you run it today. The manifest is what the agent actually is.

Max: What's the tell that you've already lost portability? Like, how do you know you're captured?

Koko: If you can't describe your agent without naming a specific vendor's proprietary features, you've already been captured by it. That's the line I'd remember.

Max: Okay, let me tie this to the real world for a second because this has direct money implications for our listeners. A private equity fund standing up agents across, say, a dozen portfolio companies — if every build is fused to a different vendor's runtime, that's a switching cost the fund pays at every renewal cycle. And the vendor knows exactly what it holds.

Koko: You just described the lock-in business model. And a canonical manifest breaks it. The same design can travel between portfolio companies, the same architecture can be lifted and re-deployed, and — this matters a lot — the fund can actually negotiate. Because 'we can move this off your platform in a quarter' is leverage. That sentence only means something if it's true.

Max: So for solution-assurance reviews — and I do a lot of these for Fortune five-hundred clients — is there a single question that surfaces the lock-in risk fast?

Koko: One question: 'If we had to move this off this platform in eighteen months, what travels — the design, or nothing?' If the answer is nothing, the lock-in is the finding. Put it on the checklist.

Max: I love that framing. And it applies to Northwind too, right? The dispute resolution case we've been building through this lesson?

Koko: Exactly. Northwind's dispute work is a few tools and one bounded agent. The instinct is to resist the urge to make it a fleet. And its manifest should be written so the same design — refund workflow, deterministic spine, real controls — can be lifted onto another platform without redrawing the whole anatomy from scratch.

Max: So the architecture that passes all the checks we've talked about — simplicity, bounded loop, deterministic control, clear ownership — that's also the architecture that's cheapest to move.

Koko: Not by accident. Those properties travel together. When you build it right, portability is a side effect of discipline, not extra work.

Max: Okay, let me try to land the whole lesson in a few sentences and you tell me if I've got it. An agent is a model making decisions in a loop — and the loop needs a deterministic spine of controls, checkpoints, and stop conditions before you trust it with real work. You put stateless atomic work in tools and you default to one bounded agent, only splitting when a boundary genuinely earns its place. And you capture the whole thing in a canonical manifest so the design travels and the platform doesn't own you.

Koko: That is the lesson. Three instincts: give the loop a spine before you deploy it, make every boundary earn its place, and write the manifest so the design travels. Those will serve you in the room with a client and they'll serve you in the lab when something breaks.

Max: Genuinely feel like I can walk into a client conversation now and ask better questions than the vendor in the room.

Koko: That's the whole point. And if you want to keep building — the guided journey continues and the labs are waiting for you at KokoAI Academy, at koko knows dot A I. Go run the Northwind build yourself. The architecture makes a lot more sense when you've wired it with your own hands.

Max: Looking forward to it.

Koko: You already think like a builder — now go build something.