A lightweight React component for visualizing AI Agent execution traces from SSE streams. Free, unlimited, local-first. No cloud account required.

Live Demo · NPM · Documentation · Examples · Changelog · Contributing

• Real-time SSE streaming with automatic reconnection
• 6 view modes: List, Timeline, Waterfall, DAG, Swimlane, Cluster
• Virtual scrolling — handles 100K+ events smoothly
• Dark/Light themes with full CSS variable customization
• Responsive layout — works on mobile and desktop

• Full-text search (Ctrl/Cmd+K) across all event fields
• Time range filter with datetime pickers
• Event type filter checkboxes
• Agent filter with drag-to-reorder
• Bookmarks & pinning for important events

• Cost dashboard — total cost, per-agent breakdown, pie chart
• Token usage chart — cumulative tokens over time
• Performance bottleneck detection — slow tools, high cost, error rates
• Event breakpoints — pause on specific event types
• Event snapshots — save/load event state via IndexedDB
• Event diff — side-by-side comparison of two events
• JSON syntax highlighting in tool arguments
• Duration visualization bars for tool calls

• Export events as JSON or CSV
• Record raw SSE streams as JSONL for replay
• IndexedDB persistence for session restore
• Event stream recording for debugging

• TypeScript with strict mode and full type exports
• i18n — English and Chinese built-in
• ARIA accessibility — proper roles, labels, and keyboard navigation
• Sound feedback — optional audio cues for errors and status changes
• Custom renderers — override message and result rendering
• Storybook — interactive component development

• Transport adapters: SSE (default), WebSocket, HTTP Polling
• Framework examples: Next.js, Vite, Express, FastAPI
• Agent framework examples: LangGraph, OpenAI Agents, CrewAI

npm install agent-sse-flow
# or
pnpm add agent-sse-flow

import { AgentFlow } from 'agent-sse-flow'
import 'agent-sse-flow/style.css'

function App() {
  return (
    <AgentFlow
      url="http://localhost:8080/agent/stream"
      theme="dark"
    />
  )
}

That's it. The component connects to your SSE endpoint and renders the agent execution trace in real time.

Send JSON events from your backend:

{"type": "start", "message": "Agent started", "agentName": "researcher", "agentColor": "#3b82f6"}
{"type": "thinking", "message": "Analyzing request...", "agentName": "researcher"}
{"type": "tool_call", "tool": "search_web", "args": {"query": "AI news"}, "agentName": "researcher"}
{"type": "tool_result", "result": "Found 10 results...", "duration": 1250}
{"type": "message", "message": "Here's what I found...", "cost": 0.002, "tokens": 150}
{"type": "error", "message": "Rate limit exceeded"}
{"type": "end", "message": "Done", "cost": 0.015, "tokens": 1200, "duration": 3500}

All fields except type are optional. See API Reference for the full FlowEvent interface.

Customize with CSS variables:

<AgentFlow
  url="/api/stream"
  customTheme={{
    '--af-accent': '#10b981',
    '--af-bg': '#0f172a',
    '--af-text': '#e2e8f0',
    '--af-border': '#1e293b',
  }}
/>

See the full list of CSS variables in the API Reference.

# Install dependencies
pnpm install

# Start dev server (with mock SSE server)
pnpm dev

# Run tests
pnpm test

# Type check
pnpm type-check

# Build library
pnpm build

# Storybook
pnpm dev-storybook

Contributions are welcome! Please read the Contributing Guide for details on:

• Development setup
• Coding conventions
• Commit format
• Pull request process

MIT © 2025