# microsoft/agentrx architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/agentrx
- Repository: https://github.com/microsoft/agentrx

## Overview

AgentRx diagnoses failed AI-agent executions: a user supplies a trajectory, which is normalized to Trajectory IR, analyzed for static and per-step invariants, checked for violations, and passed to an LLM judge for failure-step and taxonomy classification; reports summarize results. The graph preserves the documented stages and major modules. Some implementation details are unsampled, so edges rely on the README or SOURCE INDEX references where available; optional client selection is shown separately.

Main entry points: [`run.py`](https://github.com/microsoft/agentrx/blob/main/run.py) (Pipeline Runner), [`agentrx/invariants/checker.py`](https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/checker.py) (Invariant Checker), [`agentrx/judge/judge.py`](https://github.com/microsoft/agentrx/blob/main/agentrx/judge/judge.py) (Failure Judge), [`agentrx/llm_clients/azure.py`](https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/azure.py) (Azure Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input Normalization"]
  node_runner["Pipeline Runner<br/>[run.py]"]
  node_cli["Package CLI<br/>[cli.py]"]
  node_ir["Trajectory IR<br/>[trajectory_ir.py]"]
end

subgraph group_analysis["Invariant Analysis"]
  node_domains["Domain Registry<br/>[domain_registry.py]"]
  node_static["Static Invariants"]
  node_dynamic["Dynamic Invariants"]
  node_checker["Invariant Checker<br/>[checker.py]"]
end

subgraph group_diagnosis["Diagnosis and Reports"]
  node_judge["Failure Judge<br/>[judge.py]"]
  node_frequency["Failure Frequencies"]
  node_metrics["Run Metrics<br/>[metrics.py]"]
end

subgraph group_support["Runtime Support"]
  node_azure["Azure Client<br/>[azure.py]"]
  node_trapi["TRAPI Client<br/>[trapi.py]"]
  node_copilot["Copilot Client<br/>[copilot_cli.py]"]
  node_globals["Runtime Settings<br/>[globals.py]"]
end

node_user(("Trajectory User"))

node_user -->|"submits trajectory"| node_runner
node_runner -->|"normalizes logs"| node_ir
node_runner -->|"runs stage"| node_static
node_runner -->|"runs stage"| node_dynamic
node_runner -->|"runs stage"| node_checker
node_runner -->|"runs stage"| node_judge
node_runner -->|"runs report"| node_frequency
node_cli -.->|"launches pipeline"| node_runner
node_ir -->|"uses converters"| node_domains
node_static -->|"loads domain config"| node_domains
node_dynamic -->|"reads trajectory"| node_ir
node_checker -->|"reads trajectory"| node_ir
node_checker -->|"uses invariants"| node_static
node_checker -->|"creates client"| node_azure
node_checker -->|"creates client"| node_trapi
node_checker -->|"creates client"| node_copilot
node_judge -->|"uses client"| node_azure
node_judge -->|"uses client"| node_trapi
node_judge -->|"uses client"| node_copilot
node_judge -->|"uses telemetry"| node_metrics
node_azure -->|"reads settings"| node_globals
node_azure -->|"records telemetry"| node_metrics
node_trapi -->|"reads settings"| node_globals
node_copilot -->|"reads settings"| node_globals
node_runner -->|"produces report"| node_frequency

click node_runner "https://github.com/microsoft/agentrx/blob/main/run.py"
click node_cli "https://github.com/microsoft/agentrx/blob/main/agentrx/cli.py"
click node_ir "https://github.com/microsoft/agentrx/blob/main/agentrx/ir/trajectory_ir.py"
click node_domains "https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/domain_registry.py"
click node_static "https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/static_invariant_generator.py"
click node_dynamic "https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/dynamic_invariant_generator.py"
click node_checker "https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/checker.py"
click node_judge "https://github.com/microsoft/agentrx/blob/main/agentrx/judge/judge.py"
click node_frequency "https://github.com/microsoft/agentrx/blob/main/agentrx/reports/analyze_failure_frequencies.py"
click node_metrics "https://github.com/microsoft/agentrx/blob/main/agentrx/reports/metrics.py"
click node_azure "https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/azure.py"
click node_trapi "https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/trapi.py"
click node_copilot "https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/copilot_cli.py"
click node_globals "https://github.com/microsoft/agentrx/blob/main/agentrx/pipeline/globals.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_cli,node_ir,node_user toneBlue
class node_domains,node_static,node_dynamic,node_checker toneAmber
class node_judge,node_frequency,node_metrics toneMint
class node_azure,node_trapi,node_copilot,node_globals toneRose
```

## Components

### Input Normalization

- [Pipeline Runner](https://github.com/microsoft/agentrx/blob/main/run.py): `run.py`
- [Package CLI](https://github.com/microsoft/agentrx/blob/main/agentrx/cli.py): `agentrx/cli.py`
- [Trajectory IR](https://github.com/microsoft/agentrx/blob/main/agentrx/ir/trajectory_ir.py): `agentrx/ir/trajectory_ir.py`

### Invariant Analysis

- [Domain Registry](https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/domain_registry.py): `agentrx/invariants/domain_registry.py`
- [Static Invariants](https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/static_invariant_generator.py): `agentrx/invariants/static_invariant_generator.py`
- [Dynamic Invariants](https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/dynamic_invariant_generator.py): `agentrx/invariants/dynamic_invariant_generator.py`
- [Invariant Checker](https://github.com/microsoft/agentrx/blob/main/agentrx/invariants/checker.py): `agentrx/invariants/checker.py`

### Diagnosis and Reports

- [Failure Judge](https://github.com/microsoft/agentrx/blob/main/agentrx/judge/judge.py): `agentrx/judge/judge.py`
- [Failure Frequencies](https://github.com/microsoft/agentrx/blob/main/agentrx/reports/analyze_failure_frequencies.py): `agentrx/reports/analyze_failure_frequencies.py`
- [Run Metrics](https://github.com/microsoft/agentrx/blob/main/agentrx/reports/metrics.py): `agentrx/reports/metrics.py`

### Runtime Support

- [Azure Client](https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/azure.py): `agentrx/llm_clients/azure.py`
- [TRAPI Client](https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/trapi.py): `agentrx/llm_clients/trapi.py`
- [Copilot Client](https://github.com/microsoft/agentrx/blob/main/agentrx/llm_clients/copilot_cli.py): `agentrx/llm_clients/copilot_cli.py`
- [Runtime Settings](https://github.com/microsoft/agentrx/blob/main/agentrx/pipeline/globals.py): `agentrx/pipeline/globals.py`

### Other components

- **Trajectory User**

## Connections

- Trajectory User → Pipeline Runner: submits trajectory (evidence: `README.md`)
- Pipeline Runner → Trajectory IR: normalizes logs (evidence: `run.py`)
- Pipeline Runner → Static Invariants: runs stage (evidence: `run.py`)
- Pipeline Runner → Dynamic Invariants: runs stage (evidence: `run.py`)
- Pipeline Runner → Invariant Checker: runs stage (evidence: `run.py`)
- Pipeline Runner → Failure Judge: runs stage (evidence: `run.py`)
- Pipeline Runner → Failure Frequencies: runs report (evidence: `run.py`)
- Package CLI → Pipeline Runner: launches pipeline
- Trajectory IR → Domain Registry: uses converters (evidence: `agentrx/ir/trajectory_ir.py`)
- Static Invariants → Domain Registry: loads domain config (evidence: `agentrx/invariants/static_invariant_generator.py`)
- Dynamic Invariants → Trajectory IR: reads trajectory (evidence: `agentrx/invariants/dynamic_invariant_generator.py`)
- Invariant Checker → Trajectory IR: reads trajectory (evidence: `agentrx/invariants/checker.py`)
- Invariant Checker → Static Invariants: uses invariants (evidence: `agentrx/invariants/checker.py`)
- Invariant Checker → Azure Client: creates client (evidence: `agentrx/invariants/checker.py`)
- Invariant Checker → TRAPI Client: creates client (evidence: `agentrx/invariants/checker.py`)
- Invariant Checker → Copilot Client: creates client (evidence: `agentrx/invariants/checker.py`)
- Failure Judge → Azure Client: uses client (evidence: `agentrx/judge/judge.py`)
- Failure Judge → TRAPI Client: uses client (evidence: `agentrx/judge/judge.py`)
- Failure Judge → Copilot Client: uses client (evidence: `agentrx/judge/judge.py`)
- Failure Judge → Run Metrics: uses telemetry (evidence: `agentrx/judge/judge.py`)
- Azure Client → Runtime Settings: reads settings (evidence: `agentrx/llm_clients/azure.py`)
- Azure Client → Run Metrics: records telemetry (evidence: `agentrx/llm_clients/azure.py`)
- TRAPI Client → Runtime Settings: reads settings (evidence: `agentrx/llm_clients/trapi.py`)
- Copilot Client → Runtime Settings: reads settings (evidence: `agentrx/llm_clients/copilot_cli.py`)
- Pipeline Runner → Failure Frequencies: produces report (evidence: `README.md`)