# agentops-ai/agentops architecture

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

- Interactive diagram: https://gitdiagram.com/agentops-ai/agentops
- Repository: https://github.com/agentops-ai/agentops

## Overview

AgentOps is an observability and developer platform for AI agents. The main workflow starts when a developer initializes the Python client and instruments agent/framework or LLM activity; spans and metrics are exported to the service, then queried and inspected in the dashboard as traces, replays, and analytics. The repository also includes public APIs, account and billing operations, and deployment management. Source excerpts show only part of this system, so several documented product connections are shown at a high level rather than as detailed internal call chains.

Main entry points: [`app/api/agentops/api/app.py`](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/app.py) (API Service), [`app/dashboard/app/(with-layout)/overview/page.tsx`](https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/overview/page.tsx) (Dashboard UI), [`agentops/client/client.py`](https://github.com/agentops-ai/agentops/blob/main/agentops/client/client.py) (SDK Client), [`agentops/sdk/core.py`](https://github.com/agentops-ai/agentops/blob/main/agentops/sdk/core.py) (Tracing Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["Python SDK"]
  node_client["SDK Client<br/>[client.py]"]
  node_tracing["Tracing Core<br/>[core.py]"]
  node_decorators["Span Decorators<br/>[factory.py]"]
  node_semconv["Span Conventions<br/>[span_attributes.py]"]
end

subgraph group_instrumentation["Instrumentation"]
  node_frameworks["Agent Frameworks"]
  node_llmproviders["LLM Providers"]
  node_commoninstr["Shared Instrumentation<br/>[attributes.py]"]
end

subgraph group_service["Service Backend"]
  node_api["API Service<br/>[app.py]"]
  node_publicapi["Public API<br/>[routes.py]"]
  node_auth["Authentication<br/>[views.py]"]
  node_traceapi["Trace API<br/>[views.py]"]
  node_metrics["Metrics API<br/>[views.py]"]
  node_storage["Object Uploads<br/>[storage.py]"]
  node_clickhouse[("ClickHouse Store")]
  node_supabase[("Supabase Store<br/>[supabase_client.py]")]
end

subgraph group_dashboard["Dashboard"]
  node_dashboardui["Dashboard UI<br/>[page.tsx]"]
  node_traceviewer["Trace Viewer<br/>[page.tsx]"]
  node_dashboardapi["Dashboard API Routes<br/>[route.ts]"]
  node_billing["Billing Management<br/>[billing.py]"]
  node_deployui["Deployment UI<br/>[page.tsx]"]
end

subgraph group_deployment["Deployment"]
  node_deployapi["Deployment API<br/>[routes.py]"]
  node_deployworker["Deployment Worker<br/>[worker.py]"]
  node_jobqueue["Job Queue<br/>[queue.py]"]
end

node_developer(("Developer"))
node_externalservices["External Services"]

node_developer -->|"initializes"| node_client
node_client -->|"starts tracing"| node_tracing
node_client -->|"enables instrumentation"| node_frameworks
node_developer -->|"adds spans"| node_decorators
node_frameworks -.->|"records activity"| node_commoninstr
node_llmproviders -.->|"records calls"| node_commoninstr
node_commoninstr -->|"uses conventions"| node_semconv
node_tracing -->|"uses conventions"| node_semconv
node_tracing -.->|"exports telemetry"| node_api
node_api -->|"mounts routes"| node_publicapi
node_publicapi -->|"routes authentication"| node_auth
node_publicapi -->|"routes trace queries"| node_traceapi
node_api -.->|"stores telemetry"| node_clickhouse
node_api -.->|"uses persistence"| node_supabase
node_dashboardui -.->|"requests dashboard data"| node_dashboardapi
node_dashboardapi -.->|"queries telemetry"| node_api
node_dashboardui -->|"opens trace detail"| node_traceviewer
node_dashboardui -.->|"shows analytics"| node_metrics
node_dashboardui -.->|"manages billing"| node_billing
node_dashboardui -.->|"manages deployments"| node_deployui
node_deployui -.->|"submits deployment"| node_deployapi
node_deployapi -.->|"dispatches jobs"| node_deployworker
node_deployworker -->|"claims and stores"| node_jobqueue
node_api -.->|"offers uploads"| node_storage
node_api -.->|"integrates services"| node_externalservices

click node_client "https://github.com/agentops-ai/agentops/blob/main/agentops/client/client.py"
click node_tracing "https://github.com/agentops-ai/agentops/blob/main/agentops/sdk/core.py"
click node_decorators "https://github.com/agentops-ai/agentops/blob/main/agentops/sdk/decorators/factory.py"
click node_semconv "https://github.com/agentops-ai/agentops/blob/main/agentops/semconv/span_attributes.py"
click node_frameworks "https://github.com/agentops-ai/agentops/tree/main/agentops/instrumentation/agentic"
click node_llmproviders "https://github.com/agentops-ai/agentops/tree/main/agentops/instrumentation/providers"
click node_commoninstr "https://github.com/agentops-ai/agentops/blob/main/agentops/instrumentation/common/attributes.py"
click node_api "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/app.py"
click node_publicapi "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/public/routes.py"
click node_auth "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/auth/views.py"
click node_traceapi "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/routes/v4/traces/views.py"
click node_metrics "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/routes/v4/metrics/views.py"
click node_storage "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/storage.py"
click node_clickhouse "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/db/clickhouse_client.py"
click node_supabase "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/db/supabase_client.py"
click node_dashboardui "https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/overview/page.tsx"
click node_traceviewer "https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/traces/page.tsx"
click node_dashboardapi "https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/traces/api/route.ts"
click node_billing "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/opsboard/views/billing.py"
click node_deployui "https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/deploy/page.tsx"
click node_deployapi "https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/deploy/routes.py"
click node_deployworker "https://github.com/agentops-ai/agentops/blob/main/app/deploy/jockey/worker/worker.py"
click node_jobqueue "https://github.com/agentops-ai/agentops/blob/main/app/deploy/jockey/worker/queue.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_client,node_tracing,node_decorators,node_semconv toneBlue
class node_frameworks,node_llmproviders,node_commoninstr toneAmber
class node_api,node_publicapi,node_auth,node_traceapi,node_metrics,node_storage,node_clickhouse,node_supabase toneMint
class node_dashboardui,node_traceviewer,node_dashboardapi,node_billing,node_deployui toneRose
class node_deployapi,node_deployworker,node_jobqueue,node_developer,node_externalservices toneIndigo
```

## Components

### Python SDK

- [SDK Client](https://github.com/agentops-ai/agentops/blob/main/agentops/client/client.py): `agentops/client/client.py`
- [Tracing Core](https://github.com/agentops-ai/agentops/blob/main/agentops/sdk/core.py): `agentops/sdk/core.py`
- [Span Decorators](https://github.com/agentops-ai/agentops/blob/main/agentops/sdk/decorators/factory.py): `agentops/sdk/decorators/factory.py`
- [Span Conventions](https://github.com/agentops-ai/agentops/blob/main/agentops/semconv/span_attributes.py): `agentops/semconv/span_attributes.py`

### Instrumentation

- [Agent Frameworks](https://github.com/agentops-ai/agentops/tree/main/agentops/instrumentation/agentic): `agentops/instrumentation/agentic`
- [LLM Providers](https://github.com/agentops-ai/agentops/tree/main/agentops/instrumentation/providers): `agentops/instrumentation/providers`
- [Shared Instrumentation](https://github.com/agentops-ai/agentops/blob/main/agentops/instrumentation/common/attributes.py): `agentops/instrumentation/common/attributes.py`

### Service Backend

- [API Service](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/app.py): `app/api/agentops/api/app.py`
- [Public API](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/public/routes.py): `app/api/agentops/public/routes.py`
- [Authentication](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/auth/views.py): `app/api/agentops/auth/views.py`
- [Trace API](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/routes/v4/traces/views.py): `app/api/agentops/api/routes/v4/traces/views.py`
- [Metrics API](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/routes/v4/metrics/views.py): `app/api/agentops/api/routes/v4/metrics/views.py`
- [Object Uploads](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/storage.py): `app/api/agentops/api/storage.py`
- [ClickHouse Store](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/db/clickhouse_client.py): `app/api/agentops/api/db/clickhouse_client.py`
- [Supabase Store](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/api/db/supabase_client.py): `app/api/agentops/api/db/supabase_client.py`

### Dashboard

- [Dashboard UI](https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/overview/page.tsx): `app/dashboard/app/(with-layout)/overview/page.tsx`
- [Trace Viewer](https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/traces/page.tsx): `app/dashboard/app/(with-layout)/traces/page.tsx`
- [Dashboard API Routes](https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/traces/api/route.ts): `app/dashboard/app/(with-layout)/traces/api/route.ts`
- [Billing Management](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/opsboard/views/billing.py): `app/api/agentops/opsboard/views/billing.py`
- [Deployment UI](https://github.com/agentops-ai/agentops/blob/main/app/dashboard/app/(with-layout)/deploy/page.tsx): `app/dashboard/app/(with-layout)/deploy/page.tsx`

### Deployment

- [Deployment API](https://github.com/agentops-ai/agentops/blob/main/app/api/agentops/deploy/routes.py): `app/api/agentops/deploy/routes.py`
- [Deployment Worker](https://github.com/agentops-ai/agentops/blob/main/app/deploy/jockey/worker/worker.py): `app/deploy/jockey/worker/worker.py`
- [Job Queue](https://github.com/agentops-ai/agentops/blob/main/app/deploy/jockey/worker/queue.py): `app/deploy/jockey/worker/queue.py`

### Other components

- **Developer**
- **External Services**

## Connections

- Developer → SDK Client: initializes (evidence: `README.md`)
- SDK Client → Tracing Core: starts tracing (evidence: `agentops/client/client.py`)
- SDK Client → Agent Frameworks: enables instrumentation (evidence: `agentops/client/client.py`)
- Developer → Span Decorators: adds spans (evidence: `README.md`)
- Agent Frameworks → Shared Instrumentation: records activity (evidence: `agentops/instrumentation/agentic/agno/attributes/storage.py`)
- LLM Providers → Shared Instrumentation: records calls (evidence: `agentops/instrumentation/providers/openai/wrappers/embeddings.py`)
- Shared Instrumentation → Span Conventions: uses conventions (evidence: `agentops/instrumentation/common/attributes.py`)
- Tracing Core → Span Conventions: uses conventions (evidence: `agentops/sdk/core.py`)
- Tracing Core → API Service: exports telemetry
- API Service → Public API: mounts routes
- Public API → Authentication: routes authentication (evidence: `app/api/agentops/public/routes.py`)
- Public API → Trace API: routes trace queries (evidence: `app/api/agentops/public/routes.py`)
- API Service → ClickHouse Store: stores telemetry
- API Service → Supabase Store: uses persistence
- Dashboard UI → Dashboard API Routes: requests dashboard data
- Dashboard API Routes → API Service: queries telemetry
- Dashboard UI → Trace Viewer: opens trace detail (evidence: `README.md`)
- Dashboard UI → Metrics API: shows analytics
- Dashboard UI → Billing Management: manages billing
- Dashboard UI → Deployment UI: manages deployments
- Deployment UI → Deployment API: submits deployment
- Deployment API → Deployment Worker: dispatches jobs
- Deployment Worker → Job Queue: claims and stores (evidence: `app/deploy/jockey/worker/worker.py`)
- API Service → Object Uploads: offers uploads
- API Service → External Services: integrates services
