Agent Behavior: A Markdown Format for Specifying How Agents Should Work
Standards for defining and evaluating agent behavior
At a glance
- What is it?
- Braintrust and Basis have published an open standard for writing down expected agent conduct as BEHAVIOR.md files under .agents/behaviors/, plus a TypeScript CLI that validates their structure. It is a specification and a validator, not an evaluation harness.
- Who is it for?
- Adopt it if you are building long-horizon agents and your team already reviews traces or writes rubrics, because a BEHAVIOR.md file gives those activities one written source of truth. Skip it if what you actually need is a scorer or a regression suite: the repository ships a structural validator, and the examples only demonstrate a judging convention over recorded trajectories.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 49 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: a long agent trajectory is not one number
The README opens with a claim worth taking seriously. A modern agent can work for hours and make hundreds of decisions in a single trajectory, and you cannot reduce that behavior to one outcome metric. That is the gap this project targets. If your agent produces a slide deck, a passing final artifact tells you nothing about whether it rendered the deck before returning it, or whether it inspected a stale render from before the last edit. Outcome scoring hides that. Process supervision requires you to write down what the process should look like, and that written artifact has to exist before any reviewer, rubric, scorer, or eval measures it. The intended audience is teams building long-horizon agents who already look at traces and want a single written source of truth to align prompts, evals, and human review against. It is not aimed at someone who just wants a pass or fail number on a chatbot response.
A spec is a directory with a Markdown file and optional references
The unit of the format is a directory under .agents/behaviors/, named for the behavior, containing a required BEHAVIOR.md and an optional references/ folder for rationale, examples, and background docs. The file itself is YAML frontmatter plus a free-form Markdown body. In the README's example the frontmatter carries only name and description, and the body is organized under six labels: Intent, Evidence, Decision, Execution, Recovery, and Failure modes. Those labels are optional, and the README says plain Markdown works too. The example spec, validate-rendered-deck, is a good illustration of why the Evidence label exists: it states that a render made before the latest edit is not evidence about the deck now being returned. That is a constraint about what counts as proof, written down once, that a reviewer or an automated judge can then apply consistently. The repository also ships a second worked example, primary-source-tax-research, under examples/.agents/behaviors/, for a different domain.
Discovery, validation, and what the CLI actually checks
Specs live next to the agent they describe, in .agents/behaviors/, which is the discovery model the specification page documents. The CLI lives in packages/agentbehavior, and the README describes its job narrowly: validate structure. From a clone of the repository the documented sequence is pnpm install, then pnpm build, then pnpm exec agentbehavior validate . where the dot is the path being validated. Note what that command is not. It does not run your agent, replay a trajectory, or score anything. It checks that the spec directory and its files conform to the format. The evaluation side is demonstrated only through the runnable examples, which the README describes as showing a true/false/na judging convention over recorded trajectories. That is a convention, not a bundled judge. If you want behavior specs to gate a deployment, you are supplying the runner and the judge yourself, or wiring in a tool that has implemented the client guide at docs/client-implementation/adding-behaviors-support.mdx.
Where the format is thin, and where it is the wrong tool
The six labels are prose, not schema, and the README is explicit that they are optional. That flexibility is deliberate, but it means two teams can write specs that are structurally valid and semantically incomparable, because nothing in the format forces a Recovery section or a Failure modes section to exist. Structural validation will pass a BEHAVIOR.md whose body says almost nothing. The second limitation is scope: this is a definition standard. Nothing in the supplied material indicates the repository ships a scorer, a trace ingester, or a CI action. If your actual pain is flaky evals, adopting a spec format does not fix it. The third is the authoring cost. Writing a spec that a reviewer can apply without arguing about it takes real effort, and the project's answer is a portable skill at .agents/skills/writing-agent-behavior/SKILL.md that helps agents author and calibrate specs. That is a reasonable answer, but it means the quality of your specs depends on how well that skill is used, not on the validator.
The nearest alternative is a prompt or a rubric, and the difference is location
Most teams doing this today keep the expectation in one of two places: inside the system prompt, or inside an evaluation rubric written in whatever the eval framework expects. Both work, and both have a failure mode the spec format is designed around. Prompt text drifts as the prompt grows and gets edited for other reasons, so the expectation about re-rendering after a fix ends up buried in a paragraph about tone. Rubric text is bound to one scorer, so a second reviewer or a second eval tool has to re-derive the same standard. A BEHAVIOR.md file is neither: it sits in the repository at a fixed path, in Markdown, and the README's framing is that it defines the standard before any reviewer, rubric, scorer, or eval measures it. The trade is that you now maintain a third artifact and keep it in sync with the prompt and the rubric. If your agent has one behavior worth specifying, the prompt is cheaper. The format starts paying for itself when the same conduct has to be checked by more than one consumer.
Licence, maintenance, and what upgrading costs you
The project is Apache-2.0, which permits commercial use and modification and includes a patent grant; the repository ships the full text in LICENSE. That is a permissive choice, and it matters here because the specification is meant to be implemented by other tools, which the client implementation guide explicitly invites. The README notes that the project began as a collaboration between Basis and Braintrust. No releases were retrieved, so there is no versioned artifact to pin and no changelog to read for migration notes. Practically, that means your upgrade path is the main branch of the repository, and the format's stability is asserted by the specification page rather than by a release tag. If you vendor the CLI, pin a commit hash and re-read the specification page before moving it. If you only write BEHAVIOR.md files, your exposure is smaller, because the files are Markdown and remain readable even if the tooling changes. This is a description of the licence terms as published, not legal advice.
Who should start with a single spec this week
The lowest-risk first step is to take one behavior you already check by hand, write it as .agents/behaviors/<name>/BEHAVIOR.md with name and description in the frontmatter, and run the documented validate command against the repository root. If the validator accepts a spec that you know is too vague to review against, you have learned the boundary of the tool in one sitting. After that, the decision is about consumers: if only you read the spec, a paragraph in your notes is equivalent and cheaper. If a reviewer, a second engineer, and an eval all need the same standard, the fixed path and the Markdown body earn their place. Verify two things before you commit: that the specification page's validation rules match what pnpm exec agentbehavior validate . reports on your directory, and that the true/false/na convention in examples/ is one your judging setup can actually produce. If neither holds, the format is still readable documentation, but it is not yet a gate.
Editorial conclusion
Adopt it if you are building long-horizon agents and your team already reviews traces or writes rubrics, because a BEHAVIOR.md file gives those activities one written source of truth. Skip it if what you actually need is a scorer or a regression suite: the repository ships a structural validator, and the examples only demonstrate a judging convention over recorded trajectories. Before committing, clone the repository, run the documented pnpm install, pnpm build, and pnpm exec agentbehavior validate . sequence against your own spec directory, and read the specification page to confirm which frontmatter fields the validator actually enforces.
Community notes