@flowiseai/agentflow

Embeddable React component for building and visualizing AI agent workflows

⚠️ 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/agentflow is a React-based flow editor for creating AI agent workflows. It provides a visual canvas built on ReactFlow for connecting AI agents, LLMs, tools, and logic nodes.

Features

• Visual Canvas — Drag-and-drop flow editor built on ReactFlow with zoom, pan, minimap, and fit-to-view controls
• 15 Built-in Node Types — Start, Agent, LLM, Condition, Condition Agent, Human Input, Loop, Direct Reply, Custom Function, Tool, Retriever, Sticky Note, HTTP, Iteration, and Execute Flow
• Node Editor Dialog — Modal for editing node parameters with dynamic input types (text, number, boolean, dropdown, arrays, async options)
• Rich Text Editor — TipTap-based editor with syntax highlighting for JavaScript, TypeScript, Python, and JSON (lazy-loaded)
• Specialized Input Components — Condition builder, messages input (role + content), and structured output schema builder
• AI Flow Generator — Generate flows from natural language descriptions with model selection
• Flow Validation — Detects empty flows, missing start nodes, disconnected nodes, cycles, hanging edges, and per-node input errors with visual feedback
• Dark Mode — Full light/dark theme support via design tokens and CSS variables
• Read-Only Mode — Disable editing for view-only embedding
• Custom Rendering — Replace the default header and node palette with your own components via render props
• Imperative API — Programmatic control via ref (getFlow, validate, fitView, clear, addNode, toJSON)
• Request Interceptor — Customize outgoing API requests (headers, credentials) via an Axios interceptor callback
• Keyboard Shortcuts — Cmd/Ctrl+S to save

Installation

pnpm add @flowiseai/agentflow

Peer Dependencies:

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

Basic Usage

import { Agentflow } from '@flowiseai/agentflow'

import '@flowiseai/agentflow/flowise.css'

export default function App() {
    return (
        <div style={{ width: '100vw', height: '100vh' }}>
            <Agentflow apiBaseUrl='http://localhost:3000' token='your-api-key' />
        </div>
    )
}

With Initial Flow Data and Callbacks

import { useRef } from 'react'

import { Agentflow, type AgentFlowInstance, type FlowData } from '@flowiseai/agentflow'

import '@flowiseai/agentflow/flowise.css'

export default function App() {
    const ref = useRef<AgentFlowInstance>(null)

    const initialFlow: FlowData = {
        nodes: [
            {
                id: 'startAgentflow_0',
                type: 'agentflowNode',
                position: { x: 100, y: 100 },
                data: {
                    id: 'startAgentflow_0',
                    name: 'startAgentflow',
                    label: 'Start',
                    color: '#7EE787',
                    hideInput: true,
                    outputAnchors: [{ id: 'startAgentflow_0-output-0', name: 'start', label: 'Start', type: 'start' }]
                }
            }
        ],
        edges: [],
        viewport: { x: 0, y: 0, zoom: 1 }
    }

    return (
        <div style={{ width: '100vw', height: '100vh' }}>
            <Agentflow
                ref={ref}
                apiBaseUrl='http://localhost:3000'
                token='your-api-key'
                initialFlow={initialFlow}
                onFlowChange={(flow) => console.log('Flow changed:', flow)}
                onSave={(flow) => console.log('Flow saved:', flow)}
            />
        </div>
    )
}

Props

Imperative Methods (via ref)

Security: requestInterceptor

The requestInterceptor callback runs inside the Axios request pipeline and has access to the full request configuration, including authentication headers. This is the same trust model as any other callback prop (e.g., onSave, renderHeader) — the host application developer supplies the function and is responsible for its behavior.

Guidelines for consumers:

• Only pass trusted, developer-authored functions. Never use dynamically evaluated code (eval, new Function, etc.) or user-generated input as the interceptor.
• Follow the principle of least privilege — only read or modify the specific config properties you need (e.g., withCredentials, custom headers).
• If the interceptor throws, the error is caught, logged, and the original unmodified config is used so the request still proceeds safely.

Node Types

The following node types are available in the palette by default. Use the components prop to restrict which types are shown.

Design Note

<Agentflow> is an uncontrolled component. The initialFlow prop seeds the canvas state on mount, but the component owns its own state afterward. Use the ref for imperative access and onFlowChange to observe changes.

Exports

Beyond the main <Agentflow> component, the package exports utilities for advanced usage:

// Main component and provider
// Types

// Hooks
// Validation
// Node utilities

// Field visibility helpers

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test

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

Visit the examples directory for more usage patterns. See TESTS.md for the full test plan and coverage status.

Publishing

Version Update

Bump the version in package.json before publishing. Use npm version to update the version and create a git tag:

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

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

Verify Before Publishing

# Build and check the tarball contents
pnpm build
npm pack --dry-run

# Full publish dry-run (runs prepublishOnly + simulates upload)
npm publish --dry-run

Publish

# Prerelease — tagged so `npm install @flowiseai/agentflow` won't pick it up
npm publish --tag dev

# Stable release — gets the `latest` tag
npm publish

The prepublishOnly script automatically runs clean and build before every publish, so stale dist files are never uploaded.

Documentation

• ARCHITECTURE.md - Internal architecture and design patterns
• TESTS.md - Test plan, coverage tiers, and configuration
• Examples - Usage examples and demos

Contributing

This package follows a feature-based architecture with clear separation of concerns. See ARCHITECTURE.md for details on the project structure and development guidelines.

License

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

Part of the Flowise ecosystem