Skip to content

DIRECT Principles

Design principles for Agent Experience (AX) - building software interfaces that autonomous AI agents can reliably consume.

DIRECT is to Agent Experience what SOLID is to Object-Oriented Design: a foundational set of principles that guide the creation of agent-friendly APIs, CLIs, SDKs, and documentation.

The Six Principles

Principle Why Agents Need It
Deterministic Agents trust the system to behave the same way each time, making safe recovery from errors natural
Introspectable Agents explore capabilities and understand data structures without requiring external docs or humans
Recoverable Agents can diagnose what went wrong and take corrective action without human intervention
Explicit Agents operate within clear boundaries and constraints so they act with confidence
Consistent Agents build mental models once and apply them everywhere, scaling their effectiveness
Testable Agents can try actions safely before committing, learning what works without causing harm

Why DIRECT?

Traditional developer experience (DX) optimizes for:

"How fast can a human ship?"

Agent Experience (AX) optimizes for:

"How reliably can an agent figure it out?"

These are not the same problem.

Humans can:

  • Read prose documentation and infer meaning
  • Handle ambiguous error messages
  • Debug issues through trial and error
  • Tolerate inconsistencies across endpoints

Agents cannot do any of these reliably. They need:

  • Machine-readable specifications
  • Structured, actionable errors
  • Deterministic behavior
  • Consistent patterns to generalize from

DIRECT codifies what agents need to succeed.

Compliance Levels

Progressive adoption through defined levels:

Level Name Requirements
AX-L1 Structured Valid spec, explicit types, operation IDs
AX-L2 Deterministic Strict schemas, explicit required fields
AX-L3 Agent-Ready Full DIRECT compliance with AX extensions

See Compliance Levels for detailed requirements.

Applying DIRECT

To APIs

Use AX Spec Spectral rules to lint OpenAPI specifications:

vacuum lint --ruleset ax-spec/rules/ax-openapi.json your-api.yaml

To CLIs

DIRECT CLI Pattern
Deterministic Same flags always produce same output format
Introspectable --help with detailed examples, --list-commands
Recoverable Semantic exit codes, --format json for errors
Explicit All options via flags, no interactive prompts
Consistent Uniform flag naming (--format, --output)
Testable --dry-run mode, stdin/stdout piping

To SDKs

Use layered SDK architecture:

  1. Foundation Layer - Generated from spec (e.g., ogen)
  2. Machine-accurate, 1:1 mapping to API
  3. No abstraction, no magic

  4. Agents use this layer directly

  5. Convenience Layer - Human-friendly wrappers

  6. Simplified method signatures
  7. Default values and helpers
  8. Humans use this layer

To Documentation

Structure documentation for machine consumption:

  • Endpoint summaries in structured format
  • Parameter tables with types and constraints
  • Examples in JSON (not just prose)
  • Capability indexing for discovery

Token Efficiency

Agents pay for context. DIRECT-compliant interfaces should optimize for token efficiency:

Format Relative Tokens Use Case
Raw text 1.0x Human reading
JSON 0.6x Machine parsing
JSON-compact 0.5x Bandwidth-constrained
TOON 0.4x LLM consumption

See structured-changelog for TOON (Token-Oriented Object Notation) implementation.

Implementation

Background

Comparison to SOLID

SOLID (OOP) DIRECT (AX)
Single Responsibility Deterministic
Open/Closed Introspectable
Liskov Substitution Recoverable
Interface Segregation Explicit
Dependency Inversion Consistent + Testable

Both provide foundational principles for their domains. SOLID guides class design; DIRECT guides interface design for agent consumption.