Specification v0.1

This document is the normative entry point for the Agent Behavior Specification. It defines document format, required and optional fields, and conformance rules. Conceptual definitions and rationale live in the Core Model; this document is the formal reference for implementers.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as in RFC 2119.

1. Document format

An ABS document is valid YAML. (JSON is also valid, being a syntactic subset of YAML.) The recommended file extension is .abs.yaml; plain .yaml is also acceptable.

2. Top-level structure

session: <string>            # REQUIRED — human-readable session name
description: <string>        # OPTIONAL
abs_version: "0.1"           # OPTIONAL in v0.1, RECOMMENDED, will be REQUIRED in v0.2
behaviors:                   # REQUIRED — ordered list of Behavior objects
  - actor: <string>
    action: <string>
    target: <string>         # OPTIONAL
    content: <any>           # OPTIONAL
    capture: <map>           # OPTIONAL
    with: <map>              # OPTIONAL
    evaluations: <list>      # OPTIONAL — step-level, checks this Behavior only
evaluations: <list>           # OPTIONAL — session-level (chain), checks the whole trace

A document with no evaluations anywhere (step-level or session-level) is purely descriptive. Adding evaluations at either level makes the same document executable as a test.

Note on informal shorthand

Early discussion of ABS used a compact notation where a bare list of Behaviors follows session: directly:

session: Order status
- actor: user
  action: says
  content: "Where is my order?"

This is not valid YAML — a block mapping cannot be directly followed by a block sequence at the same indentation level. All documents in this project use the explicit behaviors: form, which is the only form v0.1 defines as conformant.

3. Field definitions

4. target semantics (normative)

The meaning of target is determined by the Action category of the same Behavior. An implementation MUST interpret target as follows:

5. Ordering

Behaviors within a Session's list MUST be interpreted as an ordered sequence. Implementations MUST NOT reorder Behaviors for evaluation purposes.

6. Variable resolution

Any content or with value MAY contain a {{variable}} reference. A conforming implementation MUST resolve {{variable}} in this order of precedence:

1. Captured value — the nearest prior capture: of that name earlier in the same Session.
2. Runtime binding — a value provided at execution time via dataset row, CLI flag, or environment variable.
3. If no resolution source exists, it is an error and MUST be reported as such.

7. Alternate and branching flows

v0.1 does not model branching within a single Session. Alternate paths MUST be represented as separate Sessions.

8. Conformance

An implementation is ABS v0.1 conformant if it:

1. Parses a document per §2, resolving target per §4;
2. Resolves variables per §6;
3. If it claims step-level evaluation support, implements at minimum exact_match and contains evaluators;
4. If it claims session-level evaluation support, implements at minimum sequence and never.

9. Versioning

Version numbers

ABS uses simple integer versions: 0.1, 0.2, …, 1.0. No patch numbers. Every version is a breaking-change boundary until 1.0.

Declaring the version

Documents SHOULD declare abs_version: "0.1". This becomes REQUIRED in v0.2.

Schema versioning

The normative JSON Schema for each version is published at:

https://abs-lang.org/schema/v0.1/abs.schema.json
https://abs-lang.org/schema/v0.2/abs.schema.json

Implementation support

An implementation MAY support multiple versions simultaneously. The document declares its contract, and the tool adapts — the same strategy used by OpenAPI and AsyncAPI.

10. Non-goals

See the Manifesto, "What ABS is not."