KiwiQ: a JSON and Python workflow engine compiled to LangGraph and run on Prefect

The workflow-as-code bet, and who it is aimed at

Most agent frameworks ask you to write Python functions and decorate them. KiwiQ asks you to write a graph schema, in Python or JSON, and then compiles that schema to LangGraph for execution under Prefect. The README calls this SDK-first and contrasts it explicitly with a visual builder. That is the whole design argument: a workflow definition is a file you can diff, review and store in version control, not a canvas someone clicked together in a browser tab.

The audience follows from that. This is for teams that already have a workflow they run repeatedly in production and want to express it as a declarative artifact. The README states the platform powered KiwiQ AI's marketing agents in production and was battle-tested on 200+ enterprise AI agents, and that it is now open-sourced. Treat that as a provenance claim from the maintainers, not an independent measurement. What you can verify from the repository itself is the shape of the thing: a service-oriented Python codebase with a node registry, a set of shipped workflow definitions, and a Docker Compose file that brings up six stateful services.

It is not aimed at someone who wants an agent in twenty lines. The quick start alone requires Python 3.12, Poetry, Docker and Docker Compose, and a .env file with credentials for at least one LLM provider plus five datastores.

How a workflow actually moves: schema, registry, LangGraph, Prefect

The README's architecture diagram is the clearest statement of data flow. A FastAPI application called kiwi_app sits at the top and exposes auth, billing, the workflow API, RAG endpoints, data jobs and a WebSocket. Below it are three supporting services: RabbitMQ for events, Prefect for orchestration, and Redis for caching. Below those sits a workflow service that contains two named components, a LangGraph engine and a nodes registry. At the bottom are the persistence layers: PostgreSQL for state, MongoDB for documents, Weaviate for vectors, and the LLM APIs themselves.

So the path is: a request hits the FastAPI layer, the workflow definition is resolved, the schema is compiled into a LangGraph graph, Prefect schedules and runs it, individual nodes are looked up in the registry and executed, and progress is published as events onto RabbitMQ. The same RabbitMQ events feed the WebSocket stream that the README describes as real-time, which is how a caller watches a run without polling. PostgreSQL holds workflow state and, per the Docker table, LangGraph checkpoints. That checkpoint detail matters: it is what makes a paused workflow resumable rather than merely stalled.

The node registry is where the 24+ reusable node types live. The README names LLM nodes, routing, conditional branching, data transforms, scraping, code execution and sub-workflows. Sub-workflows are the interesting one, because a graph that can invoke a graph is how you avoid one enormous schema, and it is also how you get recursion you have to reason about. The README does not describe depth limits or cycle detection, so that is something to check in the code rather than assume.

Multi-tier memory is four databases, and you run all four

KiwiQ splits memory by access pattern rather than picking one store. PostgreSQL holds relational state and LangGraph checkpoints. MongoDB holds customer data, workflow configs and prompt templates, with versioned document storage exposed through CRUD workflow nodes. Weaviate handles vector search for RAG. Redis handles caching and session management.

This is a defensible design. Versioned documents in MongoDB and checkpoints in Postgres are genuinely different workloads, and forcing either into the other store produces awkward schema. But the cost is stated plainly in the Docker Compose table: ports 5432, 27017, 6379, 5672, 15672, 8080, 4201 and 8000, eight listeners before you have written a single agent. The production compose file is described as using external managed PostgreSQL and MongoDB rather than containerized ones, which is the right call and also means your production footprint is not the thing you tested locally.

If you are evaluating this for a small team, the honest framing is that KiwiQ's memory architecture is sized for a platform, not for an application. A single Postgres instance with pgvector would cover state, documents and embeddings for many internal tools. The README does not offer a reduced-footprint mode, and nothing in the material suggests one is planned.

Getting it running: the commands the README gives

The documented path is short. Clone, install with Poetry, copy the sample environment file, start Compose.

git clone https://github.com/kiwiq-ai/kiwiq-oss.git cd kiwiq-oss poetry install cp .env.sample .env docker compose -f docker-compose-dev.yml up --build

Note that the repository field in the project metadata points at rcortx/kiwiq while the README's clone URL is kiwiq-ai/kiwiq-oss. Confirm which remote you are pulling from before you build anything on top of it.

The environment table lists OPENAI_API_KEY as required for LLM nodes, with ANTHROPIC_API_KEY, GOOGLE_API_KEY and PPLX_API_KEY marked optional. POSTGRES_*, MONGO_ROOT_* and RABBITMQ_DEFAULT_* cover the datastores, REDIS_PASSWORD covers cache, and SECRET_KEY is the JWT secret, which the README says to generate with openssl rand -hex 32. The README points at .env.sample for the full list, so budget time for that file rather than the table.

