Agent Flow Designer (AFD): A QwenPaw Visual Agent Workflow Orchestration Plugin Based on AntV X6

Agent Flow Designer - Visual Agent Workflow Designer. Agent Flow Designer is a visual agent workflow orchestration plugin for the QwenPaw platform, supporting the rapid construction, publishing, deployment, and management of multi-node collaborative Agent workflows through drag-and-drop.

--- Table of Contents [1. Plugin Overview] [2. Core Capabilities] [3. Supported Node Types] [4. Technical Architecture] [5. Installation] [6. Usage] [7. Backend API Overview] [8. Persistent Storage] [9. Project Structure] [10. Build and Packaging] [11. FAQ] [12. Future Evolution] --- 1. Plugin Overview Agent Flow Designer (AFD for short) is a visual agent workflow orchestration plugin for the QwenPaw platform. Basic Information | Attribute | Value | |------|---| | Plugin ID | agent-flow-designer | | Current Version | v2.2.2 | | Type | PawApp application plugin (app) | | Compatibility | QwenPaw / QzAgent ≥ 2.0.0 | | Icon | 🧩 | | Category | automation | Core Positioning Simplified workflow designer: lightweight, focused on core functionality, suitable for rapid prototyping and simple orchestration scenarios. Cornerstone version: the current version is a solid starting point for secondary development, with continuous iteration in the future. Developers are sincerely invited to participate and jointly prosper the QwenPaw ecosystem. --- 2. Core Capabilities 1. Visual Workflow Orchestration

| Capability | Description | |------|------| | Drag-and-drop canvas | Based on the AntV X6 graph editing engine, supporting node dragging, four-direction connections, automatic snapping, and alignment guides | | Multiple node types | 6 node types: Start, Agent, Tool, Router Decision, End, Ask | | Conditional branching | Router Decision nodes support three routing modes: rule matching, LLM intelligent routing, and hybrid mode | | Canvas interaction | Supports zooming, fit-to-view, minimap preview, property panel collapse, box selection/multi-selection, copy-paste, and one-click automatic layout (entry in the "⋯" menu) | | Execution-state visualization | Only the edge currently executing has a blue flowing light; traversed paths remain light blue; untraversed edges remain gray; the determination criteria are consistent with the engine dispatch rules (see "Execution Semantics") | | Undo/Redo | Supports Ctrl+Z / Ctrl+Shift+Z, with a history stack limit of 50 steps | | Auto-save | 3-second debounce auto-save, dirty flag + beforeunload protection | | On-demand display of connection points | The four directional ports (top, bottom, left, right) are transparent by default and fade in only when the mouse moves over a node or a connection is being dragged, avoiding a dozen dots covering the canvas | 2. Versioned Publishing (Configuration Snapshots) Each publish generates an immutable configuration snapshot, retaining the complete version history. Supports version-based tracing, comparison, and one-click rollback. The editing state and published state are fully isolated; the stable online version is unaffected by draft modifications. 3. Deployment and External Services One-click workflow deployment, automatically generating external API endpoints. Execution after deployment is fully isolated: it uses the deployed version snapshot, and edits in the editing state do not affect the online service. Supports one-click takedown, allowing flexible control of the service lifecycle. 4. Unified External Execution Interface Provides a unified /run execution interface, supporting multi-language calls such as cURL, JavaScript, and Python. Automatically detects deployment status and refuses execution if not deployed, ensuring service stability. 5. Design-time Validation and Run Cancellation The "Validate" button calls POST /workflows/{id}/validate, listing in advance problems that can only be exposed at runtime (dangling edges, unreachable nodes, references to nonexistent/non-upstream variables, invalid fields in the Start node, delta missing baseline, onError=branch without an error out-edge connected, cycles); clicking an item locates the node. Validation is mandatory before publishing and deployment; if errors exist, a 422 is returned and the issue list is displayed on the frontend, so a non-functional version snapshot will not be produced. "Stop" calls POST /workflows/{id}/executions/{executionid}/cancel: the cancellation flag is checked between nodes; the currently executing node will finish (in-progress LLM requests are not cut off), all subsequent nodes are recorded as skipped, and the execution result is cancelled rather than "completed". Ownership isolation: userid is bound to the logged-in principal (getscopedctx); list/read-write/execute/publish/deploy/cancel/resume are all verified by owner, and unauthorized access returns 403. Workflows created before the change and lacking an owner field remain shared; the upgrade will not make the existing workflow library disappear. --- 3. Supported Node Types

