Agent Definition Language

Declarative specification language for defining autonomous agent behavior, scoring, and composition

Format YAML + JSON SchemaExtension .agent.yamlVersion 1.16.0Status DraftUpdated 2026-05-10

Overview

The Agent Definition Language (ADL) is a YAML-based specification for defining atomic AI agents in the UluOps validation framework. ADL provides a single schema for both analysis (scoring) and action (task execution) agents.

text

ADL (Agent Definition)
       │
       │ wrapped by
       ▼
CDL (Command Definition)
       │
       │ orchestrated by
       ▼
WDL (Workflow Definition)
       │
       │ staged by
       ▼
PDL (Pipeline Definition)

Key Characteristics

Aspect	Description
Format	YAML with JSON Schema validation
Extension	`.agent.yaml`
Scope	Atomic agents — one agent, one concern
Agent Types	Validator, Executor, Analyst, Generator, Explorer, Forecaster
Composition	Agents compose into Commands (CDL), then Workflows (WDL), then Pipelines (PDL)

Design Principles

💡

Tip

Declarative Over Imperative — ADL describes what an agent evaluates or accomplishes, not how it executes. The runtime (SDK) interprets the definition.

💡

Tip

Objective Scoring (Validators) — 100-point scoring framework with explicit criteria. Total points always sum to 100, categories have defined weights, and thresholds map scores to decisions deterministically.

💡

Tip

Task-Based Execution (Executors) — Discrete tasks with clear inputs, outputs, and completion criteria. Tasks have explicit dependencies and outputs are captured as artifacts.

💡

Tip

Single Responsibility — Each agent focuses on one domain concern. Composition happens at the Command/Workflow level, not within agents.

💡

Tip

Backward Compatibility — Full backward compatibility with earlier ADL versions. Existing definitions work with minimal changes.

Agent Types

ADL defines six agent types, each with distinct capabilities and constraints:

Analyze and score targets with actionable findings

Output

Score + Findings + Decision

Decision Vocabulary

PASS / WARN / FAIL

Use Cases

Code quality validation
Security auditing
Documentation completeness
API contract compliance

Requires

interfacescoringdecisions

Perform tasks that modify state or produce artifacts

Output

Artifacts + Changes + Status

Decision Vocabulary

COMPLETE / PARTIAL / FAILED

Use Cases

Issue auto-fixing
Code generation
Migration scripts
Refactoring operations

Requires

interfacetaskscompletion

Investigate topics and produce analytical reports

Output

Analysis Report + Recommendations

Decision Vocabulary

Custom (per agent)

Use Cases

Ecosystem pattern analysis
Strategic assessment
Data science review
Risk assessment

Requires

interfaceprocess

Produce artifacts from structured inputs

Output

Generated Artifacts + Status

Decision Vocabulary

Custom (per agent)

Use Cases

Agent prompt scaffolding
Configuration generation
Code scaffolding
Schema generation

Requires

interfacetasks

Discover, map, and report on codebases and systems

Output

Exploration Report

Decision Vocabulary

None (narrative output)

Use Cases

Codebase mapping
Dependency tracing
Architecture discovery
Knowledge extraction

Requires

interfacemission

Model future states and causal consequences

Output

Predictions + Causal Chains + Timelines

Decision Vocabulary

Custom (e.g., SOUND/PERVERSE)

Use Cases

Perverse outcome detection
Unintended consequence analysis
Temporal decay prediction
Cascade depth analysis

Requires

interfacemissionprocess

Schema Structure

Common Schema

All agents share this core structure:

yaml

