diff --git a/.github/workflows/publish-agentflow.yml b/.github/workflows/publish-agentflow.yml index 56e8154b67a..4d0e058ad2a 100644 --- a/.github/workflows/publish-agentflow.yml +++ b/.github/workflows/publish-agentflow.yml @@ -18,12 +18,13 @@ on: required: false type: string tag: - description: 'npm dist-tag' + description: 'npm dist-tag (dev = internal, next = pre-release, latest = stable)' required: false type: choice default: 'dev' options: - dev + - next - latest jobs: diff --git a/packages/agentflow/CHANGELOG.md b/packages/agentflow/CHANGELOG.md new file mode 100644 index 00000000000..0a464a7531d --- /dev/null +++ b/packages/agentflow/CHANGELOG.md @@ -0,0 +1,32 @@ +# Changelog + +All notable changes to `@flowiseai/agentflow` will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.0.0-dev.13] - 2026-04-17 + +### Added + +- Core canvas functionality (add, connect, edit, delete, duplicate nodes) +- 15 built-in node types (Start, Agent, LLM, Condition, Condition Agent, Human Input, Loop, Direct Reply, Custom Function, Tool, Retriever, Sticky Note, HTTP, Iteration, Execute Flow) +- Node editor dialog with dynamic input types (text, number, boolean, dropdown, arrays, JSON, code, variable selector, async options) +- Async option loading for models, tools, and credentials +- Variable system with `{{variable}}` syntax and visual picker +- Field visibility based on input values (show/hide conditions) +- Flow validation with visual feedback (empty flows, missing start node, disconnected nodes, cycles, hanging edges, per-node input errors) +- Connection constraints (single Start node, no nested Iteration, cycle prevention) +- Flow export as JSON with secret stripping +- AI flow generation from natural language descriptions +- Credential creation dialog inline from node editor +- Dark/light mode theming via design tokens and CSS variables +- Read-only mode for view-only embedding +- Custom rendering via `renderHeader` and `renderNodePalette` render props +- Imperative API via ref (`getFlow`, `validate`, `fitView`, `clear`, `addNode`, `toJSON`) +- Request interceptor for customizing outgoing API requests +- Dirty state tracking +- Keyboard shortcut: Cmd/Ctrl+S to save +- CodeMirror rich code editor (JavaScript, Python, JSON) +- TipTap rich text / markdown editor +- 10 working examples demonstrating all features diff --git a/packages/agentflow/README.md b/packages/agentflow/README.md index 23d4c9837b0..97f17c36b79 100644 --- a/packages/agentflow/README.md +++ b/packages/agentflow/README.md @@ -5,17 +5,21 @@ > Embeddable React component for building and visualizing AI agent workflows -## ⚠️ Status +## Status: Dev -**This package is currently under active development.** +**Current version: `0.0.0-dev.13`** -- 🚧 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 +This package is functional and has comprehensive test coverage, but the public API may still change before a stable release. It is suitable for early integration and testing but not yet recommended for production use. -**Cannot be used in production. For development and testing purposes only.** +**What works today:** + +- 13 node types with full editing support (Loop and Human Input nodes are present in the palette but not yet fully verified end-to-end) +- Connection validation, flow validation, and export +- Async option loading (models, credentials, tools) +- Variable picker and field visibility conditions +- AI flow generation from natural language +- Dark/light mode theming +- Read-only mode and custom rendering via render props ## Overview @@ -24,7 +28,7 @@ ## 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 +- **13 Built-in Node Types** — Start, Agent, LLM, Condition, Condition Agent, 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, JSON, code, variable selector, async options) - **Credential Management** — Create and edit credentials inline from the node editor - **Rich Text Editor** — TipTap-based editor with syntax highlighting for JavaScript, TypeScript, Python, and JSON (lazy-loaded) @@ -113,6 +117,22 @@ export default function App() { } ``` +### More Examples + +The [examples app](./examples/README.md) includes working demos for: + +- **Variable usage** — `{{variable}}` syntax, variable picker, available sources +- **Async options** — Loading models, tools, and credentials from the API +- **Status indicators** — Node execution states (running, finished, error, stopped) +- **Field visibility** — Show/hide conditions on node inputs +- **State management** — Dirty tracking, flow change callbacks +- **Dark mode** — Light/dark theme toggle +- **Custom UI** — Custom header and node palette via render props +- **Filtered components** — Restricting available node types with presets +- **Validation actions** — Validation button, error display, and custom `canvasActions` alongside built-in controls + +Run `cd examples && npm install && npm run dev` to try them locally. + ## Props @@ -122,6 +142,7 @@ export default function App() { | `token` | `string` | — | Authentication token for API calls | | `requestInterceptor` | `(config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig` | — | Customize outgoing API requests (e.g., set `withCredentials`, add headers). The callback receives the full Axios request config — only modify what you need. See [Security: requestInterceptor](#security-requestinterceptor) below. | | `initialFlow` | `FlowData` | — | Initial flow data to render (uncontrolled — only used on mount) | +| `flowId` | `string` | — | Flow identifier (reserved for future use) | | `components` | `string[]` | — | Restrict which node types appear in the palette | | `onFlowChange` | `(flow: FlowData) => void` | — | Called when the flow changes (node/edge add, remove, move) | | `onSave` | `(flow: FlowData) => void` | — | Called when the user triggers a save | @@ -131,6 +152,7 @@ export default function App() { | `showDefaultHeader` | `boolean` | `true` | Show built-in header (ignored if `renderHeader` provided) | | `showDefaultPalette` | `boolean` | `true` | Show built-in node palette | | `enableGenerator` | `boolean` | `true` | Show the AI flow generator button | +| `canvasActions` | `ReactNode` | — | Additional content rendered in the top-right canvas overlay, to the right of the built-in validation FAB. Hidden when `readOnly` is true. | | `renderHeader` | `(props: HeaderRenderProps) => ReactNode` | — | Custom header renderer | | `renderNodePalette` | `(props: PaletteRenderProps) => ReactNode` | — | Custom node palette renderer | @@ -168,8 +190,6 @@ The following node types are available in the palette by default. Use the `compo | `llmAgentflow` | LLM / language model call | | `conditionAgentflow` | Conditional branching | | `conditionAgentAgentflow` | Agent-level conditional branching | -| `humanInputAgentflow` | Wait for user input | -| `loopAgentflow` | Loop / iteration | | `directReplyAgentflow` | Direct response to user | | `customFunctionAgentflow` | Custom JavaScript function | | `toolAgentflow` | Tool integration | @@ -201,44 +221,35 @@ cd examples && pnpm install && pnpm dev Visit the [examples](./examples) directory for more usage patterns. See [TESTS.md](./TESTS.md) for the full test plan and coverage status. -## Publishing +## Troubleshooting -### Version Update +### API Connection Issues -Bump the version in `package.json` before publishing. Use `npm version` to update the version and create a git tag: +- **CORS errors** — Ensure the Flowise server allows requests from your app's origin. Check the Flowise CORS configuration. +- **401 Unauthorized** — Use an API Key (Settings > API Keys), not a JWT user token. Verify the key is passed via the `token` prop. +- **Wrong `apiBaseUrl`** — The URL must point to the Flowise API root (e.g., `http://localhost:3000`), not a subpath. -```bash -# Prerelease (for testing) -npm version prerelease --preid=dev # 0.0.0-dev.1 → 0.0.0-dev.2 +### Validation Errors -# Patch / Minor / Major (for stable releases) -npm version patch # 0.0.1 -npm version minor # 0.1.0 -npm version major # 1.0.0 -``` +- **"Flow is empty"** — Add at least one node to the canvas. +- **"Missing start node"** — Every flow requires a `startAgentflow` node. Add one from the palette. +- **"Disconnected nodes"** — All non-sticky-note nodes must be reachable from the start node. Connect any orphaned nodes. +- **"Cycle detected"** — Flows must be acyclic (DAGs). Remove the edge that creates the cycle. -### Verify Before Publishing +### Theme Issues -```bash -# Build and check the tarball contents -pnpm build -npm pack --dry-run - -# Full publish dry-run (runs prepublishOnly + simulates upload) -npm publish --dry-run -``` +- **Dark mode not applying** — Pass `isDarkMode={true}` as a prop. The component uses its own design tokens and does not inherit from the host app's theme. +- **Style conflicts** — Ensure `@flowiseai/agentflow/flowise.css` is imported. The component's CSS variables are scoped to avoid collisions. -### Publish +### Variables Not Resolving -```bash -# Prerelease — tagged so `npm install @flowiseai/agentflow` won't pick it up -npm publish --tag dev +- **Variable not in picker** — Variables are sourced from upstream nodes. Ensure the source node is connected and upstream of the current node. +- **Incorrect path** — Variable syntax is `{{nodeName.outputKey}}`. Check that the node name and output key match exactly. -# Stable release — gets the `latest` tag -npm publish -``` +### Async Options Not Loading -> The `prepublishOnly` script automatically runs `clean` and `build` before every publish, so stale dist files are never uploaded. +- **Empty dropdowns for models/tools/credentials** — These load from the Flowise API. Verify `apiBaseUrl` and `token` are correct and the server is running. +- **Network errors in console** — Check browser DevTools for failed requests. The API client logs errors to the console. ## Documentation diff --git a/packages/agentflow/TESTS.md b/packages/agentflow/TESTS.md index 4a4fbc0426e..91ad16c87bd 100644 --- a/packages/agentflow/TESTS.md +++ b/packages/agentflow/TESTS.md @@ -34,6 +34,7 @@ Presentational components that are mostly JSX. Only add tests if the component c The Jest config uses file extensions to select the test environment: + | Extension | Environment | When to use | | ----------- | ----------------------- | -------------------------------------------------------------------------- | | `.test.ts` | **node** (no DOM) | Pure logic — utilities, reducers, data transformations | @@ -98,6 +99,8 @@ jest.mock('@/infrastructure/store', () => ({ **CSS/SVG** (`src/__mocks__/styleMock.js`): Empty object export for CSS and SVG imports. +**TipTap** (`src/__mocks__/@tiptap/`): Stubs for `@tiptap/react` and related ESM-only packages that cannot run in Jest's CommonJS environment. The RichTextEditor component is lazy-loaded in production, so these mocks only affect tests that import it directly. + ### Custom Jest Environment `src/__test_utils__/jest-environment-jsdom.js` intercepts `require('canvas')` and returns a mock before jsdom tries to load the native binary. This prevents build failures in environments without native canvas compilation. diff --git a/packages/agentflow/examples/README.md b/packages/agentflow/examples/README.md index 79ec294b83e..a38e790fc94 100644 --- a/packages/agentflow/examples/README.md +++ b/packages/agentflow/examples/README.md @@ -122,14 +122,30 @@ Full integration with a running Flowise instance. Requires `VITE_FLOW_ID` for th ### Additional Examples -| Example | File | Description | -| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------ | -| **Multi-Node Flow** | `MultiNodeFlow.tsx` | Complete translation agent flow with multiple connected nodes showing gradient edges | -| **Dark Mode** | `DarkModeExample.tsx` | Theme toggle demonstrating light/dark mode support | -| **Status Indicators** | `StatusIndicatorsExample.tsx` | Node execution states (running, finished, error, stopped) with animated loader | -| **Custom UI** | `CustomUIExample.tsx` | Custom header and node palette using render props | -| **All Node Types** | `AllNodeTypesExample.tsx` | Visual catalog of all 15 available node types with colors and icons | -| **Filtered Components** | `FilteredComponentsExample.tsx` | Restricting available nodes with preset configurations | +| Example | File | Description | +| ----------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- | +| **Multi-Node Flow** | `MultiNodeFlow.tsx` | Complete translation agent flow with multiple connected nodes showing gradient edges | +| **Dark Mode** | `DarkModeExample.tsx` | Theme toggle demonstrating light/dark mode support | +| **Status Indicators** | `StatusIndicatorsExample.tsx` | Node execution states (running, finished, error, stopped) with animated loader | +| **Custom Node** | `CustomNodeExample.tsx` | Node with self-contained InputParam definitions and show/hide field visibility | +| **Custom UI** | `CustomUIExample.tsx` | Custom header and node palette using render props | +| **All Node Types** | `AllNodeTypesExample.tsx` | Visual catalog of all 15 available node types with colors and icons | +| **Filtered Components** | `FilteredComponentsExample.tsx` | Restricting available nodes with preset configurations | +| **Validation Actions** | `ValidationActionsExample.tsx` | Validation button, error display, and custom `canvasActions` alongside built-in controls | + +### Feature Coverage + +| Feature | Demonstrated In | +| ---------------------------------------------- | ------------------------------ | +| Variable usage (`{{variable}}` syntax, picker) | Custom Node | +| Async options (models, tools, credentials) | Basic Usage (with running API) | +| Flow execution status indicators | Status Indicators | +| Field visibility (show/hide conditions) | Custom Node | +| State management (dirty tracking, callbacks) | Basic Usage | +| Dark/light mode theming | Dark Mode | +| Custom header and palette via render props | Custom UI | +| Restricting node types with `components` prop | Filtered Components | +| Validation actions and custom `canvasActions` | Validation Actions | ## Switching Examples