# QVerisFlow: LangGraph workflows with conversational construction

> QVerisFlow is a Python and React framework for building, editing, and monitoring multi-agent workflows. It is aimed at engineers who want LangGraph orchestration, LLM selection, QVeris tool access, and a visual interface in one application, but its licensing metadata and deployment requirements need review before adoption.

**QVerisAI/QVerisFlow** — Automatic multi-agent workflow generation, fully integrated with QVeris unified data and tool layer

- Repository: https://github.com/QVerisAI/QVerisFlow
- Stars: 1,813 · Forks: 71
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/qverisai-qverisflow

## What QVerisFlow is built to coordinate

QVerisFlow addresses the operational cost of assembling multi-agent applications from separate components. The repository describes a framework for conversational workflow construction, visual editing, automatic Agent definition generation, and live execution monitoring. That makes it relevant to engineers building workflows in which several agents, tools, and model calls must be coordinated rather than placed in a single prompt or script.

The intended workflow starts with a natural-language request in the Web UI. A dialogue-oriented agent interprets the request, while the Meta Agent can analyze the task and generate agent definitions. The result appears as a graph that the user can edit before execution. For teams that prefer code or configuration, the same project exposes Python definitions, YAML agent files, and a command-line builder. The README also identifies QVeris as a unified data and tool layer, so applications can reference tools such as `qveris_search_tools` and `qveris_execute_tool` instead of implementing every external integration inside an agent.

This is not a general-purpose business automation suite as described in the repository. Its center of gravity is an agent graph. It is most useful when the application needs routing, workflow state, multiple specialized agents, and visibility into execution progress. A single deterministic function that does not require model calls, persistence, or graph editing is a poor fit because QVerisFlow introduces LangGraph, model configuration, WebSocket communication, and infrastructure components before it reaches that function.

## QVerisFlow layers, graph state, and event flow

The architecture is divided into six layers. The Web UI uses React, ReactFlow, WebSocket, and Zustand. FastAPI and WebSocket handlers form the Web API layer. The evolution layer contains `DialogueAgent`, `MetaAgent`, `ConversationalBuilder`, and `WorkflowOperationTools`. Orchestration is handled by `SmartRouter` and `WorkflowEngine`. The core layer provides `BaseAgent`, `AgentGraph`, `ContextManager`, and verification components. Definitions such as `AgentDefinition`, `ToolDefinition`, and `WorkflowDefinition` sit below that, while PostgreSQL, Redis, the QVeris API, and multiple LLM providers form the infrastructure layer.

The documented execution path is therefore conversational request, workflow planning, agent generation, graph editing, execution, and WebSocket status updates. `BaseAgent` is described as encapsulating a LangGraph state graph, and `AgentGraph` builds the execution graph. `SmartRouter` selects an agent according to the task. `WorkflowEngine` supports streaming execution and real-time events. The UI receives those events through `WebSocketHandler`, which also manages sessions, while `SessionManager` handles user session and state persistence.

QVerisFlow also documents a three-layer validation mechanism: rule validation, LLM judging, and composition validation. The README does not give enough detail to explain how disagreements among those layers are resolved or what happens when an LLM judge fails. That omission matters because a generated workflow can appear complete on the canvas without proving that its tools, routing decisions, or outputs are valid.

## Installing QVerisFlow and starting the Web UI

The README recommends Python 3.11 or later and gives two dependency installation paths. The `uv` path is listed first, while the pip path includes the Web and development extras. These commands install the package and its declared dependencies; they do not configure credentials or start PostgreSQL, Redis, MinIO, or the QVeris API.

```bash
uv sync
```

The pip alternative is the exact command documented by the project:

```bash
pip install -e ".[web,dev]"
```

Before starting the services, edit `config/app_config.yaml`. The documented Qwen configuration requires an API key, a DashScope-compatible base URL, and a selected default model. Treat `your-api-key` as a placeholder and replace it before launching the application.

```yaml
models:
  qwen-plus:
    api_key: "your-api-key"
    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    model_name: "qwen-plus"
    max_tokens: 8000
    temperature: 0.3

model_selection:
  default: "qwen-plus"
```

Start the backend in one terminal:

```bash
uv run python -m src.web
```

Start the frontend in another terminal. The README directs the operator into `web-ui`, installs npm dependencies, and runs the development server:

```bash
cd web-ui && npm install && npm run dev
```

The documented UI address is `http://localhost:5173`. At this point, a first real use is to describe a workflow in the conversation panel, confirm the generated plan and agents, inspect the graph, then execute it and watch the status updates. The README does not state whether the backend must be reachable on a particular host, nor does it provide a documented login or initial account step.

## Infrastructure modes and QVeris integration

QVerisFlow has a larger deployment footprint than the quick-start commands suggest. The repository includes a `Dockerfile`, `docker-compose.yml`, and `.env.example`. The Compose file documents two modes. A bare-metal deployment starts infrastructure only and leaves the application to connect to services such as `localhost`. A Docker deployment uses the Compose application profile to run the application and infrastructure together.

For infrastructure-only startup, the documented command is:

```bash
docker compose up -d postgres redis minio minio-init
```

