FlowX

FlowX es un servidor MCP y SDK de Python que permite a los agentes de IA crear flujos de trabajo. Describe un proceso en lenguaje natural; FlowX genera el grafo del flujo de trabajo (workflow.json), las implementaciones de los nodos y un backend FastAPI ejecutable. El agente puede entonces inspeccionar, ejecutar y modificar ese flujo de trabajo en la misma conversación, convirtiéndolo en un proceso reutilizable en lugar de una respuesta puntual.

Describe → Genera → Inspecciona → Ejecuta → Refina → Reutiliza.

Proyecto original ascendente: AIpRoBuilder/FlowX · Aviso de atribución · Procedencia y verificación de la fuente. FlowX mantiene la licencia Apache-2.0; se aceptan bifurcaciones y reutilizaciones compatibles.

Recorrido ilustrativo, no una grabación en vivo. Tu agente existente sigue siendo el asistente; FlowX proporciona su capacidad de flujo de trabajo detrás de la conversación. Los mensajes y las tarjetas por nodo ilustran lo que la interfaz del host puede mostrar, independientemente del transporte. FlowX no incluye esta interfaz ni genera automáticamente estos diseños de tarjetas. Los tiempos de generación y ejecución son ilustrativos. Consulta las instrucciones de guion gráfico y renderizado.

Por qué FlowX

Inicio rápido en 5 minutos

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

Registra flowx-mcp en tu cliente MCP (ejemplo de configuración) y luego pregunta:

Usa flowx para crear un flujo de trabajo que acepte un ticket de soporte, clasifique su categoría, asigne una prioridad y redacte una respuesta.

Otros instaladores (Poetry, uv, conda, un checkout local de ag_ui_workflow) se cubren en Instalación.

La capa de flujo de trabajo detrás de las interfaces inteligentes

La interfaz generativa da forma a la interacción. El flujo de trabajo generativo da forma a la ejecución. FlowX se centra en esto último: el proceso explícito que un agente puede construir, ejecutar y cambiar detrás de un chat, un panel de tareas u otra interfaz inteligente.

FlowX es independiente del modelo y de la interfaz. Conecta un cliente agente compatible con MCP, llama al SDK de Python o delega la generación de flujos de trabajo a través de A2A. Un frontend personalizado puede consumir los eventos del backend generado; renderizar esos eventos sigue siendo responsabilidad del frontend. No se implica una integración dedicada con un modelo o interfaz inteligente en particular.

Qué incluye hoy

[!NOTA] La ruta interactiva principal es MCP stdio local. MCP y el SDK de Python exponen el mismo motor: construir o modificar workflow.json y los requisitos, nodos, punto de entrada principal o todo el flujo de trabajo, y luego ejecutarlo como servicio. El adaptador A2A actualmente expone la construcción de flujos de trabajo sin transmisión. FlowX es una capa de flujo de trabajo, no un producto de interfaz alojado.

Instalación

Añade la capa de flujo de trabajo generativo a tu entorno de agente. FlowX requiere Python 3.10 o posterior; una instalación incluye el núcleo compartido, el adaptador MCP, el SDK de Python y el adaptador A2A.

Instalar desde 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

Instalar con un checkout local de AG-UI workflow

El agente FlowX está integrado bajo packages/core/flowx_core. Solo ag_ui_workflow sigue siendo una dependencia externa del entorno de ejecución del flujo de trabajo. Para usar un checkout local en lugar de su dependencia Git, instálalo primero y luego instala FlowX sin dependencias.

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

