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 .

# Poetry
poetry env use python3.10
poetry install

# uv
uv sync

# conda
conda env create -f environment.yml
conda activate flowx

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

# Poetry
poetry env use python3.10
poetry install
poetry run pip install -e ../ag_ui_worflow --no-deps

# uv
uv venv --python 3.10
uv pip install --python .venv/bin/python -e ../ag_ui_worflow --no-deps
uv pip install --python .venv/bin/python -e . --no-deps

# conda
conda env create -f environment.yml
conda activate flowx
pip install -e ../ag_ui_worflow --no-deps
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": "<your 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()