Once up, the documented endpoints are the API docs at localhost:8000/docs, the Prefect dashboard at 4201, RabbitMQ management at 15672 and RedisInsight at 8001. To run without Docker, the README gives two commands: set PYTHONPATH to the repo root and the services directory, then run poetry run uvicorn kiwi_app.main:app --host 0.0.0.0 --port 8000 --reload, and in a second terminal poetry run python services/workflow_service/services/worker.py. The README notes you still need PostgreSQL, MongoDB, Redis, RabbitMQ and Weaviate running separately, which is the whole reason the Compose file exists.

The repository also ships a CLAUDE.md so that Claude Code picks up project context when run from the repo root. That is a small thing, but it is a real signal about how the maintainers work, and it costs you nothing to use.

Human-in-the-loop and the event bus that makes it visible

The README lists HITL as a feature: pause workflows for human review, input or approval, with real-time WebSocket streaming. Mechanically, this depends on the checkpointing in PostgreSQL and the RabbitMQ event bus. A paused run has to persist enough state to resume, and the pause has to be observable, which is why the WebSocket sits in the FastAPI layer alongside the workflow API.

This is the part of the platform that is hardest to replicate cheaply. Pausing mid-graph, surviving a restart, and resuming from a checkpoint is a real engineering problem, and it is the reason Prefect is in the stack at all. If your workflows are short and synchronous, you are paying for orchestration you do not use.

The README does not document approval timeouts, what happens to a paused run if the reviewer never responds, or how concurrent pauses interact with the production tuning note about 4x concurrent workflow execution. Those are the questions to answer from the source before you put a human approval gate in front of anything that matters.

Where KiwiQ is the wrong tool, and what to use instead

The clearest mismatch is a single agent with a few tools. You would be running FastAPI, Prefect, RabbitMQ, Redis, Postgres, MongoDB and Weaviate to get behaviour that a plain LangGraph script or a minimal agent loop delivers in one process. Nothing in the README suggests a slimmed-down deployment mode, and the production compose file is described as hardened for concurrent execution, not for small footprints.

The second mismatch is a team that needs a tagged release to pin. The project metadata supplied here shows no retrieved releases. If your dependency policy requires a version number rather than a commit SHA, you are pinning to main, and that is a different risk posture.

For a real alternative, consider Prefect on its own. KiwiQ already uses Prefect as its execution layer, so the difference is not the scheduler, it is everything KiwiQ adds on top: the node registry, the graph schema format, the multi-tier memory split, the HITL pause and resume, and the shipped workflow definitions. Choosing plain Prefect means you write your own node abstractions and your own state model, and you keep the freedom to store state however you like. Choosing KiwiQ means you inherit 24+ node types and 27+ workflow definitions you did not write, and you accept its storage choices as given. That is the trade: convention and shipped material against a smaller surface you fully control.

Licence, upgrades and what the material does not say

KiwiQ is Apache-2.0. That permits commercial use, modification and redistribution, and it includes an explicit patent grant, which matters if you are embedding this in a product. It also means you carry the obligations in the licence text, including attribution and change notices. Read the LICENSE file in the repository rather than a summary, and get your own advice if the deployment is commercially significant. Nothing here is legal advice.

On maintenance, the material is thin. The last push recorded is 2026-04-13, the repository is not archived, and no releases were retrieved. There is no changelog, no migration guide and no stated compatibility policy for the workflow schema format. That last gap is the one that should worry an adopter most: if the schema format shifts between commits and you have 27 workflow definitions in your own tree, you are doing the migration by hand. The README mentions that the platform ships 27+ production workflow definitions, which are the best available reference for the current schema, but they are examples rather than a versioned contract.

There is also a structural cost the README implies without stating. Six stateful services means six upgrade paths, six backup strategies and six things that can be a version behind. The production compose file addresses this partly by moving PostgreSQL and MongoDB to managed services, which shifts the operational burden to a provider without removing it.

Editorial conclusion

Adopt KiwiQ if you already run Postgres, MongoDB, Redis, RabbitMQ and Weaviate, or are willing to, and you want workflow definitions stored as versionable Python or JSON rather than clicked together in a UI. Skip it if you are prototyping a single agent, if you cannot operate a Prefect server, or if you need a stable versioned release to pin against, because the repository shows no tagged release. Before committing, clone the repository, run poetry install, start docker compose -f docker-compose-dev.yml up --build, and confirm that the 27 workflow definitions shipped in the tree actually load through the node registry on your machine.

Official sources

1. Issues
2. License: Apache-2.0
3. rcortx/kiwiq on GitHub
4. README