Essay

Code-First Agentic Architecture

Put repeatable work in code. Spend model tokens on reasoning.

By ·4 min read

In this essay

Code-first agentic architecture makes agents simpler, safer, and cheaper by separating work we can program from work that requires reasoning. Here’s how — and why — to do it.

How

1. 🔧 Identify the mechanical work

Look at what your agent needs to do. Retrieving data, parsing, searching, calculating, counting, sorting, filtering, transforming, validating, traversing graphs, and applying defined rules are candidates for conventional code.

If you can specify an operation’s behavior and reliably test its results, implement it in code rather than asking the model to perform it.

2. ⌨️ Make it a command-line tool

Give the tool explicit inputs, predictable behavior, structured output, and useful errors. Make sure it works without an agent.

Keep the interface independent of any particular model or harness. A person, a script, and an agent should all be able to use the same executable.

Test the tool independently.

3. 🧾 Return evidence, not just conclusions

Return structured results with stable identifiers, provenance, relevant context, and known limitations. Distinguish complete results from partial or uncertain ones.

For expensive operations, save the results and provide commands to search, filter, and retrieve relevant portions. Don’t make the agent repeat the work or consume an entire report when it needs only a few records.

Give the agent a way to trace evidence back to its origin and verify what the results establish.

4. 🧠 Teach the agent how to use it

Write a small skill explaining when to invoke the tool, how to interpret its results, and how to reason, decide, or investigate further.

Teach the agent to frame a question, retrieve relevant evidence, evaluate its meaning, and determine the next step.

Define how to handle failures, incomplete results, and uncertainty. Give the agent stopping conditions so it knows when to act, report its findings, or request further information.

Keep deterministic procedures in the tool, not the skill.

5. ✅ Test the complete workflow

Test the command-line tools independently, then evaluate the agent using them.

Give the agent real tasks. Does the tool produce correct evidence? Does the agent select relevant operations, interpret the results correctly, and make decisions supported by that evidence?

Compare the workflow with alternatives. Measure task quality, reliability, execution time, and model cost.

Keep the approach when it produces better results or reduces the total cost of producing them.

Why

Cost

Conventional code can perform repeatable operations without consuming model tokens. Saved results can be reused, and focused retrieval keeps unnecessary data out of the model’s context.

Spend model tokens on decisions, not bookkeeping.

Simplicity

Understanding why a model does what it does is hard. Deterministic code makes its rules explicit.

Every responsibility assigned to conventional software reduces the model’s work and the interactions we must reason about. The reduction in complexity can be much greater than the reduction in work.

The less we ask the model to do, the easier the whole system becomes to understand, test, and debug.

Security

The model doesn’t need unrestricted access to do useful work. Give it tools with narrowly defined operations and enforce permissions in the software that executes them.

A tool can validate inputs, reject unauthorized operations, and limit what gets read or changed. Those restrictions must also apply to any other capabilities the agent can access.

Don’t rely on the model to obey a security boundary. Enforce it.

Correctness

Conventional software can implement explicit rules and be tested against expected results. We can verify calculations, validate inputs, check edge cases, and detect failures without asking a model whether its own work is correct.

The agent can still make mistakes when interpreting the evidence. But we have reduced the amount of work that depends on model reasoning.

Test what can be tested. Reserve reasoning for what requires reasoning.

Reproducibility

Given the same inputs, configuration, and tool version, deterministic operations can produce the same results.

Record those inputs and preserve the evidence. We can repeat an analysis, compare results, and investigate differences without relying on a model to reconstruct its previous work.

The agent’s conclusions may vary, but the evidence supporting them need not.


Let code do the repeatable work. Spend model tokens on reasoning.

See also