# mizcausevic-dev/agentobserve architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/agentobserve
- Repository: https://github.com/mizcausevic-dev/agentobserve

## Overview

Purpose and principal workflow: AgentObserve is an operations API for observing and governing AI-agent fleets, with run traces, cost and latency checks, SLA scoring, and operational posture outputs. The principal workflow begins when an external agent runtime submits a completed run to `POST /api/ingest/run`; separate evaluation endpoints let API clients request governance checks. The sampled ingest handler validates and summarizes spans but explicitly does not persist the run or invoke the detectors.

Components

**HTTP application and API**
- **Express application** — `src/index.ts`: Builds the Express app, installs middleware, exposes health and Swagger routes, mounts API routers, and listens when run as the main module.
- **Run intake and evaluation routes** — `src/routes/evaluate.ts`: Defines run ingestion and cost, regression, SLA, and combined run-audit endpoints; validates request bodies and calls governance functions for evaluation routes.
- **Fleet, run, incident, and dashboard reads** — `src/routes/agents.ts`: Serves agent and baseline details, recent and full run records, incidents, and a calculated fleet summary from in-memory data.
- **Request schemas** — `src/schemas/validation-schemas.ts`: Defines Zod payload and span validation, including the accepted run-ingestion and evaluation request shapes.
- **API documentation** — `src/docs/swagger.ts`: Provides the OpenAPI specification mounted at `/docs`; its specification contents were not sampled.

**Governance evaluations**
- **Cost and budget evaluation** — `src/governance/cost-anomaly.ts`: Compares submitted run cost with an agent’s baseline and monthly budget, then returns a status, issues, and recommended action.
- **Regression evaluation** — `src/governance/regression-detector.ts`: Scores latency, output-length drift, repeated tool calls, retries, and terminal status against baseline data and configured thresholds.
- **SLA evaluation** — `src/governance/sla-evaluator.ts`: Assesses agent latency and success-rate targets, computes remaining error budget, and returns compliance status and guidance.
- **Combined run audit** — `src/governance/run-audit.ts`: The README describes a combined per-run posture audit using regression and cost checks; implementation details were not sampled.

**Domain data and state**
- **Agent fleet registry** — `src/data/agents.ts`: Defines the in-memory agent catalog, ownership, operating status, budget and SLA metrics, and agent lookup.
- **Runs, baselines, and incidents** — `src/data/runs.ts`: Holds in-memory run traces, baseline metrics, and incident records used by read routes and governance logic; ingestion does not persist into this state in the sampled handler.

**External participants**
- **Agent runtime** — null repository path: External producer that submits a completed run and its spans.
- **API clients and fleet operators** — null repository path: External consumers of evaluation and fleet-read APIs; the README frames these outputs as supporting on-call and fleet reviews.

