Visual Designer

The Visual Designer is a flow-based canvas for building and editing team structures visually. Create teams by dragging agents, drawing connections, and configuring relationships in an intuitive interface.

Overview

Path: /teams/designer (new team) or /teams/{id}/designer (edit existing)

Key Features:

Drag-and-drop canvas
Visual node-based agent representation
Connection lines for relationships
Properties panel for configuration
Auto-layout for clean organization
Real-time preview

Built with: Vue Flow (verified from app/components/designer/ directory and app/types/domains/team.ts)

Designer Interface

Canvas Layout

┌─────────────────────────────────────────────────────────────┐
│  Header: Team Name, Save, Cancel, Auto-Layout             │
├─────────────────┬───────────────────────────────────────────┤
│                 │                                           │
│  Toolbox Panel  │         Canvas (Infinite)                │
│                 │                                           │
│  • Add Agent    │    [Agent Node]──→[Agent Node]           │
│  • Add Team     │                                           │
│  • Add Tool     │    [Agent Node]──→[Agent Node]           │
│                 │                                           │
│                 │                                           │
├─────────────────┴───────────────────────────────────────────┤
│  Properties Panel: Selected Node/Edge Configuration        │
└─────────────────────────────────────────────────────────────┘

Canvas Features

Infinite Canvas: Pan and zoom anywhere

Pan: Click and drag on empty canvas
Zoom: Mouse wheel or pinch gesture
Fit View: Auto-centers all nodes

Grid: Optional snap-to-grid (enabled by default)

Grid Size: 20px
Snap: Nodes snap to grid when dragging
Toggle: Settings panel → Grid Enabled

Background: Dot pattern (light/dark mode adaptive)

Node Types

Agent Node

Appearance: Rounded rectangle with icon, name, and role badge

Components (from app/components/designer/ and flow types):

┌──────────────────────┐
│  👤  Agent Name      │
│  Description         │
│  [Manager] badge     │
└──────────────────────┘

Visual Indicators:

Icon: Agent icon or avatar
Name: Agent display name
Role Badge: "Manager", "Orchestrator", or "Member"
Color: Based on role (purple for manager, blue for member)
Border: Highlighted when selected

Connection Points:

Top: Input (receives from other agents)
Bottom: Output (sends to other agents)
Sides: Bidirectional (AI Delegation)

Team Node

Purpose: Reference another team as a sub-component

Appearance: Group-style node with team icon

┌──────────────────────┐
│  👥  Team Name       │
│  X agents            │
└──────────────────────┘

Use Case: Multi-tier workflows (Team A escalates to Team B)

Connection: Can connect to agents or other teams

Tool Node

Purpose: Represent external integrations in workflow

Appearance: Hexagonal node with tool icon

    ┌──────────┐
   /  🔧 Tool  \
  /   Name      \
  \             /
   └──────────┘

Status: Coming Soon — Tool nodes visible but not functional yet

Adding Nodes

From Toolbox

Steps:

Click "Add Agent" in toolbox panel
Select from existing agents OR create new
Node appears at canvas center
Drag to desired position

Existing vs New:

Existing Agent: References agent from /gnosaris list
New Agent: Creates team-specific agent (form opens in modal)

Interface: Modal with agent list and search

Filters:

Search by name or description
Filter by role (Manager, Member, etc.)
Show only agents not already in team

Action: Click agent → adds node to canvas

Creating Connections

Drawing Connections

Method 1: Drag from Connection Point

Hover over agent node
Connection points appear (top, bottom, sides)
Click and drag from point
Drop on target agent's connection point
Connection line appears

Method 2: Connection Mode

Click "Connect Mode" button in toolbar
Click source agent
Click target agent
Connection created automatically

Connection Types

When creating a connection, you select the type:

Modal appears with options:

AI Delegation (bidirectional arrow)
Handoff (one-way arrow)

Visual Differences:

AI Delegation:  [Agent A] ⟷ [Agent B]
Handoff:        [Agent A] → [Agent B]

Connection Labels

Optional: Add label to describe relationship

Examples:

"Escalate technical issues"
"Delegate research tasks"
"Route to billing specialist"

Display: Label appears on connection line (hover to see full text)

Editing Nodes

Selecting Nodes

Single Selection: Click on node Multi-Selection:

Click and drag to draw selection box
Hold Ctrl/Cmd and click multiple nodes

Selected State: Blue border, connection points visible

Properties Panel

When node selected, Properties Panel (bottom) shows:

Agent Node Properties

Tabs: Info, Configuration, Knowledge, Tools

Info Tab:

Name (editable)
Description (editable)
Role (dropdown: Manager, Orchestrator, Member)
Image URL (optional)

Configuration Tab:

Capabilities (toggles):
- Reasoning
- Multimodal
- Allow Delegation
Instructions (textarea)

Knowledge Tab:

Assigned knowledge sources (multi-select)
Add/remove sources

Tools Tab:

Assigned tools (multi-select)
Add/remove tools