The Compose configuration exposes PostgreSQL and Redis by default, while MinIO is used for object storage. The environment template enables `ENABLE_POSTGRES`, `ENABLE_REDIS`, and `ENABLE_OSS`, with `DEPLOY_MODE=bare-metal` as its example setting. It also defines local directories for workspaces, storage, logs, and temporary files. These defaults are development-oriented. In particular, the example contains `POSTGRES_PASSWORD=postgres`, `MINIO_ACCESS_KEY=minioadmin`, and `MINIO_SECRET_KEY=minioadmin`, which should be reviewed before any shared deployment.

QVeris access is separately configurable. The documented configuration enables the integration and reads `QVERIS_API_KEY` from the environment:

```yaml
qveris:
  enabled: true
  api_key: ${QVERIS_API_KEY}
  base_url: "https://qveris.ai/api/v1"
```

The README does not explain which QVeris plan, account, tool permissions, or API guarantees are required. Engineers should therefore verify that the configured QVeris endpoint and tool identifiers match their account before enabling generated agents that depend on them.

## Where QVerisFlow is strict, and where it is unfinished

The clearest limitation is the gap between generated workflows and verified outcomes. The project advertises three validation layers, but the README does not document retry policy, timeout handling, failed-tool behavior, approval gates, or how a user recovers a workflow that passes planning but fails during execution. The Web UI is said to support pause, resume, and intervention, yet the README does not define the state transitions or persistence guarantees for those actions.

There is also a distribution and licensing inconsistency. The repository description and README identify Apache License 2.0, while `pyproject.toml` declares `license = { text = "MIT" }` and the project name is `agent-framework`, not `QVerisFlow`. That mismatch can affect packaging metadata and organizational compliance review. This article does not determine which license is intended. Check the repository's `LICENSE` file and the metadata used by the package distribution before redistribution.

The project has no GitHub releases. Its last push was on 2026-06-10, and the repository is not archived. That means there is a recent code history to inspect, but the documentation does not establish a release cadence, compatibility policy, or long-term support commitment. The use of `langgraph>=0.2.0`, `langchain-core>=0.3.0`, and other lower-bounded dependencies also means an environment can resolve newer versions than the project has documented.

## QVerisFlow versus a direct LangGraph application

A direct LangGraph application is the clearest alternative. In that approach, the engineer defines the state schema, nodes, edges, tools, and execution entry point directly in Python. It usually has fewer framework layers because there is no need for a conversational builder, ReactFlow canvas, WebSocket event layer, or QVeris-specific integration unless those features are required.

QVerisFlow's difference is not simply that it uses LangGraph. It adds a construction loop around the graph. A user can describe the application, generate definitions, edit them visually, and inspect execution events. It also centralizes model selection and references QVeris tools through `ToolDefinition` and tool references. That is useful when workflow editing and runtime observability are first-class requirements.

The trade-off is operational and architectural overhead. Direct LangGraph code gives the engineer explicit control over graph transitions and dependencies. QVerisFlow offers more application infrastructure, but the README does not define migration from generated YAML or Python definitions, nor does it explain whether a canvas workflow can be exported as code. For a small internal automation, direct LangGraph is likely easier to inspect. For a team building an operator-facing multi-agent workspace, QVerisFlow supplies the missing UI and session features.

## Conclusion

QVerisFlow fits teams that already operate Python agents and want a visual workflow builder backed by LangGraph, PostgreSQL, Redis, and optional QVeris services. It is less suitable for a small local script that needs no graph UI, persistent workspaces, or multi-agent routing. Verify the conflicting Apache-2.0 and MIT metadata first, then confirm model credentials, QVeris availability, infrastructure requirements, and the release policy before committing to it. The repository's last push was on 2026-06-10 and GitHub releases are not documented.

## FAQ

### How do I install QVerisFlow?

The README documents `uv sync` as the recommended installation command. It also provides `pip install -e ".[web,dev]"` for a pip-based editable installation with the Web and development extras.

### What configuration does QVerisFlow need before it can use an LLM?

Edit `config/app_config.yaml` to define a model under `models` and select it through `model_selection`. The documented example uses `qwen-plus`, an API key placeholder, and a DashScope-compatible `base_url`.

### Can QVerisFlow run without PostgreSQL, Redis, or QVeris?

The repository provides separate infrastructure and application deployment modes, and `.env.example` includes switches such as `ENABLE_POSTGRES` and `ENABLE_REDIS`. The README does not document a minimal mode that removes every infrastructure dependency, so this cannot be confirmed without inspecting the application configuration and startup code.

### How do I monitor a QVerisFlow workflow?

The README says that `WorkflowEngine` supports streaming execution and real-time events, while the Web UI uses WebSocket communication to display progress. It also states that pause, resume, and intervention are supported, but does not document their detailed state behavior.

### What license does QVerisFlow use?

The README and repository description state Apache License 2.0, but `pyproject.toml` contains `license = { text = "MIT" }`. The intended license should be verified against the repository's `LICENSE` file and package metadata before use or redistribution.

## Sources

- [Issues](https://github.com/QVerisAI/QVerisFlow/issues)
- [License: Apache-2.0](https://github.com/QVerisAI/QVerisFlow/blob/main/LICENSE)
- [QVerisAI/QVerisFlow on GitHub](https://github.com/QVerisAI/QVerisFlow)
- [README](https://github.com/QVerisAI/QVerisFlow/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qverisai-qverisflow