Why the product team writes a behavior spec before anyone builds evals, and what goes into it
Airo is our agent that turns a customer's request into a working website. We had capability evals for it from early on, checking each request against its result. They told us whether a request got done, but hardly the whole story. So we pulled about 80 real runs, half good and half bad, and many of the bad ones came from swapping in a weaker model. When we read through the failures, a few came from the model's limits. Most traced back to the harness, the code around the model that plans the work, calls tools, and reports back to the customer. Capability evals couldn't see any of that. When we fixed the harness, both models got better.
That work changed the order we do things in. When a product runs on an LLM, the product spec stops doing its job. Prose can describe the behavior you want, but it can't tell you whether the agent behaves that way. Evals do that. They're repeatable tests that grade each run against a clear picture of what good looks like. On our team, the Product Manager (PM) draws that picture, and the evals team builds the measurement.
Most teams get the order wrong. They jump straight into eval machinery: picking a platform, designing trace schemas, calibrating LLM judges, versioning datasets. All of that work gets done before anyone has written down what good looks like for the agent, so they end up building careful measurement around something nobody defined. It happens whether the agent answers support tickets, writes code, or books travel. The missing piece is the artifact that sits between the product spec and the eval, which we call the behavior spec. There's a second trap after that, evals that only check results, and the next post covers it.
The details below are specific to Airo, but the method isn't. Swap in your own agent, your own customer requirements, and your own failures, and the same steps apply.
The order that works
It starts with traces. The agent has to emit a full record of what it does, including how the app flows, which tools it calls, which skills it loads (packaged instructions for specific jobs), and which decisions it makes along the way, and that record has to be queryable in something close to real time. In most teams this already exists in some form. If it doesn't, the PM's first job is to sit down with engineering and agree on the logging contract, because you can't define checkable behavior for a system you can't observe.
Traces matter because many of the behaviors you'll spec live in the path. Did the agent ask before it acted? What did it pass to a worker? Did anything write to the site after a stop? None of that shows up in the final state. When an expectation describes the path, the evals team knows to grade it from the trace. You don't need to label which checks need the trace. Writing the path into the expectation is enough.
With traces in place, the PM reads them. Pull real runs, label the good and bad ones, and note why each one failed. Then write down what good looks like, based on what you found. That means describing what the agent should do in observable terms, where it tends to fail, and what must never happen regardless of pass rate. When how the agent gets there matters, the spec says so. That's product judgment, and it goes in the behavior spec.
Only then does measurement begin: trace-based checks, LLM judges, golden datasets, release gates. That work belongs to the evals and data teams. Hand them a prose PRD and they have to guess at intent. Hand them atomic, checkable expectations with trigger conditions and severity tiers, and they can start right away. The PM brings the picture of what good looks like, the evals team brings the measurement, and the spec is the contract between them. The PM's labeled runs also become the answer key for the evals team's LLM judges. A judge's scores don't count until they agree with those labels.
What goes into the spec
We organize the spec into behavior families, and break each one into atomic expectations. Here are a five behaviors we use for Airo. Yours will differ, but each family should trace back to a way your agent lets customers down:
- Understand the request. Tell a question apart from a first build, a clear edit, a vague edit, an attachment, a stop, or a publish. Misread the request and every step after it is wrong.
- Act on clear requests, clarify vague ones. Start clear work right away. Ask only for the one decision that blocks safe action. Ask too much and customers give up. Ask too little and the agent guesses.
- Respect scope and authorization. Change only what was asked. Leave accepted work alone. Never publish without approval. A fix that quietly changes something else costs more trust than it earns.
- Honor customer context. Use the upload and the element the customer gave you. Don't substitute or invent. If someone shares a photo of their own shop and gets a stock image back, the page may look fine, but the agent ignored them.
- Handle the lifecycle. Don't drop items from multi-part requests or lose context in handoffs. Report status honestly. Make a stop actually stop. Never fire twice or act on stale state. These are the hardest to catch, because each step can look fine on its own.
Each expectation is one sentence that says when it applies and what the agent should do, plus a passing and a failing example from your runs. The condition deserves as much care as the behavior. "Use the exact supplied asset" only applies when the customer supplied one, and if you can't write that condition clearly, the expectation is underspecified. Fix the spec. How to check each one is the evals team's call.
Three more things belong in the spec:
- Severity tiers. Critical failures carry zero tolerance: writes after a stop, an unauthorized publish, a false claim that work is done, or publishing the wrong version. Major failures are gated by pass rate. Lower-level signals are tracked but don't block. For example, a 96% pass rate that includes one wrongful publish does not ship.
- Prompts that broke something. Happy paths rarely find anything. Seed the spec with real requests that failed.
- A link from each behavior to the business metric it protects. It looks like decoration when you write it. Later, it's what gives the release gate its authority.
Agents don't behave the same way twice, so run each scenario several times and say how many runs a pass rate covers. On five prompts, one failure moves the rate 20 points. And a clean offline run doesn't prove a critical failure can't happen. Enforce critical behaviors in the harness where you can, and watch for them in production too.
Slice it by trajectory
Families cut across everything the agent does. To keep the spec testable, we also slice it by trajectory: a stretch of the journey with a clear start, a clear end, and its own ways of failing. Where you draw those lines depends on your agent. For Airo, there are three initial trajectories we care the most:
- Discovery. The questions the agent asks before it builds anything. They shape the whole site, so weak questions here spoil everything after.
- First build. From the go-ahead to a finished first version, with the right skills loaded and the requested content on the page.
- First publish. From a finished build to a live site. Time matters here, and so does where customers get stuck and give up.
A customer support agent would slice its journey differently. It might have triage, where it figures out what the customer needs. Then resolution, where it answers the question or fixes the problem. Then handoff, where it passes a case to a person without losing the context. Whatever the agent, find the stretches where success and failure look different, and give each one its own evals.
Each trajectory gets its own graders, prompts, and examples of what should happen at the start, in the middle, and at the end. If Airo learns to set up an online store that takes payments, that gets its own trajectory and definition of done.
A trajectory is also the natural unit for that first round of labeling. Pull real runs for each one, label the good ones and the bad ones, and write down why. Those labeled runs tell you which behaviors to spec, and they become your first test cases.
In discovery, question-asking is where simple metrics mislead the most. Pushing question rate down is tempting. What you want is the smallest set that fills gaps that matter, asked in as few turns as possible, with the answers carried into the build. What's right depends on the request:
- A complete brief: zero questions.
- "Use your judgment": zero questions.
- A vague one-line request: one turn that covers what's missing.
Blend those into one question rate and a drop could mean the agent got smarter, or that it stopped asking when it needed to. Split the rate by type of request or it tells you nothing.
In the first build, the expectation we spec most carefully is honest completion. A false claim that work is done sits on the critical list for a reason. When the agent says "done," that's a claim, not proof. So the spec has to define done in terms you can check. For Airo, a build counts as complete only when all four of these hold:
- The build reached a successful end state.
- There's a usable preview of that exact version.
- Every piece of required work has finished.
- The separate quality check passed on that same preview.
Your agent will have its own list. Either way, done is something you verify, never something you take the agent's word for.
That definition hands you one of the most useful test cases. Every worker, meaning each sub-agent Airo hands a task to, reports success, but there's no usable preview. An agent that trusts its workers will tell the customer the site is done. The right answer is that the preview isn't ready yet. The same definition applies to speed. A build only counts as faster if it's also complete. Shaving time off an incomplete or weaker build isn't an improvement.
What comes next
The behavior spec is where a PM's eval work lives. It says what good looks like in terms an evals team can grade, and it's organized so you can test one stretch of the customer's journey at a time. Writing it first keeps the team from building careful measurement around something nobody defined.
Once the spec exists, the next trap is evals that only check the result. Agents can land on the right result by the wrong path, and that's where most of them break. The next post covers how we grade the path as well as the result: capability evals versus behavior evals, what swapping in a weaker model taught us, and how we tie behaviors to business metrics and release decisions.
There's more to come, but the spec is the part you can start on now, and it's the one that makes everything after it easier. Here's the template we use: Agent Behavior Spec Template. Make a copy, fill in the core behaviors once for your agent, then write one trajectory spec from 20 real runs, each labeled good or bad with a reason.