FlowX

FlowX é um servidor MCP e SDK Python que permite que agentes de IA criem fluxos de trabalho. Descreva um processo em linguagem simples; o FlowX gera o grafo do fluxo de trabalho (workflow.json), as implementações dos nós e um backend FastAPI executável. O agente pode então inspecionar, executar e alterar esse fluxo de trabalho na mesma conversa, tornando-o um processo reutilizável em vez de uma resposta pontual.

Descrever → Gerar → Inspecionar → Executar → Refinar → Reutilizar.

Upstream original: AIpRoBuilder/FlowX · Aviso de atribuição · Procedência e verificação da fonte. O FlowX permanece licenciado sob Apache-2.0; forks e reutilizações em conformidade são bem-vindos.

Demonstração ilustrativa, não uma gravação ao vivo. Seu agente existente continua sendo o assistente; o FlowX fornece sua capacidade de fluxo de trabalho por trás da conversa. Mensagens e cartões por nó ilustram o que a interface do host pode renderizar, independentemente do transporte. O FlowX não inclui essa interface nem gera automaticamente esses layouts de cartões. Os tempos de geração e execução são ilustrativos. Consulte as instruções de storyboard e renderização.

Por que FlowX

Início rápido em 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

Registre flowx-mcp no seu cliente MCP (exemplo de configuração) e então pergunte:

Use o flowx para criar um fluxo de trabalho que aceite um ticket de suporte, classifique sua categoria, atribua uma prioridade e redija uma resposta.

Outros instaladores (Poetry, uv, conda, um checkout local de ag_ui_workflow) são abordados em Instalação.

A camada de fluxo de trabalho por trás das UIs inteligentes

A UI generativa molda a interação. O Workflow Generativo molda a execução. O FlowX foca neste último: o processo explícito que um agente pode construir, executar e alterar por trás de um chat, um painel de tarefas ou outra interface inteligente.

O FlowX é agnóstico em relação a modelo e UI. Conecte um cliente de agente compatível com MCP, chame o SDK Python ou delegue a geração de fluxo de trabalho via A2A. Um frontend personalizado pode consumir os eventos do backend gerado; renderizar esses eventos continua sendo responsabilidade do frontend. Nenhuma integração dedicada com um modelo ou UI inteligente específico está implícita.

O que está disponível hoje

[!NOTE] O caminho interativo principal é o MCP stdio local. MCP e o SDK Python expõem o mesmo mecanismo: construir ou modificar workflow.json e requisitos, nós, o ponto de entrada principal ou todo o fluxo de trabalho, e então executá-lo como um serviço. O adaptador A2A atualmente expõe a construção de fluxo de trabalho sem streaming. O FlowX é uma camada de fluxo de trabalho, não um produto de UI hospedado.

Instalação

Adicione a camada de Workflow Generativo ao seu ambiente de agente. O FlowX requer Python 3.10 ou posterior; uma única instalação inclui o núcleo compartilhado, o adaptador MCP, o SDK Python e o adaptador A2A.

Instalar a partir do 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 com um checkout local do AG-UI workflow