Save: Changes auto-save on blur (no save button)

Node Actions

Right-click context menu:

Edit: Open properties panel
Duplicate: Create copy of node
Delete: Remove node from canvas
Center: Pan canvas to center this node

Keyboard shortcuts:

Delete: Remove selected node(s)
Ctrl+D: Duplicate selected node
Ctrl+C / Ctrl+V: Copy/paste

Editing Connections

Selecting Connections

Click on connection line → highlights edge, shows properties

Properties Panel (Edge)

Fields:

Type: AI Delegation or Handoff (dropdown)
Label: Optional descriptive text
Condition: Optional routing rule (advanced)

Example Condition: "Only if technical issue detected"

Edge Actions

Right-click context menu:

Edit Type: Change between AI Delegation and Handoff
Add Label: Add descriptive text
Delete: Remove connection

Canvas Controls

Button	Icon	Action
Zoom In	Plus	Increase zoom level
Zoom Out	Minus	Decrease zoom level
Fit View	Frame	Auto-center all nodes
Auto-Layout	Grid	Automatically organize nodes
Grid Toggle	Grid icon	Enable/disable snap-to-grid
Undo	Arrow left	Undo last action
Redo	Arrow right	Redo last undone action

Auto-Layout Feature

Purpose: Automatically organize nodes for clean, hierarchical layout

Algorithm: Hierarchical layout (top-to-bottom flow)

Steps:

Click "Auto-Layout" button
Nodes rearrange automatically
Manager at top
Members below in grid
Connections straighten

Customization: Manually adjust after auto-layout

Settings (via properties panel):

Direction: Top-to-bottom, Left-to-right
Node Spacing: Distance between nodes (default: 100px)
Rank Spacing: Distance between levels (default: 150px)

Team Configuration

Team Properties Panel

Access: Click on empty canvas area (deselects all nodes)

Fields:

Team Name (required)
Identifier (slug, auto-generated)
Description (required)
Image URL (optional)

Advanced Settings:

Auto-save: Enable/disable auto-save (default: on)
Theme: Light or dark designer theme
Grid: Enable/disable grid and snap

Saving and Publishing

Auto-Save

Default: Enabled Frequency: Every 3 seconds (debounced) Indicator: "Saved" badge in header

What's saved:

Node positions
Connections
Node configurations
Team metadata

Storage: Flow data stored in TeamFlowData format (from app/types/domains/team.ts):

typescript

{
  nodes: FlowNode[],     // Array of agent/team/tool nodes
  edges: FlowEdge[],     // Array of connection lines
  viewport: {            // Canvas view state
    x: number,
    y: number,
    zoom: number
  }
}

Manual Save

Button: "Save Team" in header (always visible)

Action:

Validates team structure (at least 2 agents, valid connections)
Saves flow data to database
Creates/updates team record
Redirects to team list

Validation Errors:

"Team must have at least 2 agents"
"Team must have a manager"
"All agents must be connected"
"Circular connections not allowed"

Cancel

Button: "Cancel" in header

Action:

If auto-save enabled → discard unsaved changes (last 3 seconds)
If auto-save disabled → discard all changes
Confirmation dialog if significant changes exist

Flow Data Structure

From app/types/domains/team.ts:

FlowNode

typescript

{
  id: string,                 // Unique node ID
  type: 'agent' | 'team' | 'tool',
  position: { x: number, y: number },
  data: {
    id: number,              // Agent/team/tool ID
    name: string,
    description?: string,
    [key: string]: any       // Additional node-specific data
  }
}

FlowEdge

typescript

{
  id: string,                 // Unique edge ID
  source: string,             // Source node ID
  target: string,             // Target node ID
  type?: string,              // Edge style (default, smooth, step)
  data?: {
    label?: string,           // Connection label
    connectionType?: 'delegation' | 'handoff',
    [key: string]: any
  }
}

TeamFlowData

typescript

{
  nodes: FlowNode[],
  edges: FlowEdge[],
  viewport: {
    x: number,
    y: number,
    zoom: number
  }
}

Storage: Saved in team table as JSON field

Designer Configuration

From app/types/domains/team.ts:

typescript

{
  team_id: number,
  flow_data: TeamFlowData,
  auto_save: boolean,          // Enable auto-save
  grid_enabled: boolean,       // Snap to grid
  snap_to_grid: boolean,       // Same as grid_enabled
  theme: 'light' | 'dark'      // Designer theme
}

Persisted: Per-user, per-team (configuration saved with team)

Keyboard Shortcuts

Shortcut	Action
Space + Drag	Pan canvas
Ctrl/Cmd + Scroll	Zoom in/out
Ctrl/Cmd + A	Select all nodes
Ctrl/Cmd + C	Copy selected nodes
Ctrl/Cmd + V	Paste nodes
Ctrl/Cmd + D	Duplicate selected
Ctrl/Cmd + Z	Undo
Ctrl/Cmd + Shift + Z	Redo
Delete / Backspace	Delete selected
Escape	Deselect all
F	Fit view (center all nodes)

