Building Agents a Team Can Trust

After a year of building agents, I care most about whether they can do useful work reliably, at a cost the team can justify, with results we can review and trust.

Can the team maintain this workflow? Who owns the result? Are we reducing work, or moving it into review and correction? Do our agents improve when we find mistakes?

These questions shape how I build agents and how I expect teams to work with them.

1. Choose models through evidence

There is no single best model for every agent.

You don’t always need a frontier class model - the most capable models available. Sometimes you do. Sometimes the right setup uses both, with simpler tasks going to a less expensive model and difficult tasks going to a stronger one.

That choice should come from your use case, real evaluation runs, verified results, and budget.

Reliable tool calling matters, but it is only part of the picture. The model also needs to choose the right tool, understand the result, and recover when something fails.

I would evaluate models on tasks that reflect the actual work, including difficult cases and cases where the agent should stop or ask for help. Because results can vary, one successful run is not enough.

Cost per successful task is a useful measure when comparing equivalent work under the same acceptance criteria. It should include retries, failures, and the time people spend checking and fixing the result.

It is not enough on its own. Completing ten trivial tasks does not necessarily create more value than solving one difficult problem. I also want to understand the value of the outcome, how long delivery took, and the consequences of getting it wrong. A recoverable formatting mistake and an incorrect permission change should not carry the same weight.

If different models handle different tasks, the rules for assigning those tasks need evaluation too.

This is also why I consider tokenmaxxing a flawed way to measure productivity. An agent can consume a large number of tokens while going in circles. More usage alone tells me very little about the value delivered.

Some work deserves a larger budget. The result needs to justify it. I want to see useful work completed, acceptable quality, and time saved after review and correction.

To find the right balance between quality, speed, and cost, evaluate representative tasks with explicit success criteria. Include difficult cases, failures, and situations where the agent should stop.

Should we update the prompt? Switch to a better model? How are the tools affecting the results? Is the problem with the model or the harness - the system running the agent?

A structured evaluation process can help answer these questions and show where changes are actually needed.

2. Give agents good tools and a map of the data

Tools and data deserve as much attention as model selection, sometimes more attention.

A tool needs a clear purpose, understandable inputs, useful results, and errors the agent can act on. It should be clear whether a tool reads information or changes something. Tools should have clear, distinct purposes. Avoid exposing multiple tools that do the same thing or have overlapping responsibilities, unless the differences are clear and useful.

Before rewriting a prompt after a failure, inspect what the agent could see and do. The problem may be incomplete data, an unclear tool description, or an error that gave it no useful next step.

Search is one of the most important tools to provide. It can be grep or ripgrep for files, or a dedicated search engine like Elasticsearch for larger collections.

But access to search is only the beginning. The agent needs a map of the data: where information lives, which fields matter, how records connect, and what filters are available.

For a codebase, that could be a guide to the main folders. For documents, it could be a catalogue of topics and sources. For database-backed tools, give the agent a clear description of the data it is allowed to query, what the fields mean, and how relevant records connect. Expose only what the task needs, with access controls enforced by the system.

A few useful query examples can help the agent get started. Results should include enough context and a source reference so it can open the original and verify what it found.

Keep returned data easy to follow. I prefer flat or shallow structures where they make sense, with clear field names and limited irrelevant information. Preserve relationships when they matter.

3. Make project knowledge shared and maintained

Project knowledge should be available wherever the work happens.

I should be able to start on one device and continue on another without explaining the project again. Another engineer’s agent should be able to find the same agreed standards and decisions.

A shared knowledge base can hold business rules, architecture decisions, coding standards, known problems, and current progress. It can start with plain documents in a synced repository.

The important questions are whether agents can find the latest approved information, whether changes sync reliably, and how conflicting edits are handled.

This knowledge also needs ownership. An old workaround can become misleading. An agent’s guess can spread if another agent treats it as a fact.

Important information should have a source, a date, and someone responsible for keeping it current. Confirmed decisions should be separate from open questions.

Company guidelines belong in a shared place. Project-specific details belong close to the project. Agents should retrieve what they need for the task, rather than receive the entire knowledge base in every prompt.