agent:
  interface:           # Required: Identity and classification
    name: string
    version: string
    displayName: string
    description: string
    agentType: validator | executor | analyst | generator | explorer | forecaster
    domain: string
    subdomain: string?
    domain_profile: string?
    risk_level: low | standard | high | critical
    tools: Tool[]?
    tags: string[]?
    triggers: Triggers?
    dependencies: Dependencies?
    epistemic_nature: EpistemicNature?  # Multi-axis epistemic classification

  defaults:            # Optional: Runtime defaults
    model: haiku | sonnet | opus
    timeout: number
    max_tokens: number
    temperature: number

  context:             # Optional: Execution context
    working_directory: string?
    environment: Record<string, string>?
    timeout_behavior: fail | warn | continue
    shell: bash | sh | zsh | powershell

  mission:             # Optional: Agent identity and purpose
    opener: string?
    stakes: string?
    outcome_framing: string?
    role_boundaries: string[]?
    explicit_prohibitions: string[]?

  knowledge_base:      # Optional: Embedded domain expertise
    sections: KnowledgeSection[]?
    global_references: string[]?

  process:             # Optional: Execution phases
    phases: Phase[]

  output:              # Optional: Output formatting
    format: markdown | json | html | structured
    sections: Section[]?

  edge_cases:          # Optional: Special handling
    EdgeCase[]

  tone:                # Optional: Communication style
    attributes: string[]
    guidelines: string[]

  handoff:             # Optional: Data flow contracts (v1.10.0)
    upstream_context:
      accepts: string[]
      description: string
    downstream_artifacts:
      produces: string[]
      description: string

  cognitive_lens:      # Optional: Epistemic framework (v1.10.0)
    thinker: string            # Required: kebab-case thinker ID
    epistemic_depth:
      primary: first-order | second-order | third-order
      capable: string[]
      target_description: string
    core_axioms: CoreAxiom[]
    failure_signatures: FailureSignature[]

  composition:         # Optional: Agent pairing metadata (v1.10.0)
    pairs_well_with: CompositionPairing[]
    covers_blind_spots_of: BlindSpotCoverage[]
    has_blind_spots_covered_by: BlindSpotCoverage[]

Validator Schema

Scoring agents with criteria, deductions, and pass/fail decisions:

yaml

agent:
  interface:
    agentType: validator

  scoring:             # Required
    maxScore: 100
    categories: Category[]
    constraints: Constraints?

  decisions:           # Required
    vocabulary:
      positive: string   # e.g., "PASS"
      negative: string   # e.g., "FAIL"
      conditional: string?
    thresholds: Threshold[]

  auto_fail:           # Optional
    enabled: boolean
    conditions: AutoFailCondition[]

  deductions:          # Optional
    severity_scale: SeverityLevel[]

Executor Schema

Task-execution agents with steps, completion criteria, and rollback:

yaml

agent:
  interface:
    agentType: executor

  tasks:               # Required
    inputs: Input[]
    operations: Task[]
    outputs: Output[]

  completion:          # Required
    vocabulary:
      complete: string
      partial: string
      failed: string
    criteria:
      - condition: string
        decision: complete | partial | failed

  rollback:            # Optional
    enabled: boolean
    strategy: git_restore | git_stash | backup_restore
    preserve_logs: boolean

Analyst Schema

Investigation agents with analytical processes and recommendations:

yaml

agent:
  interface:
    agentType: analyst

  process:             # Required
    phases: Phase[]

  scoring:             # Optional (assessment-style)
    maxScore: 100
    categories: Category[]

  decisions:           # Optional
    vocabulary:
      positive: string
      negative: string
    thresholds: Threshold[]

  # Forbidden: tasks, completion, rollback

Generator Schema

Artifact-generation agents with structured output production:

yaml

agent:
  interface:
    agentType: generator

  tasks:               # Required
    inputs: Input[]
    operations: Task[]
    outputs: Output[]

  completion:          # Optional (quality self-check)
    vocabulary:
      complete: string
      partial: string
      failed: string

  # Forbidden: scoring, deductions, auto_fail

Explorer Schema

Discovery agents with exploration missions and narrative output:

yaml

agent:
  interface:
    agentType: explorer

  mission:             # Required
    opener: string
    stakes: string?
    outcome_framing: string?

  knowledge_base:      # Optional: Tool guidance
    sections:
      - id: string
        title: string
        content: string

  process:             # Optional
    phases: Phase[]

  # Forbidden: scoring, decisions, deductions,
  #            auto_fail, tasks, completion, rollback

Forecaster Schema

Prediction agents with causal modeling and timeline projections:

yaml

agent:
  interface:
    agentType: forecaster

  mission:             # Required
    opener: string
    stakes: string?

  process:             # Required
    phases: Phase[]

  forecast:            # Optional (v1.9.0)
    actor_type: rational | naive | adversarial | systemic
    time_horizon: near-term | medium-term | long-term
    propagation_mechanism: string
    prediction_format: probability-weighted | spectrum | timeline

  scoring:             # Optional (assessment-style)
    maxScore: 100
    categories: Category[]

  # Forbidden: tasks, completion, rollback

