aiprobuilder/flowx

FlowX is an MCP server and Python SDK that lets AI agents build workflows. Describe a process in plain language; FlowX generates the workflow graph (workflow.json), the node implementations, and a runnable FastAPI backend. The agent can then inspect, run, and change that workflow in the same conversation, so it becomes a reusable process instead of a one-off answer.

Describe → Generate → Inspect → Run → Refine → Reuse.

Original upstream: AIpRoBuilder/FlowX · Attribution notice · Source provenance and verification. FlowX remains Apache-2.0 licensed; compliant forks and reuse are welcome.

Illustrative walkthrough, not a live recording. Your existing agent remains the assistant; FlowX provides its workflow capability behind the conversation. Messages and per-node cards illustrate what the host UI can render, independent of transport. FlowX does not bundle this interface or automatically generate these card layouts. Generation and execution times are illustrative. See the storyboard and rendering instructions.

Why FlowX

Quickstart in 5 minutes

python3.10 -m venv .venv && source .venv/bin/activate
python -m pip install -e .
cp .env.example .env   # set FLOWX_LLM_PROVIDER, FLOWX_LLM_MODEL, FLOWX_LLM_API_KEY, FLOWX_DEFAULT_WORKSPACE
flowx-mcp

Register flowx-mcp in your MCP client (config example), then ask:

Use flowx to build a workflow that accepts a support ticket, classifies its category, assigns a priority, and drafts a reply.

Other installers (Poetry, uv, conda, a local ag_ui_workflow checkout) are covered in Installation.

The workflow layer behind intelligent UIs

Generative UI shapes the interaction. Generative Workflow shapes the execution. FlowX focuses on the latter: the explicit process an agent can build, run, and change behind a chat, a task panel, or another intelligent interface.

FlowX is model- and UI-agnostic. Connect an MCP-capable agent client, call the Python SDK, or delegate workflow generation over A2A. A custom frontend can consume the generated backend’s events; rendering those events remains the frontend’s responsibility. No dedicated integration with a particular model or intelligent UI is implied.

What ships today

[!NOTE] The primary interactive path is local stdio MCP. MCP and the Python SDK expose the same engine: build or modify workflow.json and requirements, nodes, the main entrypoint, or the whole workflow, then run it as a service. The A2A adapter currently exposes non-streaming workflow building. FlowX is a workflow layer, not a hosted UI product.

Installation

Add the Generative Workflow layer to your agent environment. FlowX requires Python 3.10 or later; one installation includes the shared core, MCP adapter, Python SDK, and A2A adapter.

Install from Git

pip

# Create and activate a virtual environment
python3.10 -m venv .venv
source .venv/bin/activate

# Install FlowX and its runtime dependencies
python -m pip install --upgrade pip
python -m pip install -e .

Install with a local AG-UI workflow checkout

The FlowX agent is vendored under packages/core/flowx_core. Only ag_ui_workflow remains an external workflow-runtime dependency. To use a local checkout instead of its Git dependency, install it first and then install FlowX without dependencies.

pip

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ../ag_ui_worflow --no-deps
python -m pip install -e . --no-deps