Relationships
- **Agent runtime -> Express application**: Sends the completed-run HTTP request; the app parses JSON and mounts the intake routes.
- **Express application -> Run intake and evaluation routes**: Dispatches requests under `/api/ingest` and `/api/evaluate` to the corresponding routers.
- **Run intake and evaluation routes -> Request schemas**: Validates ingestion and evaluation payloads with Zod before handling them.
- **Run intake and evaluation routes -> Agent runtime**: Returns an ingestion acknowledgment with run and agent IDs, span count, and summed cost and latency; it does not write the submitted run to the in-memory run records.
- **API clients and fleet operators -> Express application**: Call the mounted fleet-read and governance endpoints over HTTP.
- **Express application -> Fleet, run, incident, and dashboard reads**: Dispatches `/api/agents`, `/api/runs`, `/api/incidents`, and `/api/dashboard` requests to the read routers.
- **Fleet, run, incident, and dashboard reads -> Agent fleet registry**: Reads agent records and resolves agent IDs and names.
- **Fleet, run, incident, and dashboard reads -> Runs, baselines, and incidents**: Reads runs, baselines, and incidents and derives summary counts and metrics.
- **Run intake and evaluation routes -> Cost and budget evaluation**: Calls the cost evaluator for `/cost-anomaly` requests.
- **Run intake and evaluation routes -> Regression evaluation**: Calls the regression evaluator for `/regression` requests.
- **Run intake and evaluation routes -> SLA evaluation**: Calls the SLA evaluator for `/sla` requests.
- **Run intake and evaluation routes -> Combined run audit**: Calls the audit function for `/run-audit` requests; the route supplies a run ID and returns not-found when no audit result is produced.
- **Regression evaluation -> Agent fleet registry**: Looks up the requested agent.
- **Regression evaluation -> Runs, baselines, and incidents**: Reads the matching run and baseline to calculate regression findings.
- **Cost and budget evaluation -> Agent fleet registry**: Reads the agent’s monthly spend and budget.
- **Cost and budget evaluation -> Runs, baselines, and incidents**: Reads the agent’s baseline cost P95.
- **SLA evaluation -> Agent fleet registry**: Reads the agent’s observed metrics and SLA thresholds.
- **Combined run audit -> Regression evaluation**: The README describes regression checks as part of the combined audit; detailed call wiring is not established by the sampled source.
- **Combined run audit -> Cost and budget evaluation**: The README describes cost checks as part of the combined audit; detailed call wiring is not established by the sampled source.

Coverage limits: The combined audit implementation was not sampled, so its exact detector calls and decision logic cannot be confirmed. The documented API includes additional endpoint behavior not visible in the supplied route excerpts. The repository sample shows in-memory example data and no persistent ingestion path; it does not establish how production telemetry, incident routing, or external alert delivery would work.