Field Reference

Interface Block

Identifies the agent. Every agent definition starts with this block.

Field	Type	Required	Description
`name`	`string`	Yes	Kebab-case identifier. Pattern: ^[a-z][a-z0-9](-[a-z0-9]+)$
`version`	`string`	Yes	Semantic version. Pattern: ^\d+\.\d+\.\d+$
`displayName`	`string`	Yes	Human-readable name for UI display (3-50 chars)
`description`	`string`	Yes	20-500 chars: When to use + what it does + what it blocks/enables
`agentType`	`enum`	Yes	validator, executor, analyst, generator, explorer, or forecaster
`domain`	`enum`	Yes	Primary domain (software, security, legal, cognitive-lens, etc.)
`subdomain`	`string`	No	Optional refinement of domain
`domain_profile`	`string`	No	Domain profile reference for domain-specific rendering (v1.6.0)
`risk_level`	`enum`	No	Risk classification: low, standard, high, critical (default: standard)
`tools`	`Tool[]`	No	Runtime capabilities: Read, Grep, Glob, Bash, Web, API, MCP
`tags`	`string[]`	No	Searchable tags for discovery
`triggers`	`object`	No	Activation configuration (file_patterns, project_markers)
`dependencies`	`object`	No	Agent dependency declarations (requires, recommends, conflicts)
`epistemic_nature`	`EpistemicNature`	No	Multi-axis epistemic classification (v1.13.0). Object with optional axes: verifiability (mechanically_checkable, expert_judgment, not_checkable), determinism (deterministic, stochastic, environment_dependent), claim_type (factual, normative, observational)

Epistemic Nature Block

Multi-axis classification of the agent's epistemic characteristics. Three independent optional axes: verifiability (can a third party confirm the finding?), determinism (same input → same output?), and claim type (what kind of assertion?). See the full specification for classification guidelines and examples.

Defaults Block

Runtime defaults for model selection, timeout, and execution budget.

Field	Type	Required	Description
`model`	`enum/string`	No	LLM model: haiku, sonnet, opus, or versioned (e.g., sonnet-4.5)
`timeout`	`number`	No	Maximum execution time in milliseconds (default: 300000)
`max_tokens`	`number`	No	Maximum tokens for model response (1000-200000)
`temperature`	`number`	No	Model temperature (0 = deterministic, 1 = creative)

Context Block

Defines what the agent can see — files, directories, and patterns.

Field	Type	Required	Description
`working_directory`	`string`	No	Base directory for relative paths (default: .)
`environment`	`object`	No	Environment variables to set
`timeout_behavior`	`enum`	No	Behavior on timeout: fail, warn, continue (default: fail)
`shell`	`enum`	No	Shell for commands: bash, sh, zsh, powershell (default: bash)
`data_sources`	`DataSource[]`	No	External APIs, MCP servers, or CLI tools the agent can query (v1.5.1)

Mission Block

The agent's purpose statement and exploration scope (Explorer/Forecaster types).

Field	Type	Required	Description
`opener`	`string`	No	Present-tense immersive opening statement
`stakes`	`string`	No	Why this validation/task matters
`outcome_framing`	`string`	No	What the agent produces
`role_boundaries`	`string[]`	No	Scope clarifications
`taxonomy_mandate`	`boolean`	No	Require failure codes (default: true)
`vocabulary_rationale`	`string`	No	Explains decision vocabulary choice (v1.5.0)
`explicit_prohibitions`	`string[]`	No	Actions agent must NOT do (v1.5.0)
`epistemic_limitations`	`string[]`	No	Agent knowledge boundary acknowledgments (v1.7.0)

Scoring Block

Score range, thresholds, criteria weights, and deduction rules. Required for Validator agents.

Field	Type	Required	Description
`maxScore`	`number`	Yes	Always 100 — total points available
`categories`	`Category[]`	Yes	Scoring categories with criteria (weights sum to 100)
`calibration_examples`	`CalibrationExample[]`	No	Example scores for consistent LLM scoring (v1.3.0)
`constraints`	`ScoringConstraints`	No	Scoring constraints (min/max per category)
`interpretation`	`string`	No	How to interpret scoring results (v1.7.0)
`weight_rationale`	`string`	No	Why weights are distributed as they are (v1.7.0)

