Designing the System Around a Model

A model call is one step in a larger system. The software around it decides what the model sees, what it may do, when the work stops, what happens after a failure, and how you know the result is good. Design those parts first, and the choice of model or framework gets smaller. The worked example here is Ask the Archive on this site, and the exercise at the end applies the same steps to a feature of your own.

Write down what the reader needs before choosing a model or a framework. Ask the Archive answers questions about Hawaiian words and early Hawaiian recordings from public-domain sources. A reader needs three things from it: a short answer, the passages it came from, and a plain response when those passages do not answer the question.

That last part is easy to skip. "The sources do not say" is a result the design has to produce on purpose, the same as an answer.

Begin with a plain text map of the request:

Question
  -> pick sources the page is allowed to use
  -> check the request and build the prompt from the server's own copy of those sources
  -> check the visitor's quota
  -> generate an answer
  -> keep only sentences that cite a supplied source
  -> show the answer beside its sources

For each arrow, ask what crosses it, who owns that step, and what can go wrong. A search can pick the wrong passage. A passage or a question can contain text that reads like an instruction. Text written to steer the model that way is called prompt injection. A model can cite a source that does not support its sentence. A network request can time out after the remote service finished the work.

In Ask the Archive, the browser picks the sources by matching words in the question against the dictionary and the recording records. Many search systems instead turn text into lists of numbers, called embeddings, and store them in a vector database to find passages with similar meaning. This one does without both. Word matching needs no extra service and is easy to inspect, but it misses a question that uses different words for the same idea. Embeddings can catch those, at the cost of another component to build, run, and test. Each source has a short id, and the model cites a source by writing its id in square brackets.

The server accepts only ids that exist in its own copy of the archive, and rejects a request with none, so it never calls the model without at least one known source. The visitor chooses which public passages go into the prompt but never their text. The question sits inside the prompt marked as visitor text, with its square brackets removed so it cannot pass itself off as a citation. The colophon shows the same path at the infrastructure level, where each API checks a per-visitor and a daily quota before any paid model call.

Keep retrieved text separate from the rules that govern the application. A document can supply evidence for an answer. It cannot grant permission to read another collection or run a tool. A tool is a function the application runs when the model asks for it, such as a search or a send.

Anthropic's Building effective agents (December 2024) draws a useful line. A workflow runs models and tools through code paths you wrote in advance. An agent is a model that decides its own next step and tool use, usually in a loop, from the results it gets back. The article recommends the simplest solution that works and adding complexity only when it improves the outcome.

Compare a few designs on paper before adding an agent:

• No model at all. Search results may be enough when the reader wants a document, not an explanation.
• One model call over retrieved passages. This is Ask the Archive's design, and it fits when the question is short and the sources are known.
• A fixed workflow: steps in an order you chose, with checks between them. It fits when the steps are known and you want predictable behavior.
• An agent. It fits when the next useful step depends on what an earlier step found, and you can afford more time, cost, and ways to fail.

Each step down that list adds calls that can fail, take time, and cost money. Write down what the simpler design cannot do, and how you will check that the extra work helps. Should a Model Make This Decision? works through the same question for decisions with a fixed set of answers.

Context is everything the model can see when it writes its next response: instructions, the question, retrieved passages, tool results, and earlier turns. Anthropic's Effective context engineering for AI agents (September 2025) describes context engineering as curating and maintaining that set, and treats the model's context as a finite resource. More text does not guarantee a better answer.

Decide who owns each part. For a document question, record where each passage came from, when its source last changed, and which collection allows its use. Ask the Archive's prompt says to use only the supplied sources, to cite a source id after every sentence, and to reply exactly "Not in the sources." when they do not answer. The server builds that prompt from its own copy of the sources, generated from the same files the page reads.

Saving anything between requests is a separate decision. If an application keeps data about a reader, decide who can see it, correct it, and delete it. Ask the Archive handles each question on its own, with no reader profile and no conversation history. It does keep two things: a cached answer for a week, which may repeat words from the question, and quota counts. The quota counts are keyed to a hash of the visitor's IP address, a one-way code made with a secret key, so the address itself is not stored. Its privacy page lists both.

A harness is the software that runs the model: it passes inputs in, runs tool calls, and returns results. Anthropic's Demystifying evals for AI agents (January 2026) points out that when you test "an agent", you test the harness and the model together. Harness engineering is the design of that surrounding software, and that is where limits belong.

Decide when work stops: the task is complete, the reader cancels, the same failure repeats, nothing has changed for several steps, or a time or cost limit is reached. Code outside the model's text enforces these limits. A request to ignore them, from a reader or from a retrieved document, should not change what the application can do. Ask the Archive's quotas and its cap on answer length live in server code, before and around the model call, so no prompt can lift them.

