Agent Types

The six agent types — validators, executors, analysts, generators, explorers, and forecasters — their output shapes, ADL constraints, and when to use each.

Overview

Every UluOps agent is defined by a type, and type determines output shape, ADL schema constraints, and composition rules. The platform supports six agent types split into two families:

• Non-writing agents read and analyze without modifying artifacts: validators, analysts, explorers, forecasters
• Writing agents produce or modify artifacts: executors, generators

At a Glance

Epistemic Nature

Independent of agent type, each agent can declare its epistemic nature — a multi-axis classification describing what kind of claims it makes and how verifiable they are. This was added in ADL v1.13.0.

Agents of the same type can have different epistemic natures. For example, code-validator (mechanically checkable, factual) and security-analyst (expert judgment, factual) are both validators, but their findings have different verifiability characteristics. This distinction matters for empirical analysis of agent effectiveness — see the RAH service for false-positive rate analysis across epistemic categories.

See the ADL Specification for classification guidelines and the full axis reference.

Validators

Validators are the most mature agent type and the foundation of UluOps quality gates. Each validator scores a target from 0 to 100 against weighted criteria, produces a pass/fail decision, and emits findings with file paths, line numbers, and failure taxonomy codes.

Output shape:

{
  "score": 85,
  "decision": "PASS",
  "findings": [
    {
      "title": "Missing error handling",
      "filePath": "src/api/client.ts",
      "lineNumber": 42,
      "severity": "H",
      "failureDomain": "PRA"
    }
  ]
}

Examples: code-validator, type-safety-validator, test-architect, frontend-validator, security-analyst, docs-validator, mcp-validator, sql-validator

Known characteristics:

• Lowest rejection rate of any type — empirical validators average ~17% rejection
• Strongest tracker integration — scores, issues, and correlation all tracked automatically
• Quality ceiling gradient — diminishing returns above score 90 on repeated runs
• Threshold sensitivity — validators near the 85/70 boundaries create the most actionable findings

Executors

Executors perform tasks that modify state or produce artifacts. They are the action-oriented counterpart to validators — where a validator identifies what's wrong, an executor fixes it. Executors use a tasks block to define their inputs, steps, and completion criteria, and a completion block to define success/failure conditions.

Output shape:

{
  "status": "COMPLETE",
  "artifacts": [
    {
      "type": "file",
      "path": "src/auth.ts",
      "action": "modified",
      "description": "Added null check on line 42"
    }
  ],
  "summary": "Fixed 3 of 3 identified issues"
}

ADL schema constraints:

• Required: interface, tasks, completion
• Forbidden: scoring, decisions, deductions — executors produce changes, not judgments
• Optional: rollback — defines how to undo changes if execution fails

The tasks block defines structured inputs and steps:

The completion block defines what success looks like:

Current status: No executor agents are registered in the ecosystem yet. The type is fully specified in ADL v1.0.0 and schema-validated, but the existing remediation pattern uses fix commands (/fix:test-gaps, /fix:security, /fix:type-safety) which are iterative validator-fix loops rather than standalone executor agents.

Planned use cases:

• Issue auto-fixing from tracker findings
• Code migration and refactoring operations
• Configuration generation from templates
• Dependency upgrade workflows

When to use: When you need an agent that does something rather than evaluates something. When the agent's output is changed files, created artifacts, or modified state rather than a score or report.

Analysts

Analysts produce structured audits, decompositions, and coherence assessments. Unlike validators, analysts investigate why something is the way it is rather than scoring how good it is. Their output is investigation-oriented rather than gate-oriented.

Output shape:

{
  "analysis": {
    "sections": [
      { "title": "Material Cause", "content": "..." },
      { "title": "Formal Cause", "content": "..." }
    ]
  },
  "decision": "TELEOLOGICAL",
  "recommendations": [...]
}

The cognitive lens pattern: Many analysts use a cognitive_lens block to encode a philosophical framework that shapes their analysis:

Specialized analysts target specific failure patterns rather than general analysis:

When to use: When you need deep investigation rather than a pass/fail gate. When you want structured reasoning about why something is the way it is.

Known characteristics:

• Higher rejection rates than validators (~31%) due to subjective evaluation
• assumption-excavator achieves 70% completion despite being subjective — challenges the "analyst = lifecycle mismatch" assumption
• Custom decision vocabularies per agent (e.g., TELEOLOGICAL/ATELEOLOGICAL, EXAMINED/UNEXAMINED, CONSISTENT/CONTRADICTED)