| Node | Type Identifier | Description | Typical Use | |------|---------|------|---------| | Start | start | Workflow entry node, receives user input | Serves as the starting point of the workflow | | Agent | agent | Invokes a real LLM/Agent, supports configuring Agent ID and additional prompts | Implements core capabilities such as intelligent dialogue and reasoning | | Tool | tool | Tool invocation node, records parameters and context | Integrates external tools/APIs (placeholder implementation) | | Router | router | Routes to different downstream nodes based on conditional branches | Implements conditional judgment and process branching | | End | end | Workflow endpoint, aggregates upstream outputs as the final result | Serves as the termination point of the workflow | | Ask | ask | Initiates a query to the user and collects input | Interactive human-machine dialogue (HITL, in development) | Operators supported by the router node Basic comparison: eq, ne, gt, lt, ge, le Text matching: contains, startswith, endswith, regex Delta/Diff operations: deltagt, deltalt, deltage, deltale, changerategt, changeratelt, textdiffratiogt, textdiffcontains ⚠ Delta/Diff operations must explicitly provide a baseline: a fixed reference value (manually enter a number) or a referenced baseline node (select the output field of an upstream node). The engine runs each node only once per single execution; there is no readable history of "previous/initial value"; when no baseline is configured, the condition will not match, and the reason will be reported in the execution trace (early versions silently calculated as 0). Execution semantics Fan-in: a merge node waits for all incoming edges to arrive before executing once; it will not be triggered early just because one branch finishes first. Branch isolation: a branch not matched by the router is recorded entirely as skipped, and its output will not enter the prompts of downstream nodes. Failure handling: Agent / Tool nodes can be configured with onError abort (default): on failure, stop immediately, all downstream nodes are recorded as skipped, and the result is reported as execution failure; branch: continue only along the "error" outgoing edge where sourceHandle === "error" (draw a line from the node's red error port on the canvas); if no error outgoing edge is connected, it is equivalent to abort; continue: ignore the failure and continue executing downstream. Variable reference: {{nodeID.field}}. When the reference cannot be resolved (node not executed / field does not exist), report "undefined", no longer conflating it with "variable value is empty". Determination of canvas flow animation: a connection flows only when "the source node has actually sent out the token" and "the target node is executing". Endpoints that are skipped, branches not matched by the router, and ordinary outgoing edges of failed nodes (unless onError: continue) do not count as traversed; the "error" outgoing edge counts only when onError: branch and the source node fails. Traversed lines remain as light blue solid lines, and all become static after execution ends (wfdone). Loops: the engine first uses DFS to mark back edges and excludes them from the in-degree barrier, then traverses per single execution—therefore back edges can exist in the graph (no deadlock), but back edges will not be triggered again. For true iteration, please wait for the loop container in Phase B. Prompt sources for Agent nodes Priority: promptTemplate → inputs binding ([{name, ref}]) → upstream output on the matched path + current input. No longer unconditionally concatenating all historical outputs into the prompt. --- 4. Technical Architecture | Layer | Technology Choice | Version | |------|----------|------| | Frontend framework | React + TypeScript | React 18.3 | | Build tool | Vite | 5.4 | | Graph editing engine | AntV X6 + @antv/x6-react-shape | 3.1.8 | | Backend framework | FastAPI (Python) | — | | Plugin framework | PawApp (qwenpaw / qzagent) | ≥2.0.0 | | Communication protocol | REST API / HTTP | — | | Markdown rendering | react-markdown + remark-gfm + react-syntax-highlighter | — | | Persistence | JSON files (atomic writes) | — |

--- 5. Installation Method Option 1: Command-line installation (recommended) The old platform command is qwenpaw plugin install plugins/apps/agent-flow-designer Option 2: Console graphical installation Open the qzagent / qwenpaw Web console Go to the "Plugin Management" page Click "Install Plugin" Select the plugins/apps/agent-flow-designer directory Wait for installation to complete --- 6. Usage Starting the plugin After installation is complete: Open the qzagent / qwenpaw Web console Find Agent Flow Designer in the left sidebar or "App Center" (icon: 🧩) Click to enter the plugin page Basic operation flow Create a workflow: click "+ New Workflow", enter a name, and enter the editor Orchestrate the workflow: Drag nodes from the left node panel onto the canvas Nodes have connection points on all four sides: one inlet and one outlet each on the top, bottom, left, and right; horizontally arranged flows can be connected directly "right side → left side"; the inlet/outlet positions of connections are saved together with the workflow. Router branches and "error" outgoing edges remain fixed on the bottom edge, where there is room to display branch names Connection points are hidden by default and fade in only when the mouse moves over a node (or when holding a node to drag a line), avoiding a dozen dots spread across the canvas at once; hiding only affects appearance, and the transparent hit areas can still be hit, so connections are unaffected. Inlets are gray, outlets are the node color Click a node to select it, and configure parameters in the property panel on the right Preview and debug: enter an instruction in the "Preview and Debug" panel on the right and press Enter to send During execution, only the connection currently running has a blue flow animation (white bright head + light blue trailing tail, moving along the data flow direction); connections already traversed remain as light blue solid lines, and those not yet reached remain gray. Routing branches, "error" outgoing edges, and onError policies are all determined according to the engine's actual dispatch rules; the entire graph will not light up at once. Publishing and deployment: Click the "Publish" button to snapshot the current workflow as an immutable version. Click the "Deploy" button to make the workflow callable through an external API. After deployment, it can be called through the external endpoint POST /workflows/{id}/run. --- 7. Backend API Overview Workflow CRUD | Method | Path | Description | |------|------|------| | POST | /workflows | Create a workflow | | GET | /workflows/{id} | Get a workflow | | PUT | /workflows/{id} | Update a workflow | | DELETE | /workflows/{id} | Delete a workflow | | GET | /workflows | List all workflows | Execution API | Method | Path | Description | |------|------|------| | POST | /workflows/{id}/execute | Execute a workflow (development mode, supports preview) | | POST | /workflows/{id}/run | External invocation (deployed workflows only) | | POST | /workflows/{id}/execute/resume | Resume a HITL-paused execution | | POST | /workflows/{id}/executions/{executionid}/cancel | Cancel a running execution (takes effect between nodes) | Validation API | Method | Path | Description | |------|------|------| | POST | /workflows/{id}/validate | Statically validate the graph structure and variable references; the request body may include workflow to validate unsaved canvas content | Version Management API | Method | Path | Description | |------|------|------| | POST | /workflows/{id}/publish | Publish a version snapshot (returns 422 if validation fails) | | GET | /workflows/{id}/versions | List all versions | | POST | /workflows/{id}/rollback/{versionid} | Roll back to a specified version | | GET | /workflows/{id}/published | Get the latest published version | Deployment Management API | Method | Path | Description | |------|------|------| | POST | /workflows/{id}/deploy | Deploy a workflow | | POST | /workflows/{id}/undeploy | Undeploy | | GET | /workflows/{id}/deployed | Get the deployed version | --- 8. Persistent Storage Storage Path Workflow data is uniformly stored in the main application data directory of qzagent / qwenpaw: | Environment | Data File Path | |------|-------------| | QZAGENTHOME set | /data/agent-flow-designer/workflows.json | | Not set (default) | /.qzagent/data/agent-flow-designer/workflows.json | Storage Features | Feature | Implementation | |------|----------| | Write method | Atomic write (tempfile.mkstemp + os.replace), ensuring write integrity | | Concurrency safety | asyncio.Lock() coroutine-level lock protects read and write operations | | Data migration | Automatically and losslessly migrates from the old path on first access | | Old data backup | After migration, the original file is renamed to .migrated as a backup | Data Safety Notes Plugin uninstall/reinstall: data is retained (stored outside the plugin directory) Plugin version update: data is retained and automatically compatible Platform upgrade: data is retained (unless /.qzagent is manually cleaned up) --- 9. Project Structure

--- 10. Build and Packaging The distribution zip is generated by package.py in the plugin directory. It must be executed inside the plugin directory (the script uses relative paths):

The script proceeds in three steps: Build the frontend as needed: compare the modification times of ui/dist with ui/src, ui/package.json, vite.config.ts, and other files; when the build output is missing or older than the source code, automatically run npm run build under ui/ (Node.js and npm must be in PATH). A build failure interrupts packaging, so it will not produce a package containing an old frontend. Version number auto-increment: add 1 to the last digit of the version in plugin.json and write it back (e.g., 2.0.10 → 2.0.11), so each run produces a new package and does not overwrite the previous distribution. Collect and compress: write agent-flow-designer .zip, containing only the files needed to run — | Packaged Content | Description | |----------|------| | plugin.json | Plugin declaration (including the auto-incremented version number) | | README.md | This documentation, distributed with the package | | backend/main.py | Backend entry point | | backend/engine/.py | Execution engine, automatically discovered by directory, so newly added modules are not missed | | ui/plugin-entry.js | PawApp frontend route registration script | | ui/dist/index.html + ui/dist/assets/ | Frontend build output | ui/src, nodemodules, package.py itself, and various design documents are not included in the package. How to install after obtaining the zip: upload and install it in "Plugin Management" in the console, or extract it to plugins/apps/agent-flow-designer and then run qzagent plugin install plugins/apps/agent-flow-designer. --- 11. FAQ Q: How does it coexist with the existing orchestrator plugin? A: This plugin uses an independent plugin ID (agent-flow-designer) and is completely isolated from the orchestrator plugin, so they can be installed and used at the same time. Q: Where is workflow data stored? A: Workflow data is persistently stored in the data/agent-flow-designer/workflows.json file under the qzagent data directory (data in the old plugin directory is automatically migrated). It uses an atomic write (tempfile + os.replace) mechanism to ensure data safety. Data will not be lost after restarting qzagent. Q: Which node types are supported? A: Currently 6 node types are supported: Start, Agent, Tool, Routing Decision, End, and Ask. Q: Getting a Rollup failed to resolve import "tslib" error during build? A: tslib has been declared as an explicit dependency. If the problem persists, run: Q: I ran python package.py, but the frontend in the zip is still the old one? A: The script only rebuilds when ui/dist is older than ui/src (or the build output is missing). If dist was modified manually or the build was interrupted, delete ui/dist first and run it again to force a rebuild. Q: Getting a [Build FAILED] npm command not found error during packaging? A: This means Node.js cannot be found in PATH. On Windows, the script already invokes npm.cmd (CreateProcess does not resolve bare npm to .cmd), so if this step still fails, Node.js is not installed or not added to PATH. --- 12. Future Evolution The current version is only a foundation, and there is still broad room for improvement in the future. We hope that through this project, we can provide everyone with a solid starting point for secondary development, and we sincerely invite developers to participate together.

Next steps (Phase B: execution semantics): Parallel fan-out: multiple ready nodes at the same layer execute concurrently, throttled by the workflow-level maxconcurrency Loop containers: grouped containers + maxiterations + back-edge retriggering (currently back edges are only marked and not executed again) Execution history persistence: executionruns persisted, supporting history viewing, replay, token cost statistics, and delta baselines across runs Node-level timeout and retry: currently there is only a fixed timeout on the Agent invocation side, lacking per-node configurable timeout/backoff retry Engine callback hooks: before/after node, for external plugins to insert short-circuit logic and instrumentation Further ahead (Phase C: variables and node ecosystem): Frontend NodeTypeDef registry + property panel rendered according to schema, so adding new node types no longer requires changes in multiple places Unified variable reference model (topological reachability validation, variable chip interpolation, type/default value/required) LLM node, Code node (subprocess/container sandbox + timeout, without using eval()), variable/condition node Tool node connected to real implementations; credentials for HTTP request nodes always go through the host secret store and are not written in plaintext into workflows.json Structured output (outputschema → parsing + validation + retry on failure) SQLite storage migration, plugin nodes --- License MIT License