Architecture

ado-aw combines a Rust-based compiler with runtime components that support secure agent execution in Azure DevOps.

High-level architecture

At a high level, the project includes:

• a compiler that reads markdown agent files and emits Azure DevOps YAML
• multiple compile targets for different pipeline shapes
• configurable runtimes such as Python, Node.js, .NET, and Lean
• first-class tools and tool allow-lists for agent execution
• safe outputs that let agents propose controlled write actions
• MCP support for exposing tools and services through the Model Context Protocol

Main building blocks

Compiler

The compiler parses front matter, validates configuration, and renders pipeline templates for Azure DevOps.

Compile targets

ado-aw supports different output targets, including standalone pipelines and Azure DevOps template-style targets such as job and stage outputs.

Runtimes

Runtimes define the environment an agent needs for its work. For example, a workflow may require Python packages, Node.js tooling, or .NET support.

Tools and integrations

Agents can be given controlled access to built-in tools and MCP-backed integrations. This keeps capabilities explicit and reviewable.

Safe outputs

Safe outputs are the bridge between agent intent and real-world mutations. Instead of writing directly, the agent produces structured proposals that are checked before execution.

MCP

ado-aw can run SafeOutputs as an MCP server and can integrate with additional MCP services, making it easier to expose tools in a structured, auditable way.

Directory structure overview

A simplified view of the repository looks like this:

src/
  compile/       Pipeline compilation logic and targets
  runtimes/      Runtime environment support
  safeoutputs/   Safe-output tool implementations
  tools/         First-class tool integrations
  data/          Base pipeline templates and supporting assets
docs/            Detailed reference documentation
examples/        Example agent definitions
tests/           Integration tests and fixtures

How the pieces fit together

1. Author an agent file in markdown

   Write your pipeline intent in a .md file with YAML front matter and a natural-language body describing the agent’s task.

2. Compiler reads front matter and body

   The ado-aw compile command parses configuration from the YAML front matter and validates all fields against the schema.

3. Compile targets render Azure DevOps YAML

   Based on your target: (standalone, 1ES, job, or stage), the compiler selects the appropriate base template and performs marker replacement.

4. Runtimes, tools, and MCP integrations are added

   Configured runtimes (Python, Node.js, .NET, Lean) inject their setup steps, tool allow-lists are applied, and MCP server entries are wired into the pipeline.

5. Safe outputs connect Stage 1 proposals to Stage 3 execution

   The generated pipeline enforces the three-stage model: agent proposals in Stage 1, threat detection in Stage 2, and safe-output execution in Stage 3.

This separation helps keep the authoring model approachable while preserving strong runtime controls.