Tasks Block

Execution tasks with steps and completion criteria. Required for Executor agents.

Field	Type	Required	Description
`inputs`	`Input[]`	Yes	What the executor/generator needs to operate
`operations`	`Task[]`	Yes	Discrete tasks the agent performs
`outputs`	`Output[]`	Yes	What the agent produces

Decisions Block

Decision vocabulary and threshold mappings. Required for Validator agents.

Field	Type	Required	Description
`vocabulary.positive`	`string`	Yes	Positive decision label (e.g., PASS, COMPLETE)
`vocabulary.negative`	`string`	Yes	Negative decision label (e.g., FAIL, FAILED)
`vocabulary.conditional`	`string`	No	Conditional decision label (e.g., WARN, PARTIAL)
`thresholds`	`Threshold[]`	Yes	Score ranges mapped to decisions
`preset`	`string`	No	Alternative to explicit thresholds
`tracking`	`DecisionTracking`	No	Decision persistence configuration

Forecast Block

Prediction framework, causal model, and timeline configuration. For Forecaster agents.

Field	Type	Required	Description
`actor_type`	`enum`	No	Prediction lens actor: rational, naive, adversarial, systemic, cultural, creative
`time_horizon`	`enum`	No	Prediction timeframe: near-term, medium-term, long-term
`propagation_mechanism`	`string`	No	How effects propagate through the system
`prediction_format`	`enum`	No	Output format: probability-weighted, spectrum, timeline, depth-map, interaction-map

Cognitive Lens Block

Philosophical framework configuration for analysis agents.

Field	Type	Required	Description
`thinker`	`string`	Yes	Kebab-case identifier for the thinker whose epistemic framework this agent encodes (e.g., aristotle, popper, hume)
`epistemic_depth`	`object`	No	Epistemic depth configuration with primary (first-order, second-order, third-order), capable (array), and target_description
`core_axioms`	`CoreAxiom[]`	No	Foundational assumptions of the thinker's framework. Each axiom has a statement and practical implications (1-10 items)
`failure_signatures`	`FailureSignature[]`	No	Known failure modes specific to this epistemic lens. Each has signature, description, and mitigation (1-10 items)

Composition Block

Declares how this agent composes with other agents and definitions.

Field	Type	Required	Description
`pairs_well_with`	`CompositionPairing[]`	No	Agents that complement this one. Each entry has agent, reason, pattern (adversarial_dialectic, parallel_reading, etc.), and optional depth
`covers_blind_spots_of`	`BlindSpotCoverage[]`	No	Agents whose blind spots this one addresses. Each entry has agent, blind_spot, and how
`has_blind_spots_covered_by`	`BlindSpotCoverage[]`	No	Agents that address this one's blind spots. Each entry has agent, blind_spot, and how

Handoff Block

Data exchange format for agent-to-agent communication in workflows.

Field	Type	Required	Description
`upstream_context`	`object`	No	What this agent accepts from upstream agents. Contains accepts (string[]) and description
`upstream_context.input_contract`	`string`	No	Explicit input requirements — format, cardinality, and error behavior when input is missing or ambiguous (v1.14.0)
`downstream_artifacts`	`object`	No	What this agent produces for downstream agents. Contains produces (string[]) and description

Failure Taxonomy

ADL agents classify findings using a structured failure taxonomy. Each finding gets a domain code and severity level.

Failure Domains

Code	Domain	Description
`STR`	Structural	Missing elements, incorrect organization, broken contracts
`SEM`	Semantic	Logical errors, contradictions, incorrect meaning
`PRA`	Pragmatic	Impractical, unusable, or operationally unsound
`EPI`	Epistemic	Unjustified claims, missing evidence, overconfidence

Severity Levels

Code	Severity	Description	Typical Validator Response
`C`	Critical	Blocks progression regardless of other factors	Auto-fail trigger
`H`	High	Significantly impacts quality	Heavy point deduction
`M`	Medium	Notable quality impact	Moderate point deduction
`L`	Low	Modest quality impact	Light point deduction
`I`	Info	Informational only	Note only, no point impact

Compound codes combine domain, mode, and severity: STR-OMI/C means Structural Omission, Critical. See the Failure Taxonomy for the complete reference including mode disambiguation rules.

