# microsoft/azure-pipelines-agent architecture

> Architecture diagram of the GitHub repository microsoft/azure-pipelines-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/azure-pipelines-agent
- Repository: https://github.com/microsoft/azure-pipelines-agent

## Overview

##### Project type and purpose
- This is the cross‐platform Azure Pipelines Agent: a .NET Core C# application that connects to Azure DevOps/TFS, polls for build or release jobs, and executes pipeline tasks on Windows, Linux, and macOS hosts.
- It uses a plugin‐based architecture to host a variety of task plugins (artifact download, test result parsing, caching, etc.), and communicates over HTTP/REST with Azure DevOps services (JobServer, BlobStore, Telemetry).

##### File structure analysis
- Top‐level folders:
- .azure-pipelines, .github, release, tools – CI/CD pipelines, signing, release scripts, tooling
- docs – design docs, threat models, troubleshooting, contribution guidelines
- src – main code, broken into subprojects:
– Agent.Listener (CLI entrypoint & job dispatcher)
– Agent.Worker (task execution engine)
– Agent.Service (Windows service wrapper)
– Agent.Plugins (artifact, cache, test publisher, result parser, Git/SVN sources)
– Agent.PluginHost (isolated plugin host process)
– Agent.Sdk (common library for plugins & core)
– Microsoft.VisualStudio.Services.Agent (shared core abstractions)
– Misc (layout scripts, packaging templates)
- Test – unit (L0) and integration (L1) tests structured by component
- Configuration and build: Common.props, NuGet.Config, .NET target files, YAML pipelines, PowerShell/ bash helpers.

##### Key insights from README
- Emphasizes cross‐platform .NET Core, supported OSes.
- Highlights build & test status, contribution & troubleshooting pointers.

1. Agent.Listener process (CLI):
- Subcomponents: CommandLine handlers (ConfigureAgent, RunAgent, RemoveAgent), Configuration managers (Linux, Windows, macOS), SelfUpdater, TelemetryPublisher.
2. Agent.Service (Windows service host).
3. Agent.Worker process:
- Subcomponents: JobRunner, TaskManager, ExecutionContext, Container manager, CodeCoverage, TestResults, Telemetry, Handlers (PowerShell, Node, ProcessHandler).
4. Agent.PluginHost (optional isolated host for heavy plugins).
5. Agent.Plugins library set:
- Artifact plugins (PipelineArtifact, BuildArtifact, FileShare), PipelineCache, TestFilePublisher, TestResultParser, Git/SVN source plugins, etc.
6. Agent.Sdk & Microsoft.VisualStudio.Services.Agent libraries (shared abstractions, HTTP clients, credential store, logging, knobs).
7. External services:
- Azure DevOps Server / Azure Pipelines REST API (JobServer, TaskServer, BlobStore, LocationServer)
- External systems: Git/TFS repositories, Docker Daemon, Test frameworks, File shares.

- Listener → Azure DevOps Server (poll/push over HTTP)
- Listener → JobDispatcher → Worker(s)
- Worker ↔ PluginHost (loads plugins via Agent.Sdk)
- Worker → Plugins (invoke task code)
- Plugins → External resources (download/upload artifacts, talk to blob store, Git/TFS)
- Worker → Container engine (Docker) for container‐based tasks
- Worker → Test runners → TestResults → Azure DevOps Test APIs
- All components → Telemetry service (CustomerIntelligenceServer)

c. Architectural patterns & design principles
- Plugin architecture: runtime discovery & execution isolation
- Process separation: CLI (Listener) decoupled from execution engine (Worker) and optional PluginHost
- Cross‐platform abstractions: OS‐specific configuration managers under a common interface
- Dependency inversion: core uses interfaces (ITraceWriter, ICredentialStore, IContainerProvider) implemented per platform
- Resilience: retry helpers, cancellation tokens, job timeouts, configuration knobs

d. Technologies & frameworks
- .NET Core / .NET 6/.NET 8 C#
- YAML pipelines for CI (Azure DevOps YAML)
- PowerShell & Bash scripts for installation, signing, release
- REST clients (HttpClient) for Azure DevOps services
- Telemetry (CustomerIntelligenceServer over HTTPS)
- Docker CLI & container APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Listener["Agent.Listener\n(CLI entrypoint & job dispatcher)"]:::process
    end

    %% Execution Layer
    subgraph "Execution Layer"
        Worker["Agent.Worker\n(Task execution engine)"]:::process
        PluginHost["Agent.PluginHost\n(Isolated plugin host)"]:::process
    end

    %% Extension Points
    subgraph "Extension Points"
        Plugins["Agent.Plugins\n(artifact, cache, test, source plugins)"]:::plugin
    end

    %% Core Libraries
    subgraph "Core Libraries"
        Sdk["Agent.Sdk\n(Common library & interfaces)"]:::library
        VSSAgent["Microsoft.VisualStudio.Services.Agent\n(Shared abstractions, HTTP, logging)"]:::library
    end

    %% External Dependencies
    subgraph "External Dependencies"
        AzureDevOps["Azure DevOps REST API\n(JobServer, BlobStore, Telemetry)"]:::external
        GitTFS["Git/TFS Repositories"]:::external
        Docker["Docker Daemon"]:::external
        FileShare["File Shares"]:::external
        TestFramework["Test Frameworks"]:::external
        Telemetry["CustomerIntelligence Server"]:::external
    end

    %% Connections
    Listener -->|"polls jobs"| AzureDevOps
    Listener -->|"dispatch job"| Worker
    Worker -->|"load plugins"| PluginHost
    Worker -->|"invoke tasks"| Plugins
    Plugins -->|"artifact ops"| AzureDevOps
    Plugins -->|"SCM operations"| GitTFS
    Worker -->|"run in container"| Docker
    Worker -->|"publish test results"| TestFramework
    Plugins -->|"read/write cache"| FileShare
    Listener -->|"telemetry"| Telemetry
    Worker -->|"telemetry"| Telemetry
    PluginHost -->|"telemetry"| Telemetry

    %% Click Events
    click Listener "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Agent.Listener"
    click Worker "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Agent.Worker"
    click PluginHost "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Agent.PluginHost"
    click Plugins "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Agent.Plugins"
    click Sdk "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Agent.Sdk"
    click VSSAgent "https://github.com/microsoft/azure-pipelines-agent/blob/master/src/Microsoft.VisualStudio.Services.Agent"

    %% Styles
    classDef process fill:#f9f,stroke:#333,stroke-width:1px
    classDef plugin fill:#ffc,stroke:#333,stroke-width:1px
    classDef library fill:#ccf,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px
```
