SCOPE observes, analyzes and explains the executions of Multi-Agent Systems (MAS) from their OpenTelemetry traces. It maps raw spans onto a shared MAS ontology, keeps every execution as a knowledge graph, and enriches each session with analyses such as semantic grouping, anomaly detection, consistency checking, cognitive-failure detection and stateful trajectory evaluation. A web dashboard and an API serve the result.
Run the whole stack on your machine with Docker Compose, send it the trace of a small two-agent example, and look at it in the dashboard. It takes about 15 minutes, most of it the first image build.
You need Docker (Compose v2.17 or later, with at least 6 GB of memory given to it) and uv to run the example. An OpenAI-compatible LLM endpoint is only needed for the analyses that call a model: without it, traces are still collected and stored in the knowledge graph.
git clone https://github.com/ioc-project/scope.git
cd scope/deploy/docker-compose
cp .env.template .env # set LLM_MODEL_NAME, EMBEDDING_MODEL_NAME, LLM_GATEWAY_* and the change-me passwords
docker compose up -d --buildcd ../../examples/currency-demo
OTLP_HTTP_ENDPOINT=http://localhost:4318 uv run main.py 100100.00 USD = 85.90 EUR (example rate)
| What | Where |
|---|---|
Dashboard and API: Applications → currency-demo → Inspect |
http://localhost:8080 |
The knowledge graph, in the Neo4j browser (neo4j and your NEO4J_PASSWORD) |
http://localhost:7474 |
The session shows up a few seconds after the example exits. The first-trace tutorial walks through each step with screenshots, and explains how to query the knowledge graph.
Tear down with docker compose down (add -v to also delete the data). To run SCOPE on Kubernetes instead, use the Helm chart. To trace your own application, see instrument your app; to see how SCOPE evaluates sessions against their peers, follow the semantic analysis tutorial.
- A MAS sends OTel spans to an OTel collector, which stores them (ClickHouse by default, swappable for another backend).
- Once a trace is complete, the SCOPE ingestion pipeline maps the raw spans onto the MAS ontology, producing a structured execution model: the topology of the system, and for each session its calls, states and transitions.
- The session is enriched by the analysis workers (semantic grouping, anomaly detection, consistency checking, cognitive failures, stateful evaluation, metrics).
- The enriched knowledge graph is served through the API and visualized in the UI, giving explainability and insight into the MAS's inner workings.
The documentation site is built from docs/ with mkdocs.yml and published at ioc-project.github.io/scope:
- Overview: what SCOPE is and how it works.
- Ingestion: the telemetry path, normalization and the ontology.
- Analysis: the analysis engines, pipelines, workers and components.
- Platform: the platform, API and UI.
- Tutorials: your first trace, semantic analysis, instrument your app and deploy SCOPE.
- Preview locally:
pip install -r docs/requirements.txt && mkdocs serve.
The ontology reference documentation (Widoco and WebVOWL) is generated separately:
- Ontology: ontology/index.md, also published at ioc-project.github.io/scope/ontologies.html
| Path | Description |
|---|---|
backend/ |
Python libraries and workers implementing ingestion, normalization, analysis, and the data API. See backend/README.md. |
backend/api |
Unified DB access layer and REST API over the raw OTel spans and the knowledge graph. |
backend/norm |
Normalizes raw OTel traces into structured MAS execution models. |
backend/mce |
Metric computation engine for sessions. |
backend/stateful-evals |
Cost-effective evaluation of a session's trajectory. |
backend/workers |
Standalone workers built on top of the backend libraries. |
ui/ |
React/TypeScript web dashboard for browsing applications, sessions, execution graphs, and live topology. See ui/README.md. |
ontology/ |
The MAS telemetry ontology (Turtle/OWL) and the scope-ontology Python package. See ontology/README.md. |
docs/ |
Documentation site sources (MkDocs), built with mkdocs.yml. |
deploy/ |
Deployment: Helm charts for Kubernetes (deploy/k8s) and a Docker Compose stack (deploy/docker-compose) running the API, UI, workers and supporting infra. |
Contributions are welcome — see CONTRIBUTING.md for guidelines, CODE_OF_CONDUCT.md for community standards, and SECURITY.md for reporting vulnerabilities. Maintainers are listed in MAINTAINERS.md.
Licensed under the Apache License 2.0 — see LICENSE for the full text.
