@flowiseai/observe

Embeddable React components for visualizing AI agent runtime observability — executions, evaluations, and more

⚠️ Status

This package is currently under active development.

• 🚧 Components are not yet fully functional
• ❌ End-to-end functionality is not complete
• 🔄 Features are still being implemented and tested
• ⚡ APIs may change before stable release
• 📝 Documentation is being updated as development progresses

Cannot be used in production. For development and testing purposes only.

Overview

@flowiseai/observe is the runtime observability SDK for Flowise. It provides embeddable React components for viewing execution traces, node-level step details, and human-in-the-loop interactions for AI agent workflows built with Flowise.

This is the "Observe" layer of the Build-Run-Observe trio alongside @flowiseai/agentflow (Build).

Features

• Execution List — Filterable, paginated table of agent executions across all agentflows, or scoped to a single agentflow via agentflowId
• Execution Detail — Resizable split-pane with a sidebar node tree and a right-side step viewer
• Node Step Viewer — Renders markdown, JSON, raw code, and HTML output per node step, with rendered/raw toggle
• Token / Cost / Time Metrics — Per-node execution metrics displayed inline
• Auto-Poll — Automatically refreshes while a run is INPROGRESS, stops on terminal state
• HITL Support — Approve/Reject buttons for human-input nodes when onHumanInput callback is provided
• State + Date Filters — Filter by execution state and date range
• Single-Row and Bulk Delete — Opt-in trash icon on row hover, plus bulk delete via checkbox selection
• Dark Mode — Full light/dark theme support via design tokens and CSS variables
• SDK-Owned Theme — No host theme required; ObserveProvider injects its own MUI theme

Installation

pnpm add @flowiseai/observe

Peer Dependencies:

pnpm add react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled

Note: ReactFlow is not a peer dependency. @flowiseai/observe is a viewer only — no canvas.

Basic Usage

Execution List

Displays all executions across every agentflow. Pass agentflowId to scope the list to a single flow — useful when embedding next to a specific agentflow canvas.

    return (
        
            
            

            
            
        
    )
}

Standalone Execution Detail

Renders the full step viewer for a single execution by ID — useful for deep-linking into a specific trace.

    return (
        
            
        
    )
}

With HITL Callback

The onHumanInput callback is how the host application handles human-in-the-loop responses. The SDK delegates routing entirely to the consumer — OSS calls Flowise directly, DevSite routes through the AgentForge proxy.

 {
        // OSS: call Flowise prediction endpoint directly
        await fetch(`/api/v1/prediction/${agentflowId}`, {
            method: 'POST',
            headers: { Authorization: `Bearer ${token}` },
            body: JSON.stringify(params.humanInput)
        })
        // DevSite: route through AgentForge proxy instead
    }}
/>

When onHumanInput is not provided, Approve/Reject buttons are not rendered. No auth complexity leaks into the SDK.

With Request Interceptor

token and requestInterceptor are both optional and compose: if both are provided, the Bearer header is set first, then the interceptor runs and can extend or override it.

API key (default):

// token alone — sets Authorization: Bearer header automatically

    

OSS session auth — embedding inside the Flowise UI where a session cookie already exists:

 {
        config.withCredentials = true
        config.headers['x-request-from'] = 'internal'
        return config
    }}
>
    

DevSite proxy auth — inject AgentForge proxy headers:

 {
        config.headers['x-agentforge-token'] = getProxyToken()
        return config
    }}
>
    

If the interceptor throws, the error is caught, logged, and the original unmodified config is used so the request still proceeds. Only pass trusted, developer-authored functions — never user-generated input.

Props

``

Root provider. Wraps ExecutionsViewer or ExecutionDetail. Injects the MUI theme, API client, and config context.

``

Filterable, paginated list of executions. Clicking a row opens ExecutionDetail in a side drawer. Must be rendered inside ``.

``

Resizable split-pane viewer for a single execution. Left sidebar shows the node tree; right panel shows NodeExecutionDetail for the selected step. Must be rendered inside ``.

Auto-Poll Behavior

Both ExecutionsViewer and ExecutionDetail auto-refresh while state === 'INPROGRESS':

INPROGRESS → polls every pollInterval ms
FINISHED | ERROR | TERMINATED | TIMEOUT | STOPPED → polling stops immediately

Set pollInterval={0} to disable auto-poll and rely on the manual refresh button only.

Deletion

Opt-in via allowDelete={true} on ExecutionsViewer. Shows a trash icon on row hover. Clicking opens an inline confirm dialog. The SDK calls DELETE /api/v1/executions internally on confirm.

Bulk delete is available via checkbox selection in the table header.

Types

type ExecutionState = 'INPROGRESS' | 'FINISHED' | 'ERROR' | 'TERMINATED' | 'TIMEOUT' | 'STOPPED'

interface Execution {
    id: string
    executionData: string // JSON-serialized NodeExecutionData[]
    state: ExecutionState
    agentflowId: string
    sessionId?: string
    isPublic: boolean
    createdDate: string
    updatedDate: string
    agentflow?: { id: string; name: string }
}

interface NodeExecutionData {
    nodeLabel: string
    nodeId: string
    data: unknown // rendered content (markdown string, object, etc.)
    previousNodeIds: string[]
    status: ExecutionState
    name?: string
    iterationIndex?: number
    parentNodeId?: string
    output?: unknown
}

interface HumanInputParams {
    question: string
    chatId: string
    humanInput: {
        type: 'proceed' | 'reject'
        startNodeId: string
        feedback?: string
    }
}

interface ExecutionFilters {
    state: ExecutionState | ''
    startDate: string
    endDate: string
    sessionId: string
    agentflowName: string // M2 only
}

Development

# Install dependencies (from monorepo root)
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

# Run examples dev server
cd examples && pnpm install && pnpm dev

Copy examples/.env.example to examples/.env and fill in your values before running the dev server.

Visit the examples directory for usage demos. See ARCHITECTURE.md for internal structure and design patterns.

Publishing

Version Update

# Prerelease (for testing / EA)
npm version prerelease --preid=dev   # 0.0.0-dev.1 → 0.0.0-dev.2

# Patch / Minor / Major (stable)
npm version patch                    # 0.0.1
npm version minor                    # 0.1.0
npm version major                    # 1.0.0

Verify Before Publishing

pnpm build
npm pack --dry-run
npm publish --dry-run

Publish

# EA / prerelease — tagged so npm install won't pick it up by default
npm publish --tag dev

# Stable release
npm publish

The prepublishOnly script runs clean and build automatically before every publish.

Documentation

• ARCHITECTURE.md — Internal architecture, layer rules, and patterns
• Examples — Running the demo app

License

Apache-2.0 — see the repository root LICENSE.md for details.

---

Part of the Flowise ecosystem