Flowise Multi-Agent Workflow: Supervisor and Worker Pattern

Build a Flowise multi-agent system using the supervisor-worker pattern. Route tasks to specialized agents and return unified results.
·
5 min read
·
Mark
·
Flowise

Problem: One Agent Can't Do Everything Well

A single Flowise agent handling research, code generation, and data analysis will hallucinate more, use the wrong tools, and produce inconsistent output. The supervisor-worker pattern fixes this by routing each task to a specialized agent that has exactly the tools and prompt it needs.

You'll learn:

  • How to wire a supervisor agent that classifies and delegates tasks
  • How to build worker agents with scoped tools and focused system prompts
  • How to return a unified response to the user from multiple agents

Time: 25 min | Difficulty: Intermediate

Why a Single Agent Breaks Under Load

LLMs degrade when given too many tools in one context window. Every tool you attach increases the chance the model picks the wrong one. Research shows tool-selection accuracy drops noticeably past 10–15 tools.

The supervisor-worker pattern solves this with division of labor:

User message
     │
     ▼
┌─────────────┐
│  Supervisor │  ← classifies intent, routes to worker
└──────┬──────┘
       │
  ┌────┴────┐
  ▼         ▼
Worker A  Worker B   ← each has 3–5 focused tools
(Research) (Code)
  │         │
  └────┬────┘
       ▼
  Final response

The supervisor never executes tools directly. Workers never see each other's tools.

Solution

Step 1: Create the Supervisor Agent Flow

Open Flowise and create a new flow called supervisor-main.

Add these nodes:

  • ChatOpenAI (or any LLM node) — set model to gpt-4o
  • Agent node — this becomes the supervisor
  • Buffer Memory — short-term memory for the conversation

Connect: ChatOpenAI → Agent, Buffer Memory → Agent.

Set the Agent System Prompt to:

You are a routing supervisor. Your only job is to analyze the user's request
and decide which worker should handle it. Do not answer directly.

Workers available:
- research_worker: web search, summarization, fact-finding
- code_worker: writing code, debugging, explaining code
- data_worker: CSV analysis, calculations, chart descriptions

Always call exactly one worker. Pass the user's original message unchanged.

This prompt keeps the supervisor from attempting to answer — it only routes.

Step 2: Build the Research Worker

Create a second flow called worker-research.

Add these nodes:

  • ChatOpenAI — model: gpt-4o-mini (cheaper for focused tasks)
  • Agent node
  • SerpAPI Tool or BraveSearch Tool
  • Calculator Tool (useful for date math during research)
  • Buffer Memory

Connect them and set the Agent System Prompt:

You are a research specialist. Use the search tool to find accurate,
up-to-date information. Always cite your source URL.
Never write code. If the user asks for code, say: "Please ask the code worker."

Keeping the "never write code" instruction prevents workers from drifting into each other's domains.

Save and copy the Flow API endpoint URL — you'll need it in Step 4.

https://your-flowise-host/api/v1/prediction/{research-flow-id}

Step 3: Build the Code Worker

Create a third flow called worker-code.

Add these nodes:

  • ChatOpenAI — model: gpt-4o
  • Agent node
  • Custom Tool — a code execution sandbox (or use the built-in Code Interpreter tool if available)
  • Buffer Memory

Set the Agent System Prompt:

You are a senior software engineer. Write clean, working code with comments
that explain WHY decisions were made. Default to Python unless the user
specifies a language. Always include a usage example.
Never perform web searches. If facts are needed, say: "Please ask the research worker."

Copy this flow's API endpoint URL too.

Step 4: Connect Workers to the Supervisor via Custom Tool

Back in supervisor-main, add two Custom Tool nodes — one per worker.

For the research worker tool, set:

  • Tool Name: research_worker
  • Tool Description: Use for web search, fact-finding, and summarization tasks. Input: the user's original message as a string.
  • Tool Type: HTTP Request
  • URL: https://your-flowise-host/api/v1/prediction/{research-flow-id}
  • Method: POST
  • Body:
{
  "question": "{{input}}"
}

Repeat for code_worker pointing at the code flow's ID.

Connect both Custom Tool nodes to the Supervisor Agent node.

Step 5: Add a Shared Output Formatter

Add a LLM Chain node after the Supervisor Agent. This cleans up the raw worker response before it reaches the user.

Set its prompt template:

You received this response from a specialized worker agent:

{worker_response}

Reformat it into a clean, structured reply for the end user.
Keep all technical details. Add a one-sentence summary at the top.

Connect: Supervisor Agent → LLM Chain → Chat Output.

Step 6: Configure Flowise Environment Variables

In your Flowise .env or Docker environment, set:

# Prevents workers from making unauthorized outbound calls
FLOWISE_SECRETKEY_OVERWRITE=your-secret-key

# Required if workers call back into the same Flowise instance
FLOWISE_URL=https://your-flowise-host

# Keep agent execution traces for debugging
DEBUG=true

If you're self-hosting with Docker:

# docker-compose.yml
services:
  flowise:
    image: flowiseai/flowise:2.x
    environment:
      - FLOWISE_SECRETKEY_OVERWRITE=your-secret-key
      - FLOWISE_URL=http://localhost:3000
      - DEBUG=true
    ports:
      - "3000:3000"
    volumes:
      - ~/.flowise:/root/.flowise

Verification

Send a test message to the supervisor flow via the Flowise chat UI or API:

curl -X POST https://your-flowise-host/api/v1/prediction/{supervisor-flow-id} \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the latest updates to the OpenAI API?"}'

You should see:

  1. The supervisor logs show a research_worker tool call
  2. The research worker runs a search
  3. The output formatter returns a structured summary

Test the code path:

curl -X POST https://your-flowise-host/api/v1/prediction/{supervisor-flow-id} \
  -H "Content-Type: application/json" \
  -d '{"question": "Write a Python function to chunk text by token count"}'

The supervisor should now route to code_worker instead.

If routing fails:

  • Supervisor calls both workers → Tighten the system prompt. Add: "Call exactly one worker. Never call more than one."
  • Supervisor tries to answer directly → Remove all non-routing tools from the supervisor. It should only have worker tool nodes.
  • Worker HTTP call returns 401 → Check that FLOWISE_SECRETKEY_OVERWRITE is set and the request header includes Authorization: Bearer your-secret-key

What You Learned

  • The supervisor agent should have zero domain tools — only worker-call tools
  • Worker system prompts must explicitly exclude other workers' domains
  • The output formatter step is optional but significantly improves response quality in production
  • Each worker can use a cheaper model than the supervisor without sacrificing quality

Limitation: Each routed request makes at least two LLM calls (supervisor + worker), which doubles latency and cost. For simple single-domain apps, a single agent is still faster and cheaper.

When to add a third worker: If you find the research or code worker being called for tasks it handles poorly — like PDF parsing or structured data — split that into its own data_worker with a CSV loader and calculator tool.

Tested on Flowise 2.2.x, Docker 27, gpt-4o-2024-11-20, Ubuntu 24.04