Common Patterns

Support Team (Linear Escalation)

User → Tier 1 → Tier 2 → Specialist → Manager

Connections: All Handoff (one-way) Roles: Members + 1 Manager Use Case: Support escalation workflow

Research Team (Hub and Spoke)

       Researcher A
             ↕
Manager ⟷  Researcher B
             ↕
       Researcher C

Connections: AI Delegation (bidirectional) Roles: 1 Manager + 3 Members Use Case: Manager delegates research, members report results

Routing Team (Orchestrator-Centric)

         Orchestrator
         /    |    \
    Sales  Support  Product

Connections: Handoff (one-way from orchestrator) Roles: 1 Orchestrator + 3 Members Use Case: Route user to appropriate specialist

Troubleshooting

Nodes Overlapping

Problem: Multiple nodes stacked on top of each other

Fix:

Click "Auto-Layout" button
Or manually drag nodes apart
Enable grid for aligned spacing

Connections Not Drawing

Problem: Can't create connection between nodes

Possible Causes:

Source and target are the same node
Connection already exists
Invalid connection (tool → tool not allowed)

Fix: Verify nodes are different, check existing connections

Auto-Save Not Working

Problem: Changes not saving automatically

Symptoms: "Saved" indicator never appears

Fixes:

Check auto-save toggle in settings
Verify network connection
Check browser console for errors
Try manual save

Canvas Won't Pan/Zoom

Problem: Canvas stuck, can't move or zoom

Fix:

Refresh page
Clear browser cache
Disable browser extensions
Try different browser

Best Practices

Layout Organization

Hierarchical (recommended):

Manager at top
Orchestrators in middle
Members at bottom
Left-to-right for sequential flows

Grid Alignment:

Enable grid for clean layout
Align nodes horizontally at same level
Use consistent spacing (100-150px)

Connection Clarity

Labels:

Use labels for complex connections
Keep labels short (2-4 words)
Explain WHY connection exists

Avoid:

Crossing lines (hard to read)
Circular references (causes infinite loops)
Too many connections per node (max 5)

Performance

Large Teams (7+ agents):

Group related agents visually
Use clear labels
Consider splitting into multiple teams

Slow Performance:

Reduce number of nodes on canvas
Disable auto-save temporarily
Close properties panel when not editing

Next Steps

Managing Teams: Team creation and configuration basics
Managing Agents: Create agents for teams
Knowledge Sources: Add knowledge to team agents
Chat Widget: Embed team on your website

Visual Designer ​

Overview ​

Designer Interface ​

Canvas Layout ​

Canvas Features ​

Node Types ​

Agent Node ​

Team Node ​

Tool Node ​

Adding Nodes ​

From Toolbox ​

Via Agent Selector Modal ​

Creating Connections ​

Drawing Connections ​

Connection Types ​

Connection Labels ​

Editing Nodes ​

Selecting Nodes ​

Properties Panel ​

Agent Node Properties ​

Node Actions ​

Editing Connections ​

Selecting Connections ​

Properties Panel (Edge) ​

Edge Actions ​

Canvas Controls ​

Toolbar (Top) ​

Auto-Layout Feature ​

Team Configuration ​

Team Properties Panel ​

Saving and Publishing ​

Auto-Save ​

Manual Save ​

Cancel ​

Flow Data Structure ​

FlowNode ​

FlowEdge ​

TeamFlowData ​

Designer Configuration ​

Keyboard Shortcuts ​

Common Patterns ​

Support Team (Linear Escalation) ​

Research Team (Hub and Spoke) ​

Routing Team (Orchestrator-Centric) ​

Troubleshooting ​

Nodes Overlapping ​

Connections Not Drawing ​

Auto-Save Not Working ​

Canvas Won't Pan/Zoom ​

Best Practices ​

Layout Organization ​

Connection Clarity ​

Performance ​

Next Steps ​

Visual Designer

Overview

Designer Interface

Canvas Layout

Canvas Features

Node Types

Agent Node

Team Node

Tool Node

Adding Nodes

From Toolbox

Via Agent Selector Modal

Creating Connections

Drawing Connections

Connection Types

Connection Labels

Editing Nodes

Selecting Nodes

Properties Panel

Agent Node Properties

Node Actions

Editing Connections

Selecting Connections

Properties Panel (Edge)

Edge Actions

Canvas Controls

Toolbar (Top)

Auto-Layout Feature

Team Configuration

Team Properties Panel

Saving and Publishing

Auto-Save

Manual Save

Cancel

Flow Data Structure

FlowNode

FlowEdge

TeamFlowData

Designer Configuration

Keyboard Shortcuts

Common Patterns

Support Team (Linear Escalation)

Research Team (Hub and Spoke)

Routing Team (Orchestrator-Centric)

Troubleshooting

Nodes Overlapping

Connections Not Drawing

Auto-Save Not Working

Canvas Won't Pan/Zoom

Best Practices

Layout Organization

Connection Clarity

Performance

Next Steps