Designing Interfaces for AI Agents

Most of the work in an AI product isn't the model. The model is an API call. The work is everything around it: what the agent is allowed to look at, how long it takes, what it does when it fails, and how a person decides whether to trust the result.

These are the principles I settled on while building Pecauva, a research workspace where finance analysts upload reports and disclosures, ask questions across them, and turn the answers into files and reviewed drafts. They aren't specific to finance. They apply to any interface where an agent does work that someone else has to stand behind.

1. Every answer points back to a source

A fluent answer with no source is a liability. The reader has to verify it from scratch, which is slower than not having the answer at all.

In Pecauva every answer is saved with its citations: the document, the chunk, and a short snippet. The interface shows them next to the answer, not behind a click. The rule that shaped the whole system was simple: if an answer can't point to a document, it isn't an answer.

Design for the source first. If you can't show where something came from, that's a signal to change the system, not to hide the gap.

2. "I don't know" is a valid answer

Models are built to produce something. The interface has to make room for nothing.

In the research matrix, each question is a column, each document is a row, and each cell is answered from that document alone. If the document doesn't say, the cell says N/A. It never borrows from another file to fill the gap.

A grid with honest gaps is more useful than a full one. An analyst can work with "this report doesn't mention it." They can't work with a confident number they have to go and check.

3. Scope what the agent can see, and show the scope

Agents get worse when they can see everything. In Pecauva, retrieval never leaves the active project, and when a question spans several documents the results are spread across files, at most two chunks from each, so one long report can't drown out the rest.

The design point is that the scope is visible. The user knows which project they're in and which documents the agent is drawing on. When the answer surprises them, the first question, "what was it looking at?", already has an answer on screen.

4. Make long work visible and resumable

Agent work is slow. Uploading and indexing a document, running a set of questions across twenty files, or generating a spreadsheet can take minutes, not milliseconds. A spinner doesn't cover that.

Every upload in Pecauva goes through the same four stages, convert, chunk, embed, and index, and its status is visible in the project the whole way. The slow work runs as durable steps, so a failure resumes where it stopped instead of starting over.

For the interface, that means progress can be shown honestly, by stage, and a person can leave and come back. Design long-running agent work like a queue someone will check on, not like a request they're waiting for.

5. Fail small, and say what failed

A run of a hundred steps shouldn't fail because one step did. In the matrix, cells run in batches of five, each with two retries. A cell that still fails is recorded as failed, and the run keeps going. The person sees ninety-nine answers and one clearly marked failure, which they can retry.

The same applies to generated files. Asking a model to write a spreadsheet directly is unreliable, so the agent writes Python instead and runs it in a sandbox. If the first run errors, the error goes back to the model and it patches the script. If the sandbox is down, a CSV falls back to a text answer, and a PDF or XLSX fails with a specific error instead of producing a broken file.

A broken file that looks fine is the worst outcome. A clear error is a much better one.

6. The agent advises, a person decides

For anything that leaves the building, keep a person in the decision, and design the handoff so it's easy for them.

Drafts in Pecauva go through review before they can be exported. An AI pass checks the draft against the organization's policies and raises up to three findings. Then a person with the compliance role makes the call. Every resubmission starts a new review cycle, so the history of what was flagged and what changed stays readable.

The limit of three findings is a design decision, not a technical one. A reviewer who gets thirty warnings stops reading them. Three focused ones get read.

The common thread

All six come down to one idea: design for trust, not for fluency. Agents are already fluent. What they lack is the ability to show their work, admit what they don't know, and hand off cleanly to the person who's accountable.

That's interface work, and it's most of the job. If you're building something like this, the Pecauva case study goes into the architecture, and here's how to work with me.