FlowLens AgentOps

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

English | 中文

Pages Demo | Quick Start | Architecture

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.
• 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

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.

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.

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	53 tests passed
Frontend Vitest suite	219 tests passed
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
• 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.