feat: implement visual agent builder with node-based interface

[Ronit-Raj9]

🎨 Visual Agent Builder - MVP Implementation

Closes #916

📝 Summary

Implements a visual node-based interface for creating and configuring agents with drag-and-drop functionality, real-time validation, and seamless integration with the existing form-based builder.

✨ What's Implemented

Core Components

• VisualAgentBuilder - Main orchestrator component managing nodes, edges, and state
• Canvas - React Flow canvas with custom controls, minimap, and node selection
• NodeLibrary - Sidebar with draggable node types
• NodeProperties - Right panel for configuring selected nodes with real-time validation
• BuilderModeToggle - Toggle between form and visual builder modes
• ErrorBoundary - Error handling wrapper for visual builder

Node Types (MVP - 5 nodes)

1. Basic Info Node - Agent metadata (name, namespace, description, type)
2. LLM Node - Model configuration with namespace-aware selection
3. System Prompt Node - Agent instructions and behavior
4. Tool Node - Tool and agent selection with MCP server support
5. Output Node - Output formatting and streaming configuration

Property Editors

• BasicInfoPropertyEditor - Name, namespace, type, description
• LLMPropertyEditor - Model selection with namespace filtering
• SystemPromptPropertyEditor - System prompt textarea
• ToolPropertyEditor - Tool selection dialog integration
• OutputPropertyEditor - Format and template configuration

Utility Libraries

• graphConverter.ts - Bidirectional form ↔ graph conversion
• formConverter.ts - Tool data transformations and node merging
• validation.ts - Real-time graph validation with errors/warnings
• utils.ts - Node positioning, default data, cycle detection, orphan detection

🎯 Key Features

✅ Drag-and-drop node creation from library
✅ Connect nodes with edges to define workflow
✅ Real-time validation with collapsible error/warning panels
✅ Delete functionality via Delete/Backspace keys or floating button
✅ Multi-select support for batch operations
✅ Default template graph (Basic Info → LLM → System Prompt → Output)
✅ Namespace-aware model filtering (only shows models from same namespace)
✅ Bidirectional sync - preserves data when switching between modes
✅ Mini-map and zoom controls for navigation
✅ Keyboard shortcuts for deletion

⚠️ Current Limitations

Scope: Declarative Agents Only

• ✅ Declarative agents fully supported (system prompt, model, tools, streaming)
• ❌ BYO agents not implemented in visual builder (form mode still works)
• Users creating BYO agents should use form mode

Technical Constraints

• Visual builder disabled in edit mode (only available for new agent creation)
• Single LLM node per graph (enforced by validation)
• Model selection restricted to same namespace as agent
• Tool nodes require existing MCP servers or agents to be configured first

🔧 Technical Details

Dependencies Added

"@xyflow/react": "^12.9.2"  // Visual canvas and node management

Integration Points

1. Page Integration (ui/src/app/agents/new/page.tsx)

   • Mode toggle between form and visual builder
   • Syncs state between both modes
   • Hides footer in visual mode for full-screen experience

2. Global Styles (ui/src/app/globals.css)

   • Added .hide-footer class for visual builder full-screen mode

3. Type Definitions (ui/src/types/index.ts)

   • Added 30+ new types for nodes, edges, validation, and props
   • Exported MVP_NODE_TYPES constant for feature gating

4. Layout (ui/src/app/layout.tsx)

   • Body uses flex flex-col h-screen for proper visual builder layout

Validation System

• Node-level validation - Validates each node's data
• Graph-level validation - Checks for required nodes, cycles, orphaned nodes
• Real-time feedback - Debounced validation (300ms) on changes
• Collapsible panels - Errors and warnings in compact side-by-side display
• Create button - Disabled until all validation passes

State Management

• React hooks for local state management
• Memoization for expensive operations
• Debounced validation to prevent excessive re-renders
• Initialization guard to prevent duplicate graph creation

🧪 Testing Recommendations

Known Edge Cases

• Switching to visual mode with existing form data populates graph
• Empty graph shows helpful instructions
• Duplicate nodes of unique types (LLM, Basic Info) trigger validation warnings
• Orphaned nodes (disconnected) show warnings but don't block creation

📸 Screenshots

Add screenshots of:

1. Node library with all 5 node types

2. Connected graph with default template

3. Property panel for different node types

4. Validation errors/warnings display

5. Mode toggle button

🔄 Migration Notes

No breaking changes - Feature is opt-in:

• Existing form builder unchanged and remains default
• Visual builder only available for new agent creation (not edit mode)
• All existing agents continue to work without modification
• Form mode supports all features (BYO agents, advanced configs)

📚 Documentation Updates Needed

• User guide for visual agent builder
• Node type reference documentation
• Video tutorial/GIF for basic workflow
• Update DEVELOPMENT.md with visual builder architecture

🚀 Future Enhancements

See #916 for full roadmap. Next steps:

• BYO agent support in visual builder
• Edit mode support (convert existing agents to graph)
• Advanced node types (Conditional, Memory, Resource)
• Graph templates and presets
• Export/import graph as JSON
• Undo/redo functionality
• Copy/paste nodes
• Graph auto-layout algorithms

[peterj]

nice! I'll take a look at the PR -- @Ronit-Raj9 it would be awesome if you could join the community meeting tomorrow and do a demo of this! https://kagent.dev/community

[Ronit-Raj9]

Sure, I will show the demo in community meet tomorrow.