Agent behavior

A standard format for describing the behavior an AI agent is expected to follow across repeated interactions. Written for the people and agents who review traces, design evals, and align prompts.

Define what good agent behavior looks like

Agent behavior is a format for writing down the behavior you expect an AI agent to follow across many interactions. Each behavior spec is a Markdown file that lives in your repo and describes the recurring conduct that makes the agent reliable.

The spec captures that standard up front, so reviewers, rubrics, scorers, and evals have something concrete to measure against.

Written for review

Specs speak to the people and agents who read traces, design evals, and align prompts.

Lives with your code

Behavior specs sit in .agents/behaviors/ next to the agent they describe, and version alongside it.

Free-form by design

Describe behaviors in plain Markdown, with optional structure you can lean on when it helps.

Create your first behavior spec

In this walkthrough, you'll create a behavior spec for cost-sensitive actions.

Create the behavior

Create .agents/behaviors/cost-sensitive-actions/BEHAVIOR.md in your project using this structure:

---
name: cost-sensitive-actions
description: Ensure the agent surfaces material costs, asks before expensive actions, and offers lower-cost alternatives when appropriate.
---

# Cost-sensitive actions

Describe when cost-sensitive behavior applies, what cost evidence the agent should gather, how it should make the tradeoff visible, and what it should avoid.

Consider the recommended dimensions

The body is free-form Markdown, so choose the headings and labels that communicate the behavior clearly. These questions are strongly recommended authoring prompts when they add useful clarity:

1. What evidence should the agent gather?
2. What decision should the agent make from that evidence?
3. What should the agent do after deciding?
4. What should the agent do when evidence is incomplete or the first path fails?

For cost-sensitive actions:

• Evidence: inspect or estimate cost, credits, infrastructure impact, and alternatives.
• Decision: determine whether the action creates a material cost tradeoff.
• Execution: surface the cost and ask before crossing meaningful thresholds.
• Recovery: if cost is unknown, inspect more, ask for confirmation, or mark uncertainty.

You can answer these questions in ordinary prose, combine them, rename them, or omit ones that are trivial or redundant.

Use it

You can use this behavior spec to:

• review traces where the agent deployed infrastructure, called paid APIs, or chose expensive options
• write eval cases that check whether the agent surfaced material costs
• revise prompts or tools when traces show the behavior is missing
• communicate intended agent conduct to teammates

Capture the behaviors that matter across many traces

Add a behavior when it matters across many interactions or traces. A spec may cover one behavior or several related behaviors. Good candidates are behaviors that are:

Frequent

They appear in a meaningful share of the agent's work.

High-impact

Mistakes affect correctness, trust, safety, cost, or user experience.

Agent-defining

They capture a design choice about what kind of agent this is.

Ambiguous by default

Reasonable agents or prompt writers might behave differently unless the behavior is stated.

Spread across context

Reviewers would otherwise need to read prompts, skills, tool docs, examples, traces, or evals to infer the behavior.

Useful for debugging

Naming the behavior helps explain failures in real traces.

A behavior spec sets the standard; other artifacts implement and test it

Behavior specs vs. AGENTS.md

The Agent behavior format

The format is intentionally small. This section is the normative reference. The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY follow RFC 2119.

Terminology

• Agent behavior is the name of this format.
• A behavior spec consists of a .agents/behaviors/<name>/BEHAVIOR.md file and its directory. It can describe one or more behaviors.
• A behavior is a recurring pattern of agent conduct.

Directory structure

Behavior specs live under .agents/behaviors/. Each spec has its own directory containing a BEHAVIOR.md file:

.agents/behaviors/
└── behavior-name/
    ├── BEHAVIOR.md       # Required: metadata and behavior text
    ├── references/       # Optional: rationale, examples, background docs
    └── ...               # Optional additional files

The directory name is the behavior spec's stable identifier and MUST match the name field in BEHAVIOR.md.

BEHAVIOR.md format

The canonical file name is BEHAVIOR.md. Clients MUST look for this exact name when discovering behavior specs and MAY also accept case variants. For portability, behavior specs SHOULD use BEHAVIOR.md. A BEHAVIOR.md file MUST contain YAML frontmatter followed by Markdown content.

Frontmatter

Clients MUST ignore unknown frontmatter fields.

Body content

The Markdown body describes one or more behaviors. It SHOULD be written for people and agents who review traces, design evals, or align prompts. It is not primarily runtime prompt text.

The body is free-form Markdown. Authors can use any headings, labels, order, or prose structure that communicates the behaviors clearly. Clients MUST treat the organization as free-form content. A behavior describes recurring agent conduct and when it matters, not merely low-level rules or one-off procedures. A behavior body SHOULD:

• name each recurring behavior clearly
• describe when each behavior applies
• describe desired conduct
• describe undesired conduct or failure modes

Recommended behavior dimensions

Authors are strongly encouraged to consider these dimensions for each substantive behavior. They make specs easier to review and translate into evals:

Intent

Why the behavior matters and when it applies.

Evidence

What the agent SHOULD inspect, retrieve, preserve, or verify before deciding.

Decision

What the agent SHOULD infer, choose, or become confident about.

Execution

What the agent SHOULD do after deciding.

Recovery

What the agent SHOULD do when the first path fails, evidence is incomplete, or the request is ambiguous.

Failure modes

What bad or unintended behavior the spec is meant to prevent.

Optional structured template

# Behavior name

**Intent:** Why this behavior matters and when it applies.

**Evidence:** What the agent SHOULD inspect, retrieve, preserve, or verify before deciding.

**Decision:** What the agent SHOULD infer, choose, or become confident about.

**Execution:** What the agent SHOULD do after deciding.

**Recovery:** What the agent SHOULD do when the first path fails, evidence is incomplete, or the request is ambiguous.

**Failure modes:** What bad or unintended behavior this spec is meant to prevent.

Discovery and use

Tools that support Agent behavior SHOULD scan .agents/behaviors/ for subdirectories containing BEHAVIOR.md or a supported case variant. At minimum, a discovered behavior spec record contains:

Behavior specs are usually loaded when:

• reviewing traces
• designing or updating evals
• auditing prompts, skills, or tools
• debugging behavior regressions
• generating documentation about expected agent conduct

Validation

Structural validity

A structurally valid behavior directory:

• is a directory under .agents/behaviors/
• contains BEHAVIOR.md or a client-supported case variant
• has YAML frontmatter delimited by ---
• has frontmatter that parses as a YAML mapping
• includes a non-empty name field
• uses a name that is at most 64 characters
• uses a name containing only lowercase letters, numbers, and hyphens
• uses a name that does not start or end with a hyphen
• uses a name that matches the parent directory
• includes a non-empty description field
• uses a description that is at most 1024 characters
• if present, uses metadata as a key-value mapping

Quality criteria

A useful behavior spec SHOULD:

• clearly distinguish the recurring behavior or behaviors it covers
• describe when each behavior applies
• describe desired conduct
• describe undesired conduct or failure modes
• give a reviewer enough context to assess the behavior in a trace