AG-UI Protocol Demo - Enhanced Edition

中文文档 | 功能详情

A comprehensive and feature-rich demonstration of the Agent User Interaction Protocol (AG-UI) with 10+ demo scenarios, 6 interactive tools, and advanced debugging capabilities. This enhanced demo showcases real-time agent communication, complex workflows, and human-in-the-loop interactions.

🚀 New in Enhanced Edition

10 Demo Scenarios

• 🌊 Basic Text Streaming - Real-time message streaming
• 🔧 Tool Calling Workflow - Complete tool lifecycle
• 🔄 State Synchronization - Snapshots and deltas
• 🎯 Multi-Step Workflow - Complex agent processes
• ⚠️ Error Scenarios - Error handling and recovery
• ⚡ Custom Events - Application-specific events
• 🤝 Human-in-the-Loop - Interactive confirmations
• 👥 Real-time Collaboration - Bidirectional state sharing
• 📊 Data Analysis Workflow - Complete analysis pipeline
• 🚀 Progressive Enhancement - Feature evolution

Advanced Tool Integration

• 6 interactive tools with streaming arguments
• Tool performance metrics and timing
• Real-time tool status visualization
• Category-based tool organization

Performance Monitoring

• Real-time event statistics
• Response time analytics
• Tool call duration tracking
• Error rate monitoring

Enhanced UI/UX

• Scenario filtering by category
• Interactive event log export
• Advanced debugging panels
• Performance metrics dashboard

Overview

This demo implements the AG-UI protocol to create a standardized interface between AI agents and frontend applications. It demonstrates:

• Real-time streaming communication between agents and UI
• Event-driven architecture following AG-UI specification
• Tool calling mechanisms for human-in-the-loop workflows
• State synchronization between agent and frontend
• Multiple backend implementations (SignalR/.NET and Socket.IO/Node.js)
• Performance monitoring and analytics
• Advanced debugging and troubleshooting tools

Screenshots

Application Interface

The AG-UI Protocol Demo interface showing demo scenarios (left), chat interface (center), and real-time event log (right)

Interactive Demo

Real-time demonstration of AG-UI protocol events including message streaming, tool calling, and state synchronization

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Communication  │    │   Backend       │
│   (Svelte)      │◄──►│   Layer          │◄──►│   (.NET/Node)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
        │                       │                       │
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Enhanced       │    │  SignalR/        │    │  Smart Agent    │
│  AgentChat      │    │  Socket.IO       │    │  Services       │
│  Component      │    │  with Analytics  │    │  with Scenarios │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Features

✨ AG-UI Protocol Compliance

• Complete implementation of AG-UI events
• Lifecycle events (RUN_STARTED, RUN_FINISHED, STEP_STARTED, STEP_FINISHED, RUN_ERROR)
• Text message streaming (TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END)
• Tool call events (TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT)
• State management (STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT)
• Special events (CUSTOM, RAW)

🔧 Multiple Backend Options

• SignalR/.NET 8: Enterprise-grade real-time communication with smart scenario detection
• Socket.IO/Node.js: Lightweight, flexible implementation

🎯 Enhanced Demonstration Features

• 10 interactive demo scenarios: From basic streaming to complex workflows
• 6 professional tools: User management, document search, code analysis, weather, confirmations
• Real-time performance metrics: Event counting, response times, error tracking
• Advanced state management: History tracking, delta visualization, JSON Patch support
• Smart scenario detection: Backend automatically detects demo intent from user messages
• Interactive event monitoring: Real-time AG-UI event log with filtering and details
• Multi-scenario demonstrations: Pre-built scenarios for testing different AG-UI features
• Human-in-the-loop workflows: User confirmation, preferences, and collaborative decision-making
• Error handling showcase: Demonstration of error recovery and resilience patterns

📊 Demo Scenarios

• 🌊 Basic Text Streaming: Real-time character-by-character message display
• 🔧 Tool Calling Workflow: Complete tool lifecycle with argument streaming
• 🔄 State Synchronization: STATE_SNAPSHOT and STATE_DELTA demonstrations
• 🎯 Multi-Step Workflow: Complex tasks with multiple tools and state updates
• ⚠️ Error Handling: Error scenarios and recovery patterns
• ⚡ Custom Events: CUSTOM and RAW event demonstrations
• 🤝 Human-in-the-Loop: User confirmation and collaborative workflows
• 👥 Real-time Collaboration: Bidirectional state sharing

🛠️ Available Tools

• getUserPreferences: User settings and configuration management
• searchDocuments: Knowledge base search with filtering and pagination
• confirmAction: Human-in-the-loop confirmation workflows
• analyzeCode: Code analysis with security, performance, and style checks
• weatherLookup: External API integration demonstration
• createReminder: Task and reminder creation
• saveUserPreferences: Persistent user configuration
• generateChart: Data visualization tools
• Error handling: Robust connection and error management

Quick Start

Prerequisites

• Node.js 18+ and npm
• .NET 8 SDK (for SignalR backend)
• Modern web browser

Installation

# Clone the repository
git clone <repository-url>
cd ag-ui-demo1