Generators

Generators produce artifacts from structured inputs. Where executors modify existing state, generators create new things from scratch. They use a tasks block (like executors) but without completion — generators define what to produce rather than what to change.

Output shape:

{
  "status": "COMPLETE",
  "artifacts": [
    {
      "type": "file",
      "path": "agents/new-agent.agent.yaml",
      "action": "created",
      "description": "Generated ADL schema with 5 scoring categories"
    }
  ],
  "decisions_requiring_input": []
}

ADL schema constraints:

• Required: interface, tasks
• Forbidden: scoring, deductions, auto_fail — generators produce artifacts, not judgments
• Optional: completion (not required like executors)

Key difference from executors: Generators create new artifacts; executors modify existing ones. Generators don't need completion criteria because the artifact either exists or it doesn't — there's no partial modification state to track.

Examples:

Both generators use a COMPLETE/PARTIAL/BLOCKED vocabulary:

• COMPLETE — artifact was generated and written to disk
• PARTIAL — artifact was generated but sections need user clarification
• BLOCKED — generation cannot proceed (duplicate agent, contradictory requirements)

When to use: When you need to scaffold new artifacts from requirements or specifications. When the output is a new file rather than a modified one.

Known characteristics:

• Generators naturally pair with validators — generate an artifact, then validate it (e.g., adl-generator → adl-meta-validator)
• Both current generators include duplicate detection to avoid generating overlapping agents
• Generators are the newest agent family (introduced in ADL v1.6.0)

Explorers

Explorers produce discovery artifacts — categorical maps, inventories, commitment extractions. They are the most purely read-only type: no scoring, no decisions, just discovery. Explorers answer "what's here?" rather than "is it good?"

Output shape:

{
  "report": "Structured exploration narrative...",
  "discoveries": [
    {
      "category": "Commitment",
      "content": "The artifact claims X but never defines X"
    }
  ]
}

The cognitive lens pattern: Like analysts, most explorers operate through a philosophical framework:

Explorers have the most restricted ADL schema — they forbid scoring, decisions, deductions, auto_fail, tasks, completion, and rollback. This enforces their read-only, discovery-oriented nature.

When to use: When entering an unfamiliar codebase or domain. When you need a map before you can validate. When the question is "what exists and how does it relate?" rather than "does it meet criteria?"

Known characteristics:

• Observations are tracked and auto-collected — explorer output is parsed into structured discoveries stored in the tracker via the SDK
• Most valuable as a first step before running validators or analysts
• deep-explore is the only non-philosophical explorer — it uses semantic search and call graph tracing rather than a cognitive lens

Forecasters

Forecasters model future states rather than evaluating present states. They produce trajectory projections, decay predictions, and causal chain analyses. Where validators ask "is this good now?" and analysts ask "why is this the way it is?", forecasters ask "what happens next?"

Output shape:

{
  "predictions": [
    {
      "title": "Knowledge decay in auth module",
      "timeHorizon": "6 months",
      "confidence": "HIGH",
      "mechanism": "Dependency drift"
    }
  ],
  "causalChains": [
    { "trigger": "...", "consequence": "...", "depth": 2 }
  ]
}

The forecast block: Unique to forecasters — configures the prediction lens:

Examples:

When to use: When current quality is good but you need to know how it will degrade. When you want to detect second-order effects of changes. When planning maintenance schedules.

Known characteristics:

• Predictions are inherently less verifiable than present-state analysis
• Most valuable for platform-level artifacts, infrastructure, and policy
• Custom decision vocabularies per agent (e.g., DURABLE/FRAGILE, BOUNDED/GENERATIVE, SHALLOW/DEEP)
• Weirdness increases with cascade depth — third-order predictions are speculative by nature

Choosing the Right Type

The boundary between types is enforced at the schema level — ADL validation will reject a validator that includes tasks, or a generator that includes scoring. This prevents type confusion and ensures each agent's output shape matches what the tracker and SDK expect.

Tracker Integration

Each type integrates differently with the validation tracker:

All six types produce output that can be recorded as a run. The difference is how much of that output maps to the tracker's structured data model versus remaining as narrative text.

Type Maturity

The six types were introduced across different ADL versions, reflecting their maturity:

Registry counts from list_definitions, tracker runs from get_analytics({ metric: "agent_performance" }). Generators and explorers don't produce scored runs tracked in the standard pipeline. As of March 2026, 217+ total definitions are published across all types (agents, commands, workflows, pipelines).