Main entry points: [`src/routes/evaluate.ts`](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/routes/evaluate.ts) (Run and evaluation routes), [`src/index.ts`](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/index.ts) (Express application), [`src/governance/cost-anomaly.ts`](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/cost-anomaly.ts) (Cost evaluation), [`src/governance/regression-detector.ts`](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/regression-detector.ts) (Regression evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_express_app["Express application<br/>HTTP server"]
  node_evaluation_routes["Run and evaluation routes<br/>API routes"]
  node_read_routes["Fleet and run reads<br/>API routes"]
  node_request_schemas["Request schemas<br/>Validation"]
end

subgraph group_governance["Governance Evaluations"]
  node_cost_evaluation["Cost evaluation<br/>Governance"]
  node_regression_evaluation["Regression evaluation<br/>Governance"]
  node_sla_evaluation["SLA evaluation<br/>Governance"]
  node_run_audit["Combined run audit<br/>Governance"]
end

subgraph group_data["In-Memory Data"]
  node_agent_registry[("Agent fleet registry<br/>In-memory state")]
  node_run_records[("Runs and baselines<br/>In-memory state")]
end

subgraph group_external["External Participants"]
  node_agent_runtime["Agent runtime<br/>External producer"]
  node_api_clients["API clients and operators<br/>External consumers"]
end

node_agent_runtime -->|"submits run"| node_express_app
node_express_app -->|"dispatches requests"| node_evaluation_routes
node_evaluation_routes -->|"validates payloads"| node_request_schemas
node_evaluation_routes -->|"returns acknowledgment"| node_agent_runtime
node_api_clients -->|"calls APIs"| node_express_app
node_express_app -->|"dispatches reads"| node_read_routes
node_read_routes -->|"reads agents"| node_agent_registry
node_read_routes -->|"reads run data"| node_run_records
node_evaluation_routes -->|"calls cost check"| node_cost_evaluation
node_evaluation_routes -->|"calls regression check"| node_regression_evaluation
node_evaluation_routes -->|"calls SLA check"| node_sla_evaluation
node_evaluation_routes -->|"calls audit"| node_run_audit
node_regression_evaluation -->|"looks up agent"| node_agent_registry
node_regression_evaluation -->|"reads run baseline"| node_run_records
node_cost_evaluation -->|"reads budget"| node_agent_registry
node_cost_evaluation -->|"reads baseline cost"| node_run_records
node_sla_evaluation -->|"reads metrics"| node_agent_registry
node_run_audit -.->|"includes checks"| node_regression_evaluation
node_run_audit -.->|"includes checks"| node_cost_evaluation

click node_express_app "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/index.ts"
click node_evaluation_routes "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/routes/evaluate.ts"
click node_read_routes "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/routes/agents.ts"
click node_request_schemas "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/schemas/validation-schemas.ts"
click node_cost_evaluation "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/cost-anomaly.ts"
click node_regression_evaluation "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/regression-detector.ts"
click node_sla_evaluation "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/sla-evaluator.ts"
click node_run_audit "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/run-audit.ts"
click node_agent_registry "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/data/agents.ts"
click node_run_records "https://github.com/mizcausevic-dev/agentobserve/blob/main/src/data/runs.ts"

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_express_app,node_evaluation_routes,node_read_routes,node_request_schemas toneBlue
class node_cost_evaluation,node_regression_evaluation,node_sla_evaluation,node_run_audit toneAmber
class node_agent_registry,node_run_records toneMint
class node_agent_runtime,node_api_clients toneRose
```

## Components

### HTTP API

Express application, request handling, and fleet read routes.

- [Express application](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/index.ts): HTTP server · `src/index.ts`
- [Run and evaluation routes](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/routes/evaluate.ts): API routes · `src/routes/evaluate.ts`
- [Fleet and run reads](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/routes/agents.ts): API routes · `src/routes/agents.ts`
- [Request schemas](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/schemas/validation-schemas.ts): Validation · `src/schemas/validation-schemas.ts`

### Governance Evaluations

Cost, regression, SLA, and combined run-audit checks.

- [Cost evaluation](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/cost-anomaly.ts): Governance · `src/governance/cost-anomaly.ts`
- [Regression evaluation](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/regression-detector.ts): Governance · `src/governance/regression-detector.ts`
- [SLA evaluation](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/sla-evaluator.ts): Governance · `src/governance/sla-evaluator.ts`
- [Combined run audit](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/governance/run-audit.ts): Governance · Documented combined audit; implementation details were not sampled. · `src/governance/run-audit.ts`

### In-Memory Data

Agent registry and run-related records used by reads and evaluations.

- [Agent fleet registry](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/data/agents.ts): In-memory state · `src/data/agents.ts`
- [Runs and baselines](https://github.com/mizcausevic-dev/agentobserve/blob/main/src/data/runs.ts): In-memory state · Also holds incident records. · `src/data/runs.ts`

### External Participants

Run producers and API consumers.

- **Agent runtime**: External producer
- **API clients and operators**: External consumers

## Connections

- Agent runtime → Express application: submits run
- Express application → Run and evaluation routes: dispatches requests
- Run and evaluation routes → Request schemas: validates payloads
- Run and evaluation routes → Agent runtime: returns acknowledgment · Acknowledges the run without persisting it.
- API clients and operators → Express application: calls APIs
- Express application → Fleet and run reads: dispatches reads
- Fleet and run reads → Agent fleet registry: reads agents
- Fleet and run reads → Runs and baselines: reads run data
- Run and evaluation routes → Cost evaluation: calls cost check
- Run and evaluation routes → Regression evaluation: calls regression check
- Run and evaluation routes → SLA evaluation: calls SLA check
- Run and evaluation routes → Combined run audit: calls audit
- Regression evaluation → Agent fleet registry: looks up agent
- Regression evaluation → Runs and baselines: reads run baseline
- Cost evaluation → Agent fleet registry: reads budget
- Cost evaluation → Runs and baselines: reads baseline cost
- SLA evaluation → Agent fleet registry: reads metrics
- Combined run audit → Regression evaluation: includes checks · Documented audit behavior; exact call wiring is unconfirmed.
- Combined run audit → Cost evaluation: includes checks · Documented audit behavior; exact call wiring is unconfirmed.