Building Multi-Agent Workflows with MadoHub

Running a single AI agent is straightforward. Running five agents that depend on each other's outputs is where things get interesting — and where most tools fall short.

This post walks through how to build a multi-agent workflow in MadoHub, from laying out tiles to configuring routing rules.

Start with the output

Before placing any tiles on the canvas, decide what the final output should be. Working backward from the result forces you to think about which intermediate steps are necessary.

For example, say you want to generate a tested, documented API endpoint. The final output is a pull request containing the implementation, tests, and documentation. Working backward:

• A PR composer agent assembles the final output
• A test writer agent produces test files
• A docs writer agent generates API documentation
• A code generator agent writes the implementation
• A spec parser agent extracts requirements from a natural language description

Placing tiles on the canvas

Each agent gets a tile. In MadoHub, tiles are independent execution environments — each runs in its own context with its own model configuration and system prompt.

Place the spec parser on the left side of the canvas and the PR composer on the right. The intermediate agents go in between, roughly in execution order. This left-to-right layout mirrors how data flows through the system.

Defining connections

Connections are directed edges between tiles. When you draw a connection from the spec parser's output port to the code generator's input port, you're telling MadoHub to feed the parsed specification into the code generation prompt.

A tile can have multiple inputs. The test writer might receive both the parsed spec and the generated code, so it can write tests that match the specification and call the actual implementation.

Routing strategies

Not every connection should fire the moment upstream output appears. Each connection in MadoHub has a trigger:

• on-complete: fires once the upstream agent's session is detected as complete
• on-idle: fires once the upstream agent's terminal goes idle
• on-keyword: fires when a configured keyword shows up in the upstream output
• always: fires on every new chunk of output, with no completion signal required

Under the hood, on-complete and on-idle are handled the same way — both wait out a short idle timer (around 8 seconds) after their triggering signal before routing. Think of them as the same pause with two different reasons to start it, not two independent strategies.

Each connection also has a transform, which controls what actually gets sent downstream: raw (the last several lines verbatim), summary (an AI-generated summary), full-output (a larger recent window), prompt-wrap (your own template with variables like {output} and {round}), or ai-routing (an AI-generated, context-aware prompt, which needs an API key configured).

For our API workflow, you might set the spec parser's connection to the code generator as on-complete with a full-output transform, then set the code generator's connections to the test writer and docs writer as on-complete with a raw transform — both downstream agents start as soon as the code generator's session reports done, working from the same recent output.

Handling failures

Agents fail. Models hallucinate. Outputs don't always match expectations. A robust multi-agent workflow needs guardrails so a routed loop doesn't run forever.

MadoHub's loop protection works on rounds rather than output validation: each routed connection has a maxRounds cap (default 5, configurable from 1 to 20) and a cooldown between rounds (default 3 seconds, configurable up to 30) so a downstream agent can't be re-triggered faster than it can realistically respond. You can also set a stopKeyword — any case-insensitive substring, like "LGTM" — and the loop stops as soon as an agent's output contains it.

This is exactly how MadoHub's built-in Peer review flow works: a Claude Code author and a Codex reviewer are wired in a loop with stopKeyword set to "LGTM" — the reviewer keeps sending feedback until it says so, and the loop stops there. The built-in Pipeline flow is simpler: a two-stage handoff where the first agent's full-output feeds the second agent on completion. The built-in Watcher flow is keyword-triggered end to end, using the ai-routing transform to turn a matched phrase into a context-aware follow-up prompt.

Iteration is the point

The real advantage of canvas-based multi-agent workflows is iteration speed. Adding a new agent — say, a security reviewer between the code generator and the PR composer — takes seconds. You place a tile, draw two connections, and the workflow updates.

Try doing that in a pipeline-as-code system. You'd be editing configuration files, restarting processes, and hoping the schema still validates. On the canvas, the feedback loop is immediate.