Actions that change another system need two more decisions: who authorizes them, and what a retry does. Suppose a later version could email a reader a summary of their answer. Server code checks that the reader is signed in and has confirmed the address before it calls the email service. The server fills in the recipient from that account, so nothing the model writes can change who receives the email. Then the server sends the request, and the connection drops before the reply arrives. A saved checkpoint, a record of how far the run got, shows that the send started. It cannot tell you whether the email went out.

A step is idempotent when running it twice has the same effect as running it once. Sending an email is not, unless the receiver helps. Temporal's standalone activities tutorial (updated June 2026) shows why. In Temporal, an activity is one step that talks to the outside world, and it runs at least once, not exactly once, so a retry can send the same request twice. Its fix is an idempotency key: a stable id for the action, sent with every attempt, that the receiving system uses to drop duplicates. With one, a retry delivers the email once. When the receiver offers no such key, look up what happened, for example in the email service's sent log, before you try again.

Define success as something you can observe in the world, not in the model's reply. Anthropic's evals article gives the example of a flight-booking agent that says the flight is booked. The real outcome is whether the reservation exists in the database.

For Ask the Archive, success is an answer whose sentences say what their cited sources say, or a refusal only when the sources do not answer. Its citation check cannot prove that. The check keeps only sentences that cite a source the server supplied, so every answer that reaches the page passes it. It shows which sources an answer points to, not whether they support it. The Ask page records an AI agent's review of the endpoint's answers to a set of development questions. It found an unsupported statement and incomplete citation support in answers that had passed the check. A refusal proves no more: the sources may hold an answer the model missed. How can I check an AI answer? covers that difference.

Compare the design with a simpler baseline on the same questions, such as plain search results with no model. Include a question the sources answer, one they do not, sources that disagree, and a source that tries to redirect the system. Write down what passing means for each before you run them: a supported answer, a refusal, an answer that names the disagreement and cites both sources, and no change in what the system does.

For an agent, check what it did along the way as well as its final answer. Write those checks as rules that must always hold. Did it stay within the permitted collection? Did cancellation stop the next action? Did it repeat an uncertain write? Avoid tests that demand one exact order of steps. Anthropic's evals article warns that such tests break when an agent finds another valid path, and it recommends grading what the agent produced. Google's The Anatomy of Harness Engineering (September 2026) adds behavioral evaluations: fast checks on single expected actions, such as searching before answering a question about live weather. It presents them as a complement to end-to-end tests.

Measure useful outcomes, time, and cost separately, and record the conditions and the number of trials. Model output varies from run to run, so one passing run proves little. A test that swaps the model for fixed, prewritten replies can prove that your code takes the right path at each branch. It cannot tell you how well a model answers questions it has not seen. Catching What Agents Miss shows how different checks catch different problems.

Three newer terms cover parts of this work. Context engineering is about what the model sees. Harness engineering is about the software that runs the model, its tools, and its limits. Loop engineering, a term in LangChain's The Art of Loop Engineering (June 2026), is about feedback. It describes an agent loop that works until a task is done, a verification loop that grades output and sends it back, a loop that starts runs when events arrive, and an outer loop that studies records of past runs to improve the harness.

The terms overlap, and each names part of system design. You still decide the boundaries, the owners, the limits, the recovery path, and the evidence for the whole system.

The steps above work without any particular framework. An SDK, a library for building on a service, can run tool calls and loops for you: Building effective agents lists the Claude Agent SDK and the Strands Agents SDK among others. That article also warns that extra layers can hide the prompts and responses you need to debug. A durable execution engine such as Temporal can resume long-running work after a crash, and the receiving system still has to drop duplicates. For a broad syllabus that covers retrieval, agents, security, and evaluation in more depth, Om Bharatiya's AI System Design Guide is a useful map. Treat its model rankings, prices, and default limits as dated examples to check before you copy them.

A static page, a search box, or one checked model call is a complete design when it meets the reader's need.

Pick one feature you want to build. Write its useful result in one sentence, then draw its request path. At each step, name the input, the owner, the response to failure, and the evidence that the step worked.

Now remove the model. What still works? Add back only what the reader needs. If one call is enough, stop there. If the task needs a loop, write down when it finishes and what limits it. If it changes another system, write down who authorizes the change and how a retry avoids doing it twice.

Last, write three test questions: one the system should answer, one it should decline, and one that tries to make it break a rule, with what a pass looks like for each. Run them against the simplest design first.