FlowLens AgentOps

Evidence-driven observability and deterministic failure attribution for multi-agent runtimes.

English | 中文

Pages Demo | Quick Start | Architecture | Dual MCP Validation | Maintainer Handoff

Built on DeerFlow 2.0 under the MIT License. DeerFlow provides the Agent runtime, tools, subagents, memory, MCP, sandbox, and application foundation. FlowLens adds the diagnostics and AgentOps product layer described below.

Why FlowLens

A checkpoint can restore state, but it does not explain why a multi-agent run failed. A final exception also loses the decisions and dependencies that led to it. FlowLens records lightweight append-only runtime events and turns them into:

• a normalized execution Timeline across model, tool, subagent, middleware, MCP, memory, and runtime phases;
• deduplicated run Metrics derived from RunRecord counters and correlated spans;
• deterministic failure Attribution with evidence, contributing causes, confidence, and suggested action;
• redacted diagnostic export and an optional LLM explanation that cannot change the rule result;
• one shared dashboard for authenticated Connected data and seven no-key Replay scenarios.

Product Surface

• Run Explorer: search and inspect recent user-owned runs across threads.
• Execution Timeline: filter phases, follow span_id/parent_span_id, and inspect safe event metadata.
• Health Metrics: duration, tokens, tool and subagent counts, errors, MCP, memory, rollback, and completeness.
• Root Cause: rule-based primary cause, evidence links, contributing failures, and remediation guidance.
• Replay mode: success, tool error, subagent timeout, guardrail denial, checkpoint rollback, MCP auth error, and memory error.
• Connected mode: reads the real DeerFlow Gateway and RunEventStore through owner-checked APIs.
• Dual MCP validation: internal SQLite Analytics and FlowLens Inspector services demonstrate bounded read-only data access and user-bound runtime delegation.
• Portable delivery: Next.js route, Vite static build, Docker/Nginx demo, CI, and GitHub Pages workflow.

Architecture

The diagnostics path is read-only: it does not mutate checkpoints, prompts, RunRecord state, or historical events. See architecture.md for ownership boundaries and degradation behavior.

Quick Start

Choose a mode

Mode	What it proves	Requirements	URL
Replay	Dashboard interactions and deterministic synthetic failure scenarios	Node.js or Docker; no model key	http://localhost:5173 or http://localhost:4173
Connected Runtime	Real DeerFlow runs emitted into the AgentOps event pipeline	Normal DeerFlow configuration, account, and model provider	http://localhost:2026/agentops
Connected + dual MCP	Runtime delegation, read-only SQLite Analytics MCP, and FlowLens Inspector MCP	Docker Desktop plus the Connected Runtime requirements	http://localhost:2027/agentops

No-key Replay with pnpm

git clone https://github.com/try1004/FlowLens-AgentOps.git
cd FlowLens-AgentOps/frontend
corepack enable
pnpm install --frozen-lockfile
pnpm agentops:demo:dev

Open http://localhost:5173. This mode uses synthetic, contract-validated fixtures and requires no backend, model, account, or API key.

No-key Replay with Docker

git clone https://github.com/try1004/FlowLens-AgentOps.git
cd FlowLens-AgentOps
make flowlens-demo

Open http://localhost:4173, then stop it with make flowlens-stop.

On Windows without make, run the Compose command directly:

docker compose -f docker/docker-compose-flowlens-demo.yaml up --build

Press Ctrl+C to stop the foreground Replay container.

Connected DeerFlow runtime

make setup
make up

Open http://localhost:2026/agentops. Connected mode requires the normal DeerFlow configuration, authentication, and at least one configured model provider. It uses the same React components and Zod contracts as Replay mode.

Connected runtime with dual MCP services

The development stack runs two internal-only Streamable HTTP MCP services:

• SQLite Analytics MCP exposes schema inspection and SELECT-only local demonstration-data queries.
• FlowLens Inspector MCP queries owner-checked diagnostic data through the Gateway.

Schemas are discovered with a restricted service token. A real tool invocation receives a short-lived token bound to the current user_id and run_id; the model never receives that token.

From the repository root in PowerShell:

$env:DEER_FLOW_ROOT = (Get-Location).Path
$env:HOME = $env:USERPROFILE
$env:DEER_FLOW_CONTAINER_PREFIX = "flowlens-agentops"
$env:DEER_FLOW_HTTP_PORT = "2027"