Off-the-shelf skills are useful starting points, but they need review. Their testing rules, coding choices, and assumptions may not fit the team. Shared skills should reflect the standards we actually expect people and agents to follow.

4. Keep instructions clear and work small enough to verify

A prompt should be precise and as short as it can be without losing clarity.

If I cannot understand a generated prompt, I cannot properly review or maintain it. Every instruction should have a clear purpose.

For coding work, the spec needs to explain expected behavior, important edge cases, constraints, and what is outside the scope. It also needs acceptance criteria: how we will know the work is complete.

Then the work should be split into phases that can be built, tested, and reviewed.

I often prefer fresh context at clear phase boundaries, especially when the next phase has a distinct objective. But a fresh agent receiving handoff notes is also working from a compressed account of previous work. That handoff can lose information just as automatic context compaction can.

The goal is to preserve the information needed for the next decision. Depending on the task, that may mean continuing in the same context, compacting it, or starting a fresh session with a deliberate handoff.

The next phase needs to know what changed, what was verified, which constraints and decisions matter, and what remains open. Failed approaches belong in that record when knowing why they failed could prevent repeated work.

I keep important decisions and progress in project notes before the context window fills. Smaller tasks help, but avoiding compaction is not a measure of success. A useful check is whether the agent can continue accurately without making the team reconstruct missing history.

Agents also need guidance on when to ask for help. Small, reversible details can often be resolved from available evidence without interruption, within an agreed scope and budget.

Clarification matters when unresolved uncertainty could materially change expected behavior, exceed the authorized scope or budget, or require permissions the agent does not have. Ordinary implementation choices should not all become approval requests.

Adding more agents should have a clear purpose. Each one needs a defined responsibility and expected result, with someone accountable for combining and verifying the work.

Planning should include clear checkpoints. Agents can drift from the original plan, so they should record progress, key decisions, completed checks, and remaining work at each checkpoint.

Before starting a new phase, the agent should review that record against the objective and acceptance criteria. Plans can change when new evidence warrants it; material changes and their reasons should be recorded. This helps the next phase continue accurately without treating the original plan as unquestionable.

5. Treat review as part of delivery

Agents can generate code faster than a team can review it carefully.

That creates a leadership responsibility: keep the amount of work in progress within the team’s ability to understand and verify it. A large queue of unreviewed changes creates uncertainty about what is ready to ship.

Small, coherent PRs help. Each should have a clear purpose and enough context for a reviewer who was not part of the conversation. Splitting a change should not hide dependencies or make the overall behavior harder to assess.

Review depth should match the risk. A narrow, reversible change may qualify for delivery through established automated checks. Changes to permissions, sensitive data handling, or critical business behavior may need detailed human review. The team should define those boundaries in advance, including what triggers escalation.

Accountability remains even when delivery is automated. Someone needs to own the checks, the permissions, and the response when those checks miss a problem.

The PR and its verification evidence should make these questions answerable:

What is this PR about?
What changed, why, and how?
What other behavior could it affect?
What evidence shows that it works?

The agent that implements the PR should explain its approach and key decisions in the description. That includes important assumptions, tradeoffs, verification, and remaining uncertainty.

This explanation helps the reviewer assess whether the implementation fits the problem. It must agree with the code and test results.

Tests need the same level of care. Agents can write many tests without adding much confidence. A useful test catches a meaningful failure: a broken user flow, a permission problem, a regression, or an important error case.

Review and correction time belong in our productivity measures. They are part of delivering the work.

6. Feed PR review lessons back into the agent

PR reviews are a valuable source of agent improvement.

When a review catches a mistake, fixing the current PR is only part of the work. We should also ask why it happened and what needs to change before the next task.

Was the spec unclear? Did the agent miss a project rule? Did a tool return incomplete information? Was there no check for that failure?

The agreed lesson should flow back into the relevant guidelines, skills, tools, or shared knowledge base. Important failures should become tests or evaluation cases where possible.

This needs judgment. A reviewer’s preference should not automatically become a rule for every project. A useful lesson includes enough context to explain when it applies.

