Visual Workflow Builder

Design and deploy AI agents visually with the drag-and-drop workflow builder

Overview

The Visual Workflow Builder enables you to design AI agent workflows through an intuitive drag-and-drop interface. Build complex multi-agent systems without writing code, then generate production-ready LangGraph Python code.

Quick Start

Build your first workflow in minutes

API Reference

Explore the Builder API

Key Features

Drag-and-Drop Interface

• Visual node-based editor
• React Flow integration for smooth interactions
• Real-time connection validation
• Auto-layout for clean workflows

Code Generation

• Generate production-ready LangGraph Python code
• Export as standalone modules
• Include type hints and docstrings
• MCP tool integration ready

Workflow Validation

• Real-time validation as you build
• Graph connectivity checks
• Node configuration validation
• Error highlighting with suggestions

One-Click Deploy

• Deploy workflows to MCP Server
• Version control for workflows
• Rollback capabilities
• Environment-specific configurations

Architecture

Quick Start

Prerequisites

• Docker and Docker Compose
• Modern web browser (Chrome, Firefox, Safari, Edge)
• Valid authentication credentials

Starting the Builder

Docker Compose

# Start full infrastructure including builder
make test-infra-full-up

# Access the builder
open http://localhost:13000

Development Mode

# Start the backend
uv run uvicorn src.mcp_server_langgraph.builder.api.server:app \
  --host 0.0.0.0 \
  --port 8001

# Start the frontend (in another terminal)
cd builder-frontend
npm install
npm run dev

Building Your First Workflow

1. Create New Workflow

   Click “New Workflow” and give it a name like “Customer Support Agent”.

2. Add a Start Node

   Drag a Start node from the palette onto the canvas. This is the entry point.

3. Add an Agent Node

   Drag an Agent node and connect it to the Start node. Configure:

   • Name: CustomerSupport
   • Prompt: “You are a helpful customer support agent…”
4. Add Conditional Routing

   Add a Router node to direct conversations based on intent:

   • Connect Agent → Router
   • Configure conditions: “billing”, “technical”, “general”
5. Add Specialized Agents

   Add more Agent nodes for each route:

   • BillingAgent
   • TechnicalAgent
   • GeneralAgent
6. Add End Node

   Connect all paths to an End node to complete the workflow.

7. Validate and Generate

   Click “Validate” to check your workflow, then “Generate Code” to export.

Node Types

Start Node

Entry point for the workflow. Every workflow must have exactly one Start node.

Properties:
  - type: start
  - id: Unique identifier
  - position: {x, y} coordinates

Agent Node

An LLM-powered agent that processes messages.

Properties:
  - type: agent
  - name: Display name
  - prompt: System prompt for the agent
  - model: LLM model to use (optional)
  - tools: List of MCP tools to enable (optional)

Router Node

Conditional branching based on content or metadata.

Properties:
  - type: router
  - conditions: List of routing conditions
  - default: Default route if no conditions match

Tool Node

Execute an MCP tool directly in the workflow.

Properties:
  - type: tool
  - tool_name: Name of the MCP tool
  - arguments: Tool arguments (static or dynamic)

Human-in-the-Loop Node

Pause for human review or input.

Properties:
  - type: human
  - prompt: Message to show reviewer
  - timeout: Maximum wait time
  - options: Available response options

End Node

Termination point for the workflow. Multiple End nodes are allowed.

Properties:
  - type: end
  - output: Final output configuration

Workflow Examples

Simple Q&A Bot

Use Case: Basic question-answering with a single agent.

Multi-Stage Pipeline

Use Case: Process requests through multiple specialized agents.

Human-in-the-Loop Review

Use Case: Content generation with human approval.

Validation Rules

The builder validates workflows against these rules:

Rule	Description
Single Start	Exactly one Start node required
Reachable End	All paths must lead to an End node
No Orphans	All nodes must be connected
No Cycles	Workflow must be a DAG (no loops without Exit condition)
Valid Configs	All node configurations must be complete
Unique IDs	All node IDs must be unique

Validation Errors

When validation fails, the builder highlights problematic nodes:

{
  "valid": false,
  "errors": [
    {
      "type": "MISSING_END_NODE",
      "message": "Workflow must have at least one End node",
      "severity": "error"
    },
    {
      "type": "ORPHAN_NODE",
      "message": "Node 'agent_3' is not connected to the workflow",
      "node_id": "agent_3",
      "severity": "warning"
    }
  ]
}

Code Generation

Generated Code Structure

The builder generates production-ready LangGraph code:

"""
Generated workflow: Customer Support Agent
Created: 2025-12-06T10:30:00Z
"""

from typing import TypedDict
from langgraph.graph import StateGraph, START, END


class AgentState(TypedDict):
    messages: list
    current_intent: str | None


def customer_support(state: AgentState) -> AgentState:
    """Customer support agent node."""
    # Agent implementation
    return state


def router(state: AgentState) -> str:
    """Route based on detected intent."""
    intent = state.get("current_intent")
    if intent == "billing":
        return "billing_agent"
    elif intent == "technical":
        return "technical_agent"
    return "general_agent"


