Agent behavior

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

Behavior specs vs. AGENTS.md

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.

Complete examples

For complete specs in both free-form and template styles, browse the examples in the repository:

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

A single BEHAVIOR.md MAY group behaviors that belong to the same agent, product surface, or behavioral domain and should be discovered and reviewed together. Give each behavior a clear heading or label. Use separate specs when behaviors need independent ownership, discovery, or reuse. For example, a spec named loop could provide an agent overview followed by sections such as ## Page-grounded assistance, ## Evidence-backed answers, and ## Bias to action. Each section describes a separate behavior but shares the file's frontmatter.

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:

These dimensions are flexible guidance. They MAY appear in prose or be combined, renamed, reordered, or omitted when trivial or redundant. When these dimensions apply, evidence is the input to a decision, the decision is the conclusion, execution is the visible action, and recovery is what happens when the first path fails.

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.

This template is one way to organize a behavior.

Optional directories

A references/ directory can hold supporting material for reviewers and eval authors:

• rationale documents
• example traces
• background docs
• domain-specific context

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:

Unlike skills, behaviors are not primarily loaded to help a model complete its next task. Clients SHOULD not inject all behavior specs into runtime prompts unless intentionally building a behavior-conditioned agent. 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

Validation has two layers: structural validity, which tools can check, and quality, which requires human or model judgment.

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

Clients SHOULD skip structurally invalid specs and surface a diagnostic rather than load partial or ambiguous content.

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

Authors SHOULD use the recommended dimensions when they add clarity. Structural validation applies only to the directory and frontmatter requirements; body organization remains free-form, including for specs that group multiple behaviors.