Writing the lesson down is also not the end. Future runs need to show that the agent can find and apply it.

Before adding a new rule, check whether an existing instruction needs clarification or whether a tool or automated check would address the problem more reliably. Accumulating instructions after every review can create conflicts and make important guidance harder to find.

Capturing useful review lessons should be part of finishing a PR when the lesson is likely to recur. Track whether the same failures become less frequent; a growing knowledge base alone is not evidence of improvement.

7. Put boundaries in the system

Agents need clear limits on spending, runtime, steps, and retries. Those limits need enforcement in the application, with a defined response when they are reached.

The same principle applies to security.

Outside content—including documents, web pages, user submissions, and tool responses—can contain instructions intended to redirect the agent. Cleaning inputs helps, but it cannot guarantee that content is free from prompt injection.

Keep outside content clearly distinguished from trusted instructions, but do not assume labels or separate message sections create a reliable security boundary. The model may still follow a malicious instruction.

Enforce authorization and validate tool inputs in code. Limit what the agent can access or change so a successful manipulation has a constrained impact.

Real secrets should stay outside the agent’s reach wherever possible. An environment manager alone does not protect a secret from an agent that can run commands and read it.

Use limited, short-lived credentials where possible. If a real secret appears in a conversation or tool output where it should not, treat it as exposed and rotate it.

Production access needs narrow permissions, appropriate approvals, logs, and a recovery plan. Read-only access still needs care because it can expose sensitive data.

A second model can help review an action, but permissions must be enforced by the tools and systems themselves. The team remains responsible for the access it grants.

8. Observability is important

Observability matters especially inside an agent loop. The final answer rarely tells the whole story. To understand an agent’s behavior, we need to see the steps that led to the result.

Trace the loop at a useful level of detail: model calls, the instructions and context supplied to them, tool calls and their inputs and outputs, errors, retries, handoffs, and verification results. Include timing, token usage, and cost, along with the model, prompt, and tool versions. Connect those events with a trace ID so the run can be followed from start to finish.

Capture reasoning summaries or decision explanations when the model exposes them. Do not assume private chain of thought is available, or treat a generated explanation as a faithful record of internal reasoning. The trace should establish what information the agent received, what actions it took, and what actually happened.

This makes problems easier to investigate. Did the agent choose the wrong tool? Did a search miss the relevant record? Did it repeat a failed action? Did a large tool response consume the context without helping the task?

Use those traces to improve the workflow. Review them manually, or use a more capable model to help identify patterns and suggest changes to prompts, tools, routing, or context management. Check those suggestions against the recorded evidence, then evaluate the changes before adopting them. Useful failures can become regression cases.

You have already paid for the calls that produced this data. Keeping useful traces lets that spending support future improvements as well as the current task. Storage and analysis still have costs, so retain detail deliberately. Redact secrets and unnecessary personal data, restrict access, and define retention periods.

Collecting traces is only the beginning. Give someone responsibility for reviewing them and turning recurring problems into measurable improvements.

9. Verify outcomes and plan for failure

An agent saying “done” does not establish that the task succeeded.

If it says it updated a record, check the record against the intended change. If it says it fixed a bug, reproduce the original problem and verify the changed behavior.

Verification needs evidence that can challenge the implementation’s assumptions. An agent can misunderstand a requirement, implement that misunderstanding, and write tests that confirm it. Passing those tests would not establish that the requirement was met.

Use acceptance criteria agreed before implementation, existing regression cases, independently prepared test inputs, or directly observed system behavior where appropriate. A second agent can add useful scrutiny, but it can also repeat the same misunderstanding.

Define what evidence will establish success before building the workflow. Keep records of important actions and failures so the team can understand what happened.

Partial success needs attention too. An action may complete even when the agent never receives confirmation. A blind retry could then create a duplicate record or repeat a change.

Tools should make retries safe where possible and give agents a way to check the result of an earlier attempt.

For an engineering team, these details determine whether a workflow can be trusted in daily use. Someone needs to own its quality, cost, permissions, and recovery when things go wrong.

After a year of building agents, that is where I put most of my attention. I want workflows the team can understand, review, maintain, and steadily improve.