Para la ejecución desde checkout de fuente, FlowX descubre automáticamente cada componente packages/*. Establece FLOWX_EXTRA_PATHS solo cuando la fuente externa de ag_ui_workflow no esté instalada.

Compatibilidad del entorno de ejecución del flujo de trabajo

FlowX apunta a la API ag_ui_workflow con ámbito de solicitud, verificada contra la revisión ascendente 3e1e15b (2026-10-13). Los detalles del contrato para colaboradores están en docs/RUNTIME.md.

Configuración y primer flujo de trabajo

El bucle describir → generar → ejecutar → refinar funciona a través de cualquier cliente agente local compatible con MCP.

1. Configura FlowX

cp .env.example .env

Establece al menos FLOWX_LLM_PROVIDER, FLOWX_LLM_MODEL, FLOWX_LLM_API_KEY y FLOWX_DEFAULT_WORKSPACE.

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

FLOWX_CONFIG_ROOT permite que un flowx-mcp instalado resuelva un archivo .env fuera del checkout del repositorio. FLOWX_EXTRA_PATHS puede apuntar a una fuente local de ag_ui_workflow cuando no esté instalada en el entorno actual.

2. Inicia el servidor

# Default local stdio entry point
flowx-mcp

# Verbose logging
flowx-mcp --verbose

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

Para uso interactivo en terminal, prefija con poetry run o uv run si el entorno no está activado. Para la configuración del cliente MCP, usa la ruta absoluta del ejecutable y los argumentos descritos a continuación; un host MCP puede no heredar tu PATH de shell.

3. Registra FlowX en un cliente MCP

{
  "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"
      }
    }
  }
}

SDK de Python

Incorpora la construcción de flujos de trabajo directamente en un agente Python o en el backend detrás de tu propia interfaz inteligente, sin transporte MCP. Un recorrido completo está en 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

Cada llamada de construcción devuelve un AgentResult con resultados por etapa, errores no resueltos, registros y rutas de artefactos; los fallos de etapa se informan allí en lugar de lanzarse.

Para cambiar un flujo de trabajo existente, elige qué evolucionar con evolve(workflow_id, command, target=...). list_nodes devuelve el id de paso y el id de nodo de cada nodo para usar como objetivo; sin un target, el motor decide a qué se refiere el comando. Un recorrido ejecutable está en 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

Servidor A2A

Permite que otro agente delegue la generación de flujos de trabajo a FlowX a través del endpoint Agent2Agent sin transmisión:

flowx-a2a --host 127.0.0.1 --port 8001

Sirve una tarjeta de agente A2A en /.well-known/agent-card.json y JSON-RPC en /a2a (también /). Los métodos admitidos son message/send, tasks/get y tasks/cancel. Envía un mensaje de texto A2A para construir un flujo de trabajo; añade metadata.workflowId para modificar uno existente. La tarea es completed cuando todas las etapas tuvieron éxito y, de lo contrario, failed; en cualquier caso, lleva el resultado, incluidas las rutas de artefactos generados.

4. Crea un flujo de trabajo desde el chat

Comienza con la misma intención de ticket de soporte que se muestra en el recorrido:

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. Ejecuta, refina y reutiliza

Continúa en la misma conversación:

Run the workflow as a service.

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

El cliente usa build_workflow (o build_workflow_json, build_nodes y build_main_entrypoint una etapa a la vez) para crear y refinar el flujo de trabajo, y run_service para iniciarlo o reiniciarlo. evolve_workflow cambia un flujo de trabajo existente o un nodo (target="workflow", un id de paso de nodo o id de nodo de list_nodes, o sin objetivo para que FlowX decida). list_workflows, list_nodes y get_workflow muestran los ids de flujo de trabajo, ids de nodo y ubicaciones de artefactos. Los ids de paso exactos provienen del flujo de trabajo generado, no de un esquema de demostración fijo.

Esta es la distinción: el agente no solo responde al ticket. Construye y evoluciona el proceso para manejar el siguiente.

Arquitectura

La capa de flujo de trabajo generativo tiene un núcleo compartido y tres interfaces orientadas al agente: flowx_core planifica, genera y audita artefactos; flowx_mcp, flowx_sdk y flowx_a2a hacen que esas capacidades estén disponibles para diferentes hosts de agentes. El entorno de ejecución generado se encuentra debajo de esa capa; la interfaz inteligente se encuentra encima.

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

Topología del entorno de ejecución

• flowx_mcp.server expone la superficie de herramientas a través de stdio usando FastMCP.
• flowx_core.AgentBuilder crea y actualiza artefactos de flujo de trabajo a partir de mensajes.
• flowx_sdk.FlowXClient y flowx_a2a llaman al mismo núcleo de agente sin pasar por MCP.
• El main.py generado se ejecuta como un subproceso FastAPI gestionado por flujo de trabajo.
• run_service inicia o reinicia el main.py generado; los clientes lo alcanzan a través de HTTP y AG-UI SSE.

De la intención a los artefactos de flujo de trabajo

La compilación del flujo de trabajo es el mecanismo detrás de la capa de flujo de trabajo generativo. La planificación y la generación de código convierten la intención en artefactos; las auditorías proporcionan retroalimentación durante la generación y comprobaciones en tiempo de ejecución. El flujo de artefactos a continuación se refleja desde 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

Superficie de herramientas

Estas herramientas MCP permiten que el agente host opere la capa de flujo de trabajo desde la misma conversación. El renderizado de la interfaz se deja deliberadamente al host.

Ejemplos de workflows

Diferentes intenciones, la misma capa de workflow: análisis, transformación de archivos y recopilación de información pueden convertirse cada uno en un proceso ejecutable. Pega los prompts a continuación en un cliente MCP conectado a tu servidor local flowx, luego inspecciona, ejecuta y refina el workflow generado. Las capturas de pantalla son ejemplos de salida, no una UI de FlowX incluida; las fuentes de datos externas pueden requerir su propio acceso y dependencias.

1. stock_pressure

Use flowx to create a workflow named stock_pressure.

Build a workflow based on the following theory. Using the most recent n trading days, specified by the user, estimate the likely future distribution price levels for market makers in a user-specified stock and display them on a chart.

Market Maker Distribution Pressure Peak Forecasting Model

I. Model Goal

Use historical trading data, chip distribution, market-maker cost basis, and historical highs to identify future price regions that may form distribution pressure.

Core assumptions:
1. Market makers accumulate positions at low prices after a sharp decline.
2. The accumulation phase forms the market maker's average cost zone.
3. During subsequent rallies, market makers probe overhead sell pressure.
4. Historical high-volume trading zones and previous highs create dynamic resistance.
5. Distribution pressure points are determined by multiple factors together.

II. Input Data

Daily market data:
Date: date
Open: open price
High: high price
Low: low price
Close: close price
Volume: trading volume

III. Chip Distribution Model

Divide the price range into N price buckets.

For each price interval p:
C(p)=Σ Volume(t)

Where:
C(p) represents the cumulative traded chips in that price region.

Peak trading concentration:
P_peak = argmax C(p)

This represents the price zone with the highest cost concentration in the market.

IV. Estimating the Market-Maker Accumulation Cost

Select the accumulation phase using these conditions:
1. The stock experienced a sharp decline.
2. Trading volume expanded significantly.
3. Price entered a sideways consolidation range.

Average market-maker cost:
C_dealer = Σ(P_t × V_t) / ΣV_t

Where:
P_t: transaction price
V_t: volume

This yields the market maker's primary holding cost.

V. Historical Pressure Peak Calculation

Define the pressure score:
Pressure(p)= w1C(p) + w2High_Test(p) + w3Profit(p) + w4Gain(p)

Where:
1. Trading-density pressure C(p)
Represents the historical trading-chip volume accumulated in that price zone.

2. Historical-high pressure High_Test(p)
Measure:
- Whether historical highs occurred at this level
- Whether rallies failed multiple times near this level
- Whether the region formed a top structure

3. Profitable-position pressure Profit(p)
Calculate:
Profit(p)=ΣC(x), x<p

This indicates how many chips below the current price are already in profit.

The more profitable chips there are,
the greater the potential selling pressure.

4. Market-maker gain pressure Gain(p)
Gain(p)= (p-C_dealer)/C_dealer

This represents the market maker's theoretical return at price p.

VI. Pressure Peak Search Algorithm

Step 1:
Build a price-volume matrix:
price_bins = divide(min_price,max_price,N)

Step 2:
Aggregate:
volume_profile[p]

Step 3:
Compute the pressure score for each price level.

Step 4:
Sort:
The highest-scoring levels are the primary pressure peaks.

Output:
Pressure_1
Pressure_2
Pressure_3

Representing:
Primary pressure zone
Secondary pressure zone
Tertiary pressure zone

VII. Dynamic Probe Validation

Observe the market-maker's probing behavior during an upward move:

Case A:
Price rises while volume declines.
Meaning: overhead resistance is relatively weak.

Case B:
Price rises, volume expands sharply, a long upper shadow appears, and price then falls back.
Meaning: this price region contains substantial sell pressure.

Define:
P_pressure = the current failed test price

VIII. Integrated Distribution Price Model

Final prediction:
P_exit = argmax Pressure(p)

That is:
the price corresponding to the maximum pressure score.

Practical estimate:
P_exit ≈ market-maker cost × (1+r)

And:
it should also be close to a historical trading concentration peak.

Where:
r: target market-maker return.

IX. Python Implementation Outline

Input:
OHLCV DataFrame

Compute:
1. Compute volume distribution
2. Estimate market-maker cost
3. Detect historical highs
4. Compute the proportion of profitable chips
5. Compute pressure scores
6. Output pressure peaks

Pseudocode:
for price in price_bins:
    score = (
        w1 * volume_density(price)
        + w2 * historical_high(price)
        + w3 * profit_ratio(price)
        + w4 * dealer_gain(price)
    )

rank(score)

return top_pressure_prices

X. Final Interpretation

The future price at which market makers may distribute is not simply the historical high.

2. stock_distribution

Use flowx to create a workflow named stock_distribution.

Build a workflow based on the following theory that estimates large-holder and retail chip distribution across current and historical price levels and visualizes it.

## Role
You are a quantitative researcher responsible for building an implicit large-holder versus retail-holder chip-state model from 1-hour OHLCV data, and for identifying accumulation, distribution, and potential price pressure peaks.

## Important Principles
1. With only price and volume, you cannot directly observe the true holdings of large and small accounts.
2. large_ratio / small_ratio are latent-state estimates of the model, not real account holdings.
3. "Price up = large holders sell to small holders, price down = small holders sell to large holders" is a hypothesis to test, not a fact.
4. All real-time features may use only current and past data; no future leakage is allowed.
5. Output probabilities and confidence levels, and do not present model results as certainty.

## Input
The CSV must contain at least:
datetime, open, high, low, close, volume

## Core State
H_t: estimated large-holder chip ratio
L_t: estimated retail-holder chip ratio
H_t + L_t = 1
D_t = H_t - L_t = 2H_t - 1

R_t = (P_t-P_{t-1})/P_{t-1}
V*_t = V_t / EMA(V_t)

## State Transition
Simplest calibratable model:

ΔH_t = -alpha * tanh(R_t / sigma_R) * V*_t

Constrain H_t ∈ [h_min, h_max].

Interpretation:
- High-volume upward moves push H lower, implying implicit dispersion from large holders to small holders.
- High-volume downward moves push H higher, implying implicit concentration from small holders to large holders.
- Small price moves or normal volume produce smaller state changes.

3. picture_to_svg

Use flowx to create a workflow named picture_to_svg.

Create a workflow that uploads a WeChat QR code image, automatically removes personal name information, and converts it to SVG format.

4. policy_scrawler

Use flowx to create a workflow named policy_scrawler.

Requirements:
1. Obtain the institution-name templates you need from the national policy publishing institution directory.
2. Combine province, city, and county names across China to construct concrete search names for policy institutions nationwide.
3. Use Playwright to simulate a browser and search Baidu for the official website names of the target institutions.
4. Build a workflow that crawls the official website URLs of policy institutions nationwide.

5. start-up-hiring

Use flowx to build a crawler workflow that finds the founders of n AI startups that are currently hiring on LinkedIn.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Si FlowX te resulta útil, dale una estrella al repositorio, comparte un workflow que hayas generado o abre una incidencia describiendo una intención que quieras convertir en un workflow. Cuando redistribuyas o modifiques FlowX, mantén la atribución de LICENSE y NOTICE (consulta docs/PROVENANCE.md).

Contacto

¿Te interesa construir la capa de Workflow Generativo para Agentes de IA—o conectarla a una UI inteligente? Ponte en contacto en peterxcx@gmail.com.

Código QR de WeChat:

Volver arriba ↑