AgentCircuits.UI 0.7.3

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
• Lint Policy
• Project Structure

Features

Chat Interface

• Streaming responses - Real-time text streaming via SignalR
• REST API execution - Agent execution via REST with streamed event callbacks
• Thinking/reasoning display - Collapsible reasoning content blocks with reasoning stats
• Image support - Inline image rendering with clickable full-size preview modal and download
• Chat activity indicators - Visual sending/receiving status above the input form
• Dark/light theme - System preference detection with manual override
• Responsive design - Desktop and mobile support
• HTML session export - Export conversations as standalone HTML files

Tool Call Visualisation

• Collapsible tool calls - View tool name, arguments, and results
• Status indicators - Pending (spinner), success (tick), error (cross), cancelled
• Result pairing - Tool results matched to invocations by ID
• Tool approval - Approve or reject tool calls with "Always Allow" option

Session Management

• Session list - Browse previous conversations
• Session switching - Load any session's history
• Active session indicators - See which sessions are currently executing
• Session cancellation - Cancel running sessions
• New session - Start fresh conversations
• Delete session - Remove unwanted sessions

Task Management

• Task panel - Sidebar-style panel for tracking agent work progress
• Task cards - Status icons, dependency badges, and grouping by state
• Dependency graph - Visualise task dependencies
• Shared task lists - Share task lists between sessions

Agent Details

• Agent details popover - View agent specifications and configuration
• System prompt visibility - Inspect the agent's system prompt
• Live agent list updates - Agent list refreshes automatically when server configuration changes

Pending Inputs & Operations

• Pending inputs UI - Human-in-the-loop interactions (user questions, confirmations)
• Operation notifications - Visual notifications for pending operations
• Delivery mode controls - Configure how operation notifications are delivered

Metrics Display

• Token counts - Input/output tokens per turn (including cached and reasoning tokens)
• Cost tracking - USD cost when available
• Performance metrics - TTFT, tokens per second, tool call statistics

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 10.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:8080 by default.

Verify the backend is running:

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

# Check sessions endpoint
curl http://localhost:8080/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:8080
• /hubs/* → http://localhost:8080 (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. Execution request sent to portal via REST API
3. Portal executes agent, streams events back via SignalR
4. Events routed to the correct session-scoped EventStore
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:8080',
    '/hubs': {
      target: 'http://localhost:8080',
      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
4. Agent list updates live when the server configuration changes (via ConfigChanged SignalR events)

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

Automated Tests

npm run test:unit     # Unit tests (Vitest)
npm run test:client   # Client-side component tests (Vitest browser)
npm run test:ui       # UI tests (Vitest browser)
npm run test:e2e      # End-to-end tests (Playwright)
npm run test          # Run all test suites

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
   • Images render inline with clickable preview

3. Session Management

   • Session appears in sidebar after first message
   • Click session to load history
   • Active session indicators visible for running sessions
   • Cancel a running session
   • "New chat" button clears state
   • Delete session removes from list

4. Task Management

   • Task panel opens from sidebar
   • Tasks update in real time during execution
   • Dependency badges display correctly

5. Tool Approval

   • Tool approval dialog appears for restricted tools
   • "Always Allow" persists the decision

6. 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:8080/api/agents | jq

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

Lint Policy

• npm run lint is enforced in CI.
• svelte/prefer-svelte-reactivity is temporarily scoped-off for a small set of legacy files in eslint.config.js to keep CI actionable while incremental refactors are completed.
• The override is intentionally file-scoped (not global) and should be removed per file as each one is migrated to SvelteMap, SvelteSet, SvelteURL, or SvelteURLSearchParams.

Project Structure

agentcircuits.ui/
├── src/
│   ├── lib/
│   │   ├── components/       # UI components
│   │   │   ├── app/          # Application components
│   │   │   │   ├── chat/     # Chat interface (messages, form, sidebar, settings)
│   │   │   │   ├── dialogs/  # Modal dialogs (tool approval, image preview, etc.)
│   │   │   │   ├── misc/     # Shared utilities (markdown, syntax highlighting, etc.)
│   │   │   │   ├── models/   # Model selector and badges
│   │   │   │   ├── server/   # Server status and error screens
│   │   │   │   ├── tasks/    # Task management panel and cards
│   │   │   │   └── tools/    # Tool call display and renderers
│   │   │   └── ui/           # shadcn-svelte primitives
│   │   ├── stores/           # State management (Svelte 5 runes)
│   │   │   ├── activeSessions.svelte.ts  # Active execution tracking
│   │   │   ├── chat.svelte.ts            # Message orchestration
│   │   │   ├── connection.svelte.ts      # SignalR connection state
│   │   │   ├── events.svelte.ts          # Per-session event aggregation
│   │   │   ├── operations.svelte.ts      # Pending operations/notifications
│   │   │   ├── sessionInputs.svelte.ts   # Human-in-the-loop inputs
│   │   │   ├── sessions.svelte.ts        # Session list management
│   │   │   ├── tasks.svelte.ts           # Task tracking state
│   │   │   └── ...
│   │   ├── services/         # API and SignalR services
│   │   │   ├── signalr.ts               # SignalR connection and event routing
│   │   │   ├── async-operations-signalr.ts  # Async operation handling
│   │   │   ├── html-export.ts           # HTML session export
│   │   │   └── ...
│   │   ├── types/            # TypeScript interfaces
│   │   │   ├── events.ts     # AgentCircuits event types
│   │   │   ├── tasks.ts      # Task management types
│   │   │   ├── operations.ts # Operation notification 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
│   ├── client/               # Client-side component tests
│   ├── e2e/                  # End-to-end Playwright tests
│   ├── stories/              # Storybook stories
│   └── unit/                 # Unit tests
├── 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:8080/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 8080/tcp
# Or on macOS
lsof -ti:8080 | 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:8080
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