O agente FlowX é fornecido sob packages/core/flowx_core. Apenas ag_ui_workflow permanece como uma dependência externa de runtime de fluxo de trabalho. Para usar um checkout local em vez de sua dependência Git, instale-o primeiro e depois instale o FlowX sem dependências.

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 execução a partir do checkout da fonte, o FlowX descobre automaticamente cada componente packages/*. Defina FLOWX_EXTRA_PATHS apenas quando a fonte externa de ag_ui_workflow não estiver instalada.

Compatibilidade do runtime de fluxo de trabalho

O FlowX tem como alvo a API ag_ui_workflow com escopo de solicitação, verificada contra a revisão upstream 3e1e15b (2026-10-13). Detalhes do contrato para contribuidores estão em docs/RUNTIME.md.

Configuração e primeiro fluxo de trabalho

O loop descrever → gerar → executar → refinar funciona através de qualquer cliente de agente local compatível com MCP.

1. Configure o FlowX

cp .env.example .env

Defina pelo menos FLOWX_LLM_PROVIDER, FLOWX_LLM_MODEL, FLOWX_LLM_API_KEY e 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 um flowx-mcp instalado resolva um arquivo .env fora do checkout do repositório. FLOWX_EXTRA_PATHS pode apontar para uma fonte local de ag_ui_workflow quando ela não estiver instalada no ambiente atual.

2. Inicie o servidor

# Default local stdio entry point
flowx-mcp

# Verbose logging
flowx-mcp --verbose

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

Para uso interativo no terminal, prefixe com poetry run ou uv run se o ambiente não estiver ativado. Para configuração do cliente MCP, use o caminho absoluto do executável e os argumentos descritos abaixo; um host MCP pode não herdar o PATH do seu shell.

3. Registre o FlowX em um 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 Python

Incorpore a construção de fluxos de trabalho diretamente em um agente Python ou no backend por trás da sua própria UI inteligente, sem transporte MCP. Um passo a passo completo está em 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 chamada de construção retorna um AgentResult com resultados por etapa, erros não resolvidos, logs e caminhos de artefatos; falhas de etapa são relatadas lá em vez de serem lançadas.

Para alterar um fluxo de trabalho existente, escolha o que evoluir com evolve(workflow_id, command, target=...). list_nodes retorna o id de etapa e o id de nó de cada nó para usar como alvo; sem um target, o mecanismo decide a que o comando se refere. Um passo a passo executável está em 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

Permita que outro agente delegue a geração de fluxo de trabalho ao FlowX através do endpoint Agent2Agent sem streaming:

flowx-a2a --host 127.0.0.1 --port 8001

Ele serve um cartão de agente A2A em /.well-known/agent-card.json e JSON-RPC em /a2a (também /). Os métodos suportados são message/send, tasks/get e tasks/cancel. Envie uma mensagem de texto A2A para construir um fluxo de trabalho; adicione metadata.workflowId para modificar um existente. A tarefa é completed quando todas as etapas foram bem-sucedidas e, caso contrário, failed; de qualquer forma, ela carrega o resultado, incluindo os caminhos dos artefatos gerados.

4. Crie um fluxo de trabalho a partir do chat

Comece com a mesma intenção de ticket de suporte mostrada na demonstração:

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. Execute, refine e reutilize

Faça o acompanhamento na mesma conversa:

Run the workflow as a service.

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

O cliente usa build_workflow (ou build_workflow_json, build_nodes e build_main_entrypoint uma etapa de cada vez) para criar e refinar o fluxo de trabalho, e run_service para iniciá-lo ou reiniciá-lo. evolve_workflow altera um fluxo de trabalho existente ou um nó (target="workflow", um id de etapa de nó ou id de nó de list_nodes, ou nenhum alvo para deixar o FlowX decidir). list_workflows, list_nodes e get_workflow mostram os ids de fluxo de trabalho, ids de nó e locais de artefatos. Os ids exatos de etapa vêm do fluxo de trabalho gerado — não de um esquema de demonstração fixo.

Esta é a distinção: o agente não apenas responde ao ticket. Ele constrói e evolui o processo para lidar com o próximo.

Arquitetura

A camada de Workflow Generativo tem um núcleo compartilhado e três interfaces voltadas para agentes: flowx_core planeja, gera e audita artefatos; flowx_mcp, flowx_sdk e flowx_a2a tornam essas capacidades disponíveis para diferentes hosts de agentes. O runtime gerado fica abaixo dessa camada; a UI inteligente fica acima dela.

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

Topologia do runtime

• flowx_mcp.server expõe a superfície de ferramentas via stdio através do FastMCP.
• flowx_core.AgentBuilder cria e atualiza artefatos de fluxo de trabalho a partir de prompts.
• flowx_sdk.FlowXClient e flowx_a2a chamam o mesmo núcleo de agente sem rotear via MCP.
• O main.py gerado é executado como um subprocesso FastAPI gerenciado por fluxo de trabalho.
• run_service inicia ou reinicia o main.py gerado; os clientes o acessam via HTTP e AG-UI SSE.

Da intenção aos artefatos de fluxo de trabalho

A compilação do fluxo de trabalho é o mecanismo por trás da camada de Workflow Generativo. Planejamento e geração de código transformam intenção em artefatos; auditorias fornecem feedback durante a geração e verificações em runtime. O fluxo de artefatos abaixo é espelhado de 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

Superfície de ferramentas

Estas ferramentas MCP permitem que o agente host opere a camada de fluxo de trabalho na mesma conversa. A renderização da UI é deliberadamente deixada para o host.

Exemplos de workflows

Intenções diferentes, a mesma camada de workflow: análise, transformação de arquivos e coleta de informações podem cada uma se tornar um processo executável. Cole os prompts abaixo em um cliente MCP conectado ao seu servidor flowx local e, em seguida, inspecione, execute e refine o workflow gerado. As capturas de tela são exemplos de saída, não uma UI FlowX integrada; fontes de dados externas podem exigir seus próprios acessos e dependências.

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.

Contribuindo

Issues e pull requests são bem-vindos. Se o FlowX for útil para você, dê uma estrela no repositório, compartilhe um workflow que você gerou ou abra uma issue descrevendo uma intenção que você deseja transformar em um workflow. Ao redistribuir ou modificar o FlowX, mantenha a atribuição do LICENSE e NOTICE (veja docs/PROVENANCE.md).

Contato

Interessado em construir a camada de Workflow Generativo para Agentes de IA—ou conectá-la a uma UI inteligente? Entre em contato em peterxcx@gmail.com.

QR code do WeChat:

Voltar ao topo ↑