Composition Rules

ℹ

Note

Validator — Required: interface, scoring, decisions. Optional: defaults, context, mission, knowledge_base, auto_fail, deductions, process, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: tasks, completion, rollback.

ℹ

Note

Executor — Required: interface, tasks, completion. Optional: defaults, context, mission, knowledge_base, decisions, rollback, process, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: scoring, deductions, auto_fail.

ℹ

Note

Analyst — Required: interface, process. Optional: defaults, context, mission, knowledge_base, scoring, decisions, deductions, auto_fail, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: tasks, completion, rollback.

ℹ

Note

Generator — Required: interface, tasks. Optional: defaults, context, mission, knowledge_base, completion, decisions, process, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: scoring, deductions, auto_fail.

ℹ

Note

Explorer — Required: interface, mission. Optional: defaults, context, knowledge_base, process, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: scoring, decisions, deductions, auto_fail, tasks, completion, rollback.

ℹ

Note

Forecaster — Required: interface, mission, process. Optional: defaults, context, knowledge_base, scoring, decisions, deductions, auto_fail, forecast, output, edge_cases, tone, handoff, cognitive_lens, composition. Forbidden: tasks, completion, rollback.

Revision History

Version	Date	Changes
1.16.0	2026-05-10	Tightened allOf rules: forecast section now forbidden on non-forecaster agent types via "forecast": false. Previously forecast was schema-permitted for all types but only rendered by the forecaster template, causing silent absorption.
1.15.0	2026-04-07	Relaxed maxLength constraints on 25 narrative fields to support richer cognitive lens agent definitions. Key bumps: opener 800→2000, stakes 400→1000, vocabulary_rationale 800→2000, axiom 300→800, interface.description 500→1000, decision_guidance 1500→2000, interpretation/weight_rationale 2000→3000.
1.14.0	2026-04-03	Added input_contract optional string field in handoff.upstream_context for explicit input requirements — format, cardinality, and error behavior when input is missing or ambiguous.
1.13.0	2026-03-24	Added epistemic_nature object in interface block for multi-axis epistemic classification of agents. Three independent optional axes: verifiability (mechanically_checkable, expert_judgment, not_checkable), determinism (deterministic, stochastic, environment_dependent), claim_type (factual, normative, observational). Supports empirical analysis of agent effectiveness.
1.11.0	2026-03-14	Increased character limits for cognitive lens fields: vocabulary_rationale (500→800), decision_guidance (1000→1500), stakes (300→400), failure_signature.mitigation (300→500). Cognitive lens agents require richer field content to encode counterintuitive decision vocabulary and composition guidance.
1.10.0	2026-03-02	Added cognitive-lens domain enum value. Added cognitive_lens block (thinker, epistemic_depth, core_axioms, failure_signatures). Added composition block (pairs_well_with, covers_blind_spots_of, has_blind_spots_covered_by). Formalized handoff block (upstream_context, downstream_artifacts).
1.9.0	2026-02-27	Added forecaster agent type — prediction-oriented agents with optional forecast block (actor_type, time_horizon, propagation_mechanism, prediction_format).
1.8.0	2026-02-26	Added explorer agent type — lightweight, mission-driven agents for tool-augmented codebase exploration.
1.7.0	2026-02-20	Added epistemic_limitations, key_definitions, domain_taxonomy, anti_pattern, interpretation, weight_rationale, decision_guidance, multi-pass methodology support.
1.6.0	2026-02-07	Added domain_profile, analyst and generator agent types, domain profile system with conditional rendering.
1.5.1	2026-01-28	Added data_sources in context block, formula and thresholds in verification.
1.5.0	2026-01-23	Added vocabulary_rationale, explicit_prohibitions in mission, success_criteria in decisions.
1.4.0	2026-01-15	Added reasoning_scaffolding, pre_decision_checklist in process, examples in output.
1.3.0	2026-01-14	Added calibration_examples, failure_code_examples, token_budget, section_order, display_id on auto-fail.
1.2.0	2026-01-13	Added mission block, knowledge_base block, extended verification with partial_scoring and definition_clarifications.
1.1.0	2026-01-12	Added risk_level, tools, context block, retry configuration, failure taxonomy, extended domains.
1.0.0	2026-01-11	Initial ADL specification. Unified schema for validator and executor agents.