def billing_agent(state: AgentState) -> AgentState:
    """Billing specialist agent."""
    return state


def technical_agent(state: AgentState) -> AgentState:
    """Technical support agent."""
    return state


def general_agent(state: AgentState) -> AgentState:
    """General inquiry agent."""
    return state


# Build the graph
workflow = StateGraph(AgentState)

# Add nodes
workflow.add_node("customer_support", customer_support)
workflow.add_node("billing_agent", billing_agent)
workflow.add_node("technical_agent", technical_agent)
workflow.add_node("general_agent", general_agent)

# Add edges
workflow.add_edge(START, "customer_support")
workflow.add_conditional_edges(
    "customer_support",
    router,
    {
        "billing_agent": "billing_agent",
        "technical_agent": "technical_agent",
        "general_agent": "general_agent",
    }
)
workflow.add_edge("billing_agent", END)
workflow.add_edge("technical_agent", END)
workflow.add_edge("general_agent", END)

# Compile
app = workflow.compile()

Code Generation Options

Option	Description	Default
include_types	Generate TypedDict state classes	true
include_docstrings	Add docstrings to functions	true
include_mcp_tools	Generate MCP tool imports	true
checkpoint_config	Include checkpointing setup	false
output_format	Output format (python, module)	python

Workflow Storage

Workflows are stored with versioning support:

{
  "id": "wf_abc123",
  "name": "Customer Support Agent",
  "description": "Multi-agent customer support workflow",
  "version": 3,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-06T10:30:00Z",
  "created_by": "alice",
  "nodes": [...],
  "edges": [...],
  "metadata": {
    "tags": ["support", "production"],
    "environment": "production"
  }
}

Version History

# List versions
curl http://localhost:9001/api/builder/workflows/wf_abc123/versions \
  -H "Authorization: Bearer $TOKEN"

# Get specific version
curl http://localhost:9001/api/builder/workflows/wf_abc123/versions/2 \
  -H "Authorization: Bearer $TOKEN"

# Rollback to version
curl -X POST http://localhost:9001/api/builder/workflows/wf_abc123/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"version": 2}'

Security

Authentication

All builder endpoints require JWT authentication:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Authorization

Workflow access is controlled by OpenFGA:

# Permission model
user:alice can create workflow:*
user:alice can edit workflow:wf_abc123
user:alice can deploy workflow:wf_abc123
user:bob can view workflow:wf_abc123  # Read-only access

# Team permissions
team:engineering can edit workflow:*
team:engineering can deploy workflow:*

Workflows may contain sensitive prompts and configurations. Ensure proper access controls before sharing.

API Endpoints

Endpoint	Method	Description
/api/builder/workflows	POST	Create new workflow
/api/builder/workflows	GET	List workflows
/api/builder/workflows/{id}	GET	Get workflow details
/api/builder/workflows/{id}	PUT	Update workflow
/api/builder/workflows/{id}	DELETE	Delete workflow
/api/builder/validate	POST	Validate workflow
/api/builder/generate	POST	Generate code
/api/builder/health	GET	Health check

See Builder API Reference for complete documentation.

Keyboard Shortcuts

Shortcut	Action
Ctrl/Cmd + S	Save workflow
Ctrl/Cmd + Z	Undo
Ctrl/Cmd + Shift + Z	Redo
Delete	Delete selected node
Ctrl/Cmd + D	Duplicate selected node
Ctrl/Cmd + A	Select all nodes
Escape	Deselect all
Space + Drag	Pan canvas
Scroll	Zoom in/out

Troubleshooting

Workflow won't save

Symptoms: Save button doesn’t respond or shows error

Solutions:

1. Check authentication token hasn’t expired
2. Validate workflow before saving (may have errors)
3. Check network connectivity to backend
4. Clear browser cache and reload

Code generation fails

Symptoms: Generated code is empty or incomplete

Solutions:

1. Ensure workflow passes validation first
2. Check all agent prompts are configured
3. Verify node connections are complete
4. Check backend logs for detailed errors

Nodes won't connect

Symptoms: Can’t drag connections between nodes

Solutions:

1. Check node types are compatible
2. Ensure you’re connecting output → input
3. Verify node isn’t already connected (single output only)
4. Try refreshing the page

Workflow won't deploy

Symptoms: Deploy button shows error

Solutions:

1. Validate workflow first
2. Check MCP Server is running
3. Verify deployment permissions
4. Check for conflicting workflow names

Best Practices

Start Simple

Begin with a linear workflow, then add complexity incrementally

Name Clearly

Use descriptive names for nodes and workflows

Validate Often

Run validation after each major change

Version Control

Save versions before major changes

Related Documentation

Interactive Playground

Test your workflows in real-time

LangGraph Concepts

Understand LangGraph fundamentals

MCP Tools

Configure MCP tools

Deployment

Deploy workflows to production

---

Ready to build! Open the Visual Workflow Builder and start creating your first AI agent workflow.