# Install frontend dependencies
cd frontend
npm install

# Install Node.js backend dependencies
cd ../backend/nodejs-mock-server
npm install

# Return to project root
cd ../..

Running the Demo

Option 1: Socket.IO Backend (Node.js) - Recommended for Development

Terminal 1: Start Node.js Backend

cd backend/nodejs-mock-server
npm run dev
# Or: npm start

This starts the Node.js backend on port 5001

Terminal 2: Start Frontend

cd frontend
npm run dev

This starts the frontend on port 5173

Option 2: SignalR Backend (.NET)

Terminal 1: Start .NET Backend

cd backend/dotnet-signalr-server
dotnet run

This starts the .NET SignalR backend on port 5000

Terminal 2: Start Frontend

cd frontend
npm run dev

This starts the frontend on port 5173

Option 3: Frontend Only (for testing against external backends)

cd frontend
npm run dev

Access the Application

• Frontend: http://localhost:5173
• Node.js Backend: http://localhost:5001
• Backend Health Check: http://localhost:5001/health (Node.js) or http://localhost:5000/health (.NET)
• Available Tools: http://localhost:5001/tools (Node.js)

Using the Demo

1. Select Backend: Choose between Socket.IO (Node.js) or SignalR (.NET) using the radio buttons
2. View Guide: Click "Show Guide" to see available scenarios and protocol documentation
3. Try Demo Scenarios: Use the colored demo buttons to trigger specific AG-UI feature demonstrations
4. Monitor Events: Watch the Event Log panel to see real-time AG-UI events
5. Observe State: Check the Agent State panel to see state synchronization in action
6. Track Tools: Monitor the Tool Calls panel to see tool execution lifecycle
7. Interactive Chat: Type messages to have natural conversations with the agent

Project Structure

├── frontend/                 # Svelte frontend application
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/   # UI components
│   │   │   │   └── AgentChat.svelte
│   │   │   ├── SignalRAgent.ts    # SignalR client
│   │   │   ├── SocketIOAgent.ts   # Socket.IO client
│   │   │   └── types.ts           # AG-UI type definitions
│   │   ├── App.svelte        # Main application
│   │   └── main.ts
├── backend/
│   ├── dotnet-signalr-server/     # .NET SignalR implementation
│   │   ├── AgentHub.cs            # SignalR Hub with AG-UI events
│   │   └── Program.cs
│   └── nodejs-mock-server/        # Node.js Socket.IO implementation
│       ├── server.js              # Express + Socket.IO server
│       └── package.json
└── docs/                    # Multilingual documentation
    ├── en/                  # English documentation
    ├── zh/                  # Chinese documentation
    └── README.md           # This file

AG-UI Protocol Implementation

This demo showcases the complete AG-UI protocol implementation:

Event Types Implemented

1. Lifecycle Events

   • RUN_STARTED: Agent execution begins
   • RUN_FINISHED: Agent execution completes
   • RUN_ERROR: Agent execution fails
   • STEP_STARTED: Agent step begins
   • STEP_FINISHED: Agent step completes

2. Message Events

   • TEXT_MESSAGE_START: Message streaming begins
   • TEXT_MESSAGE_CONTENT: Message content chunks
   • TEXT_MESSAGE_END: Message streaming completes

3. Tool Events

   • TOOL_CALL_START: Tool execution begins
   • TOOL_CALL_ARGS: Tool arguments streaming
   • TOOL_CALL_END: Tool call completes
   • TOOL_CALL_RESULT: Tool execution result

4. State Events

   • STATE_SNAPSHOT: Complete state synchronization
   • STATE_DELTA: Incremental state updates

Tool System

The demo includes several example tools demonstrating the AG-UI tool calling pattern:

const tools = [
  {
    name: "getUserPreferences",
    description: "Get user preferences and settings",
    parameters: {
      type: "object",
      properties: {
        userId: { type: "string", description: "The user ID" }
      },
      required: ["userId"]
    }
  },
  // More tools...
];

Development

Adding New Tools

1. Define tool in frontend/src/App.svelte:

const newTool = {
  name: "myTool",
  description: "Description of what this tool does",
  parameters: {
    type: "object",
    properties: {
      param1: { type: "string", description: "Parameter description" }
    },
    required: ["param1"]
  }
};

2. Handle tool execution in backend
3. Test tool calling in the frontend interface

Customizing AG-UI Events

Extend the event handling in AgentChat.svelte:

function handleAgentEvent(event: AGUIEvent) {
  switch (event.type) {
    case EventType.CUSTOM:
      // Handle custom events
      break;
    // ... other cases
  }
}

Documentation

Comprehensive documentation is available in multiple languages:

• English: docs/en/
• 中文: docs/zh/

Available Documentation

• Architecture Guide
• Development Setup
• API Reference
• Troubleshooting
• Contributing Guidelines

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Update documentation
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

• AG-UI Protocol Documentation
• AG-UI GitHub Organization
• CopilotKit Integration

Support

For questions and support:

• Create an issue in this repository
• Join the discussion in AG-UI GitHub Discussions
• Check the troubleshooting guide