For source-checkout execution, FlowX automatically discovers each packages/* component. Set FLOWX_EXTRA_PATHS only when the external ag_ui_workflow source is not installed.

Workflow runtime compatibility

FlowX targets the request-scoped ag_ui_workflow API, verified against upstream revision 3e1e15b (2026-10-13). Contract details for contributors are in docs/RUNTIME.md.

Setup and first workflow

The describe → generate → run → refine loop works through any local MCP-capable agent client.

1. Configure FlowX

cp .env.example .env

Set at least FLOWX_LLM_PROVIDER, FLOWX_LLM_MODEL, FLOWX_LLM_API_KEY, and FLOWX_DEFAULT_WORKSPACE.

FLOWX_LLM_PROVIDER=deepseek
FLOWX_LLM_MODEL=deepseek-flash
FLOWX_LLM_API_KEY=
FLOWX_DEFAULT_WORKSPACE=./.flowx_workspaces

FLOWX_CONFIG_ROOT lets an installed flowx-mcp resolve a .env file outside the repository checkout. FLOWX_EXTRA_PATHS can point at a local ag_ui_workflow source when it is not installed into the current environment.

2. Start the server

# Default local stdio entry point
flowx-mcp

# Verbose logging
flowx-mcp --verbose

# Source-checkout entry point
python3.10 run_server.py

For interactive terminal use, prefix with poetry run or uv run if the environment is not activated. For MCP client configuration, use the absolute executable path and arguments described below; an MCP host may not inherit your shell’s PATH.

3. Register FlowX in an MCP client

{
  "mcpServers": {
    "flowx": {
      "command": "flowx-mcp",
      "env": {
        "FLOWX_LLM_PROVIDER": "deepseek",
        "FLOWX_LLM_MODEL": "deepseek-flash",
        "FLOWX_LLM_API_KEY": "",
        "FLOWX_DEFAULT_WORKSPACE": "/Users/user/Desktop/codes/flowx_workspaces"
      }
    }
  }
}

Python SDK

Embed workflow building directly in a Python agent or the backend behind your own intelligent UI, without an MCP transport. A complete walkthrough is in examples/sdk_quickstart.py.

from flowx_sdk import FlowXClient

with FlowXClient(workspace="./workflows") as flowx:
    created = flowx.build_workflow_json(
        "Build a workflow that categorizes and prioritizes support tickets.",
    ).raise_for_failure()                                  # workflow.json + requirements
    workflow_id = created.workflow_id
    flowx.build_nodes(workflow_id).raise_for_failure()     # all nodes, or {step_id: amendment}
    flowx.build_main_entrypoint(workflow_id).raise_for_failure()
    flowx.build_workflow("Also return a summary.", workflow_id=workflow_id)  # whole engine
    print(flowx.run_service(workflow_id))                  # run / rerun as a service

Each build call returns an AgentResult with per-stage outcomes, unresolved errors, logs and artifact paths; stage failures are reported there rather than raised.

Pass repair_input_callback=... to build_nodes, build_workflow, or evolve to guide a node’s amendment after its test fails. The callback receives a NodeRepairInput with the node step id, attempt number, pytest log and test result, and returns guidance to combine with the log, "skip" to skip the amendment, or "" to use the log alone. A runnable walkthrough is in examples/sdk_guided_repair.py.

To change an existing workflow, choose what to evolve with evolve(workflow_id, command, target=...). list_nodes returns each node’s step id and node id to use as a target; without a target the engine decides what the command refers to. A runnable walkthrough is in examples/sdk_evolve.py.

from flowx_sdk import WORKFLOW_TARGET

nodes = flowx.list_nodes(workflow_id)   # [{"step_id": ..., "node_id": ..., "version": ...}]
flowx.evolve(workflow_id, "Add a language-detection step.", target=WORKFLOW_TARGET)  # the workflow
flowx.evolve(workflow_id, "Validate empty input.", target=nodes[0]["step_id"])       # one node (step id or node id)
flowx.evolve(workflow_id, "Also return a one-line summary.")                         # engine judges

A2A server

Let another agent delegate workflow generation to FlowX through the non-streaming Agent2Agent endpoint:

flowx-a2a --host 127.0.0.1 --port 8001

It serves an A2A agent card at /.well-known/agent-card.json and JSON-RPC at /a2a (also /). Supported methods are message/send, tasks/get, and tasks/cancel. Send an A2A text message to build a workflow; add metadata.workflowId to modify an existing one. The task is completed when every stage succeeded and otherwise failed; either way it carries the result, including the generated artifact paths.

4. Create a workflow from chat

Start with the same support-ticket intent shown in the walkthrough:

Use flowx to build a workflow.

Build a workflow that accepts a support ticket, classifies its category,
assigns a priority, and drafts a reply. Name the reply node draft_reply.
Return the category, priority, and draft reply as structured output.

5. Run, refine, and reuse

Follow up in the same conversation:

Run the workflow as a service.

Update the draft_reply node: for urgent tickets, include an escalation note.
Then rerun the service.

The client uses build_workflow (or build_workflow_json, build_nodes and build_main_entrypoint one stage at a time) to create and refine the workflow, and run_service to start or restart it. evolve_workflow changes an existing workflow or one node (target="workflow", a node step id or node id from list_nodes, or no target to let FlowX decide). list_workflows, list_nodes and get_workflow show the workflow ids, node ids and artifact locations. Exact step IDs come from the generated workflow—not from a fixed demo schema.

This is the distinction: the agent does not only answer the ticket. It builds and evolves the process for handling the next one.

Architecture

The Generative Workflow layer has one shared core and three agent-facing interfaces: flowx_core plans, generates, and audits artifacts; flowx_mcp, flowx_sdk, and flowx_a2a make those capabilities available to different agent hosts. The generated runtime sits beneath that layer; the intelligent UI sits above it.

flowchart TB
  UI["Intelligent UI / agent host"] --> MCP["Local MCP: build, modify, run"]
  UI --> SDK["Python SDK: build, modify, run"]
  PEER["Peer agent"] --> A2A["A2A: delegate generation"]
  MCP --> CORE["FlowX · Generative Workflow layer"]
  SDK --> CORE
  A2A --> CORE
  CORE --> FILES["Workflow graph + node code + backend"]
  FILES --> RUNTIME["FastAPI + ag_ui_workflow runtime"]
  MCP -->|"run / rerun as a service"| RUNTIME
  RUNTIME -.->|"AG-UI SSE to a custom frontend"| UI
  MCP -->|"follow-up changes"| CORE

Runtime topology

• flowx_mcp.server exposes the tool surface over stdio through FastMCP.
• flowx_core.AgentBuilder creates and updates workflow artifacts from prompts.
• flowx_sdk.FlowXClient and flowx_a2a call the same agent core without routing through MCP.
• The generated main.py runs as a managed FastAPI subprocess per workflow.
• run_service starts or restarts the generated main.py; clients reach it over HTTP and AG-UI SSE.

From intent to workflow artifacts

Workflow compilation is the mechanism behind the Generative Workflow layer. Planning and code generation turn intent into artifacts; audits provide feedback during generation and runtime checks. The artifact flow below is mirrored from assets/architecture.mmd.

flowchart LR
    A[Raw requirement] --> B[requirement_analysis.md]
    B --> C[workflow.json]
    C --> D[node_docs/*.md]
    D --> E[nodes/*.py]
    E --> F[main.py]

    C --> G[Graph audit]
    E --> H[Node audit]
    F --> I[Entrypoint audit]
    F --> J[Runtime log audit]

    G -->|feedback| C
    H -->|feedback| E
    I -->|feedback| F
    J -->|feedback| E

Tool surface

These MCP tools let the host agent operate the workflow layer from the same conversation. UI rendering is deliberately left to the host.

Example workflows

Different intents, the same workflow layer: analysis, file transformation, and information collection can each become an executable process. Paste the prompts below into an MCP client connected to your local flowx server, then inspect, run, and refine the generated workflow. The screenshots are example outputs, not a bundled FlowX UI; external data sources may require their own access and dependencies.

1. stock_pressure

2. stock_distribution

3. picture_to_svg

4. policy_scrawler

5. start-up-hiring

Contributing

Issues and pull requests are welcome. If FlowX is useful to you, star the repo, share a workflow you generated, or open an issue describing an intent you want turned into a workflow. When you redistribute or modify FlowX, keep the LICENSE and NOTICE attribution (see docs/PROVENANCE.md).

Contact

Interested in building the Generative Workflow layer for AI Agents—or connecting it to an intelligent UI? Get in touch at [email protected].

WeChat QR code:

Back to top ↑