docker compose -p flowlens-agentops `
  -f docker/docker-compose-dev.yaml `
  -f docker/docker-compose-agentops-isolated.yaml `
  up -d --build --remove-orphans frontend gateway nginx sqlite-analytics flowlens-inspector

Invoke-RestMethod http://localhost:2027/health

Open http://localhost:2027/, sign in, then open http://localhost:2027/agentops. To exercise the real SQLite path, start a new chat and send:

Use the SQLite Analytics MCP to inspect the available schema, describe the agent_runs table, then count runs by status. Execute read-only SQL only, state the SQL used, and label the result as local demonstration data.

The selected Run should show MCP events in Timeline and an MCP > 0 metric. The Dual MCP Validation Guide and Chinese end-to-end runbook cover expected evidence, policy-rejection cases, and shutdown.

Diagnostic APIs

Method	Endpoint	Purpose
GET	/api/agentops/runs	Cursor-paginated, user-scoped run index
GET	/api/threads/{thread_id}/runs/{run_id}/timeline	Phase-filtered Timeline, default 200 and maximum 2,000 events
GET	/api/threads/{thread_id}/runs/{run_id}/diagnostics	Timeline, Metrics, Attribution, warnings, and completeness; maximum 5,000 events
GET	/api/threads/{thread_id}/runs/{run_id}/diagnostics/export	Download the same redacted diagnostics contract
POST	/api/threads/{thread_id}/runs/{run_id}/explanation	Optional natural-language explanation of the fixed rule result

All Connected run endpoints reuse DeerFlow permission checks and owner validation.

{
  "run_id": "run-tool-error",
  "status": "error",
  "data_completeness": "complete",
  "metrics": {
    "total_events": 5,
    "tool_call_count": 1,
    "tool_error_count": 1,
    "failure_category": "TOOL_ERROR"
  },
  "failure_attribution": {
    "primary_cause": "TOOL_ERROR",
    "confidence": 0.8,
    "evidence": [{ "seq": 4, "event_type": "tool.error" }],
    "suggested_action": "Inspect tool arguments, sandbox path mapping, and tool output."
  }
}

Upstream and FlowLens Ownership

DeerFlow foundation	FlowLens addition
LangGraph Agent runtime and RunManager	Append-only diagnostic event conventions and RunJournal adapters
Lead Agent, SubagentExecutor, tools, middleware, and sandbox	Correlated Timeline with stable span hierarchy
MCP client, sessions, tools, and OAuth	MCP session, tool, and OAuth diagnostic events
Memory middleware, queue, and updater	Privacy-safe memory injection and update diagnostics
Checkpoints, RunEventStore, and RunRecord	Metrics, completeness, warnings, deterministic attribution, and export
Gateway permissions and authentication	User-scoped AgentOps index and read-only diagnostic APIs
Next.js workspace	AgentOps dashboard, dual data sources, Replay fixtures, and static Pages entry

FlowLens does not claim authorship of the DeerFlow runtime modules. See NOTICE and the unchanged MIT License.

Verified Evidence

Gate	Result
Focused backend FlowLens/API suite	58 tests passed on 2026-07-31
Frontend Vitest suite	234 tests passed on 2026-07-31
Frontend quality gate	ESLint, TypeScript, Next production build, and Vite Replay build passed on 2026-07-31
Real MCP integration probe	ToolNode -> delegated OAuth token -> SQLite schema tool completed locally
Next and static Replay Playwright	5 tests passed across route, desktop, tablet, and mobile workflows
Secret scan	No high-confidence credentials in Git-tracked files
In-process diagnostics benchmark	2,000 events, 20 iterations, median 24.7578 ms, P95 36.5606 ms

The benchmark measures local Python redaction, Timeline, Metrics, and Attribution only. It excludes network, model, database, and browser latency. Reproduce it with:

make flowlens-benchmark
make flowlens-check

The machine-readable result is committed at flowlens-benchmark.json.

Security and Privacy

• Diagnostic output recursively redacts authorization, cookies, API keys, OAuth tokens, passwords, client secrets, and raw memory fields.
• Tool content is bounded before it reaches Timeline, export, or the optional explainer.
• The explainer receives only redacted structured evidence, has no tools, and cannot override primary_cause.
• Unknown events remain visible as phase=unknown; malformed metadata is downgraded with a warning instead of crashing the run view.
• Truncation returns data_completeness=partial; EventStore degradation returns degraded. Neither is presented as complete.
• scripts/check_flowlens_secrets.py scans only Git-tracked text files and never prints the matched value.

Documentation

• Architecture and data flow
• Event schema and instrumentation
• Failure attribution rules
• Replay and Connected demo guide
• Dual MCP validation guide
• Chinese dual MCP end-to-end runbook
• Maintainer handoff and next steps
• Contributing
• Changelog

Current Boundaries

FlowLens v0.1 focuses on developer diagnostics. It is not an MCP configuration console, a memory-content editor, a billing platform, a production alert manager, or a replacement for OpenTelemetry/LangSmith distributed tracing. Replay data is synthetic; Connected mode remains responsible for runtime configuration and credentials.

License and Acknowledgements

This repository remains under the MIT License and preserves the upstream copyright notices. FlowLens AgentOps is a secondary development based on ByteDance DeerFlow. Thanks to the DeerFlow authors and contributors for the runtime and application foundation.