AgentCircuits.UI 0.5.2

AgentCircuits.UI

A modern chat interface for AgentCircuits agents, built with SvelteKit. This UI connects to an AgentCircuits Portal backend via SignalR and provides real-time streaming of agent responses, tool call visualisation, and session management.

Table of Contents

• Features
• Getting Started
• Architecture
• Configuration
• Development
• Testing
• Project Structure

Features

Chat Interface

• Streaming responses - Real-time text streaming via SignalR
• Thinking/reasoning display - Collapsible reasoning content blocks
• Dark/light theme - System preference detection with manual override
• Responsive design - Desktop and mobile support

Tool Call Visualisation

• Collapsible tool calls - View tool name, arguments, and results
• Status indicators - Pending (spinner), success (tick), error (cross)
• Result pairing - Tool results matched to invocations by ID

Session Management

• Session list - Browse previous conversations
• Session switching - Load any session's history
• New session - Start fresh conversations
• Delete session - Remove unwanted sessions

Metrics Display

• Token counts - Input/output tokens per turn
• Cost tracking - USD cost when available
• Performance metrics - TTFT, tokens per second

Keyboard Shortcuts

Installation

NuGet Package (Recommended for Production)

The UI is distributed as a NuGet package with pre-built assets embedded. No Node.js required at runtime.

dotnet add package AgentCircuits.UI

Usage:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Mount at root "/"
app.UseAgentCircuitsUI();

// Or mount at a specific path
app.UseAgentCircuitsUI("/chat");

// With custom options
app.UseAgentCircuitsUI("/chat", options =>
{
    options.EnableCacheControlHeaders = false;
    options.EnableSpaFallback = true;
});

app.Run();

Configuration Options:

The middleware serves the pre-built SvelteKit assets from embedded resources and handles SPA fallback routing automatically.

Development Setup

Prerequisites

• Node.js 18+ (20+ recommended)
• npm 9+
• .NET 9.0 (for the Portal backend)

1. Start the Server Backend

The UI requires the AgentCircuits Server running. In a separate terminal:

cd /home/azik/code/agentcircuits
dotnet run --project agentcircuits.server/src/AgentCircuits.Server.csproj

The server runs at http://localhost:56433 by default.

Verify the backend is running:

# Check agents endpoint
curl http://localhost:56433/api/agents

# Check sessions endpoint
curl http://localhost:56433/api/sessions

2. Install UI Dependencies

cd /home/azik/code/agentcircuits/agentcircuits.ui
npm install

3. Start the UI Development Server

npx vite

Note: npm run dev runs a dev script with legacy paths. Use npx vite directly for a cleaner start.

The UI runs at http://localhost:5173. The Vite dev server proxies API requests to the portal:

• /api/* → http://localhost:56433
• /hubs/* → http://localhost:56433 (WebSocket)

4. Open in Browser

Navigate to http://localhost:5173. You should see:

1. Connection indicator (bottom-right) showing "Connected" in green
2. Session list in the sidebar (may be empty initially)
3. Chat input at the bottom

5. Send Your First Message

1. The UI auto-selects the first available agent
2. Type a message and press Enter
3. Watch the streaming response appear

Architecture

Overview

AgentCircuits.UI (SvelteKit)
         │
         │ SignalR WebSocket
         ▼
AgentCircuits.Portal (ASP.NET Core)
         │
         │ Agent Execution
         ▼
AgentCircuits SDK (Agent, Tools, LLM Providers)

Key Components

Data Flow

1. User sends message via ChatStore.sendMessage()
2. Message sent to portal via SignalRService.executeAgent()
3. Portal executes agent, streams events back
4. Events received via AgentEvent callback
5. EventStore.handleEvent() processes each event
6. UI reactively updates from EventStore.messages
7. ExecutionComplete callback captures session ID

Event Types

Configuration

Environment Variables

Create a .env file or set these before running:

# Backend URL (default: same origin, proxied in dev)
VITE_API_BASE_URL=

# SignalR hub path (default: /hubs/execution)
VITE_HUB_PATH=/hubs/execution

Vite Proxy Configuration

The proxy is configured in vite.config.ts:

server: {
  proxy: {
    '/api': 'http://localhost:56433',
    '/hubs': {
      target: 'http://localhost:56433',
      ws: true
    }
  }
}

Update the port if your portal runs on a different port.

Agent Selection

The UI uses single-agent mode:

1. On load, fetches agents from /api/agents
2. Selects first agent (or from localStorage if previously set)
3. Agent ID persisted to localStorage as defaultAgentId

Development

Development Server

npm run dev

This starts Vite with hot module replacement. Changes to .svelte, .ts, or .css files reload instantly.

Production Build

npm run build

Outputs static files to wwwroot/ (configurable in svelte.config.js).

Type Checking

npm run check

Linting and Formatting

npm run lint      # Check code style
npm run format    # Auto-format with Prettier

Useful Commands

Testing

Manual Testing Checklist

1. Connection

   • Status indicator shows "Connected" (green)
   • Reconnects automatically after network interruption

2. Chat Flow

   • Send a text message
   • See streaming response
   • Thinking content displays (if agent uses reasoning)
   • Tool calls display with status indicators

3. Session Management

   • Session appears in sidebar after first message
   • Click session to load history
   • "New chat" button clears state
   • Delete session removes from list

4. Error Handling

   • Error dialog shows on execution error
   • Connection status shows "Disconnected" when portal stops

Running with a Test Agent

Ensure the portal has at least one agent configured:

# Check configured agents
curl http://localhost:56433/api/agents | jq

If no agents exist, create one via the Portal UI at http://localhost:56433.

Project Structure

agentcircuits.ui/
├── src/
│   ├── lib/
│   │   ├── components/       # UI components
│   │   │   ├── app/          # Application components
│   │   │   │   ├── chat/     # Chat interface components
│   │   │   │   ├── tools/    # Tool call display
│   │   │   │   └── ...
│   │   │   └── ui/           # shadcn-svelte primitives
│   │   ├── stores/           # State management (Svelte 5 runes)
│   │   │   ├── chat.svelte.ts
│   │   │   ├── connection.svelte.ts
│   │   │   ├── events.svelte.ts
│   │   │   ├── sessions.svelte.ts
│   │   │   └── ...
│   │   ├── services/         # API and SignalR services
│   │   │   └── signalr.ts
│   │   ├── types/            # TypeScript interfaces
│   │   │   ├── events.ts     # AgentCircuits event types
│   │   │   └── ui.ts         # UI model types
│   │   └── utils/            # Utility functions
│   ├── routes/               # SvelteKit routes
│   │   ├── +layout.svelte    # Main layout with SignalR wiring
│   │   └── +page.svelte      # Chat page
│   └── app.css               # Global styles
├── static/                   # Static assets
├── tests/                    # Test files
├── vite.config.ts            # Vite configuration
├── svelte.config.js          # SvelteKit configuration
└── package.json

Tech Stack

Troubleshooting

Connection Issues

"Disconnected" status:

• Check portal is running: curl http://localhost:56433/api/agents
• Check port matches in vite.config.ts
• Check browser console for WebSocket errors

Port already in use: If you see "Address already in use" when starting the portal:

# Find and kill process using the port
fuser -k 56433/tcp
# Or on macOS
lsof -ti:56433 | xargs kill

CORS errors:

• Ensure you're accessing via http://localhost:5173 (Vite proxy)
• Don't access the portal directly for the UI

Console shows /props 404: This is expected - the /props endpoint is not used by the AgentCircuits Portal. The 404 is logged as a warning but doesn't affect functionality.

No Agents Available

If the agent selector is empty:

1. Open Portal UI at http://localhost:56433
2. Create an agent configuration
3. Refresh the UI

Messages Not Sending

• Check connection status indicator
• Check browser console for errors
• Verify an agent is selected (check sessions store)

Related Documentation

• AgentCircuits.UI Design Document - Full architecture and implementation details
• AgentCircuits Portal - Backend API and SignalR hub
• AgentCircuits SDK - Core agent framework