AG-UI for .NET: How to Connect an AI Agent to a Real-Time UI

Introduction

AI agents are becoming more interactive.

A traditional API usually receives a request, performs an operation, and returns a response. An AI agent can behave differently. It may reason through a task, call tools, ask for additional information, stream partial results, update its state, and continue working.

That creates a UI challenge.

A frontend should not have to wait for the entire agent operation to finish before showing anything to the user.

This is where AG-UI, the Agent-User Interaction protocol, becomes useful. It provides a structured way for an AI agent and a user interface to communicate through events.

For .NET developers, AG-UI can provide a foundation for connecting agent backends with responsive applications while preserving information about agent state, messages, tool calls, and other runtime activity.

This article explains the AG-UI model, how it fits into a .NET application, how event streaming works, and what developers should consider when building real-time agent interfaces.

What Is AG-UI?

AG-UI stands for Agent-User Interaction.

It is an open protocol designed to connect AI agents with user interfaces.

The basic idea is:

User
 |
 v
Web UI
 |
 v
AG-UI Connection
 |
 v
AI Agent
 |
 +---- Model
 +---- Tools
 +---- Data

Instead of treating the agent as a simple request-response API, the UI can receive a stream of events describing what the agent is doing.

For example:

Agent Started
      |
      v
Message Started
      |
      v
Message Content
      |
      v
Tool Call Started
      |
      v
Tool Result
      |
      v
Message Completed

The UI can react to these events as they happen.

Why Real-Time Agent UIs Matter

Consider a traditional API request:

Browser
   |
   | POST /ask
   v
Agent
   |
   | 20 seconds
   v
Complete Response

The user sees very little information while the agent is working.

A streaming agent interface can instead look like:

Browser
   |
   v
Agent
   |
   +---- Thinking / progress event
   |
   +---- Message content
   |
   +---- Tool call
   |
   +---- Tool result
   |
   +---- More content
   |
   v
Completed

The user can see useful progress without waiting for the complete operation.

AG-UI and .NET

A .NET application can act as the backend for an AG-UI-enabled frontend.

A simplified architecture looks like:

React / Blazor / Web UI
          |
          | AG-UI Events
          v
ASP.NET Core
          |
          v
Agent Runtime
          |
     +----+----+
     |         |
   Model      Tools

The ASP.NET Core application provides the HTTP endpoint.

The agent runtime performs the actual AI work.

The frontend consumes the streamed events and updates the interface.

The Event-Based Model

The central idea is that the agent communicates through events instead of returning only one final object.

A simplified event stream might look like:

Event: RunStarted

Event: TextMessageStart

Event: TextMessageContent
"Here is the information..."

Event: ToolCallStart
"searchOrders"

Event: ToolCallResult

Event: TextMessageContent
"I found three orders..."

Event: TextMessageEnd

Event: RunFinished

The actual protocol contains more detailed event types and semantics, but this simplified sequence demonstrates the model.

The UI can process each event independently.

Request-Response vs Event Streaming

Model	Traditional API	AG-UI Style
Communication	Request/response	Event stream
Partial output	Limited	Supported
Tool visibility	Usually hidden	Can be represented
Agent progress	Limited	Event-driven
UI updates	After response	During execution
Long-running tasks	More difficult	Better suited
Interactive agents	Possible	Strong fit

The difference is particularly noticeable when an agent performs multiple operations.

A Simple .NET Endpoint

An ASP.NET Core application can expose an endpoint responsible for starting an agent run.

Conceptually:

app.MapPost("/api/agent/run", async (
    AgentRequest request,
    HttpResponse response,
    CancellationToken cancellationToken) =>
{
    response.ContentType = "text/event-stream";

    await RunAgentAsync(
        request.Message,
        response.Body,
        cancellationToken);
});

The actual AG-UI implementation depends on the agent framework and protocol library being used.

The important concept is that the response remains open while the agent produces events.

Streaming Events From .NET

A simple application-level event model might look like:

public record AgentEvent(
    string Type,
    object? Data);

The server can serialize events as they become available.

For example:

await WriteEventAsync(
    response,
    new AgentEvent(
        "message",
        new { text = "Searching orders..." }),
    cancellationToken);

The frontend receives the event and updates the interface.

A production implementation should use the protocol's defined event structures rather than inventing application-specific equivalents when interoperability is required.

Connecting an AI Agent

The agent itself may use any compatible AI framework or model provider.

A simplified architecture is:

AG-UI Endpoint
      |
      v
Agent
      |
      +---- LLM
      |
      +---- Search Tool
      |
      +---- Database Tool
      |
      +---- Business API

The agent can stream events as it moves through the workflow.

For example:

User:
"Find my recent orders and summarize them."

Agent:
   |
   +---- Call order service
   |
   +---- Receive results
   |
   +---- Analyze data
   |
   +---- Generate summary

The UI can expose useful portions of this process without exposing internal reasoning.

Tool Calls in the UI

Tool calls are one of the most useful parts of an interactive agent interface.

Suppose an agent needs to call:

getCustomerOrders

The frontend could show:

Checking recent orders...

Then display the resulting information when the tool finishes.

This creates a more transparent user experience.

However, developers should distinguish between tool activity and private model reasoning.

The UI should expose only information that is safe and useful to the user.

Building a Blazor Frontend

AG-UI is not limited to JavaScript applications.

A Blazor application can consume a streaming agent endpoint and update components as events arrive.

A conceptual component might contain:

@if (Messages.Count == 0)
{
    <p>Ask the agent a question.</p>
}
else
{
    @foreach (var message in Messages)
    {
        <div class="message">
            @message
        </div>
    }
}

The component can update its state when new agent events arrive.

For example:

Agent Event
    |
    v
Blazor State
    |
    v
StateHasChanged()
    |
    v
Updated UI

The exact event transport depends on the implementation.

React and Other Frontends

The same backend can serve a JavaScript frontend.

A browser application might connect to the agent endpoint and process incoming events:

AG-UI Server
     |
     v
Event Stream
     |
     +---- React
     +---- Angular
     +---- Vue
     +---- Blazor

This separation is valuable because the agent backend does not need to know which frontend framework is being used.

Handling Long-Running Tasks

AI agents can take longer than normal API requests.

For example:

User Request
    |
    v
Search Documents
    |
    v
Analyze Results
    |
    v
Call Business API
    |
    v
Generate Response

Instead of keeping the UI completely static, the agent can emit progress-related events.

The interface could display:

Searching documents...
Analyzing results...
Checking account data...
Preparing response...

These messages should describe meaningful application activity rather than expose hidden model reasoning.

Cancellation

Real-time agent interfaces should support cancellation.

Suppose the user starts a long-running operation and then clicks:

Cancel

The cancellation needs to propagate through the system:

Browser
   |
   | Cancel
   v
ASP.NET Core
   |
   v
Agent
   |
   +---- Cancel model call
   +---- Cancel tool
   +---- Stop processing

In .NET, CancellationToken is an important part of implementing this behavior.

For example:

public async Task RunAgentAsync(
    string prompt,
    CancellationToken cancellationToken)
{
    await agent.RunAsync(
        prompt,
        cancellationToken);
}

The agent framework must also respect cancellation for the cancellation to be effective.

Handling Errors

Streaming applications need explicit error handling.

An error can occur at several layers:

Frontend
   |
   v
HTTP Connection
   |
   v
ASP.NET Core
   |
   v
Agent
   |
   +---- Model Error
   |
   +---- Tool Error
   |
   +---- Database Error

The frontend should distinguish between:

Connection failure
Agent failure
Tool failure
Authentication failure
User cancellation

For example:

Tool failed
Retrying...

is more useful to a user than a generic:

500 Internal Server Error

Authentication and Authorization

An agent UI often has access to user-specific information.

That makes authorization essential.

For example:

User
 |
 v
Authentication
 |
 v
ASP.NET Core
 |
 v
Authorization
 |
 v
Agent
 |
 v
User Data

The agent should not receive broader permissions simply because it is operating on behalf of a user.

Tool access should be scoped to the authenticated user's permissions.

For example, an agent serving one customer should not be able to call:

getAllCustomers()

when the user is authorized only for their own account.

Protecting Sensitive Data

Streaming events can accidentally expose information that should not reach the browser.

Do not blindly stream:

API keys
Access tokens
Internal prompts
Database credentials
Private system configuration
Sensitive tool arguments
Internal infrastructure details

A good rule is:

Stream user-relevant application events, not internal implementation secrets.

Observability

Real-time agent applications need observability on both sides of the connection.

Useful telemetry includes:

Request duration
Agent run duration
Model latency
Tool latency
Error rates
Cancellation rates
Token usage
Connection failures

A distributed trace can look like:

HTTP Request
    |
    v
AG-UI Endpoint
    |
    +---- Agent
           |
           +---- Model
           |
           +---- Search Tool
           |
           +---- Database

This makes it easier to identify whether a slow UI is caused by the network, model, tool, or backend.

Reconnection and Partial State

Network connections can fail.

A user might lose connectivity after receiving several events.

The frontend should therefore avoid assuming that the entire operation either succeeds or fails as one atomic response.

Depending on the application design, the server may need a run identifier:

Run ID: 12345

The client can use that identifier to correlate events and, where supported by the architecture, recover or inspect the state of an interrupted operation.

Common Mistakes

Treating an Agent Like a Normal API

A long-running agent can produce multiple intermediate events.

Design the UI around that behavior.

Streaming Internal Reasoning

Do not expose private chain-of-thought or sensitive internal model information.

Show useful application-level progress instead.

Ignoring Cancellation

Users should have a way to stop expensive operations.

Sending Too Many UI Events

Streaming every internal state change can overwhelm the frontend.

Emit meaningful events.

Ignoring Backpressure

A fast-producing agent can generate events faster than the client can process them.

The event pipeline should be designed to handle realistic workloads.

Giving the Agent Excessive Permissions

Agent tools should follow least-privilege principles.

Troubleshooting AG-UI Applications

No Events Reach the Browser

Check:

Endpoint URL
Authentication
Content type
Connection establishment
Server-side event generation
Proxy buffering
Browser network logs

Events Arrive but UI Does Not Update

Check:

Event parsing
Event type handling
UI state management
Component refresh logic
Serialization format

Agent Response Stops Midway

Investigate:

Network disconnects
Server cancellation
Model timeout
Tool failure
Proxy timeout
Unhandled exceptions

Tool Calls Work but UI Does Not Show Them

Check whether tool events are being emitted and whether the frontend recognizes the corresponding event types.

Best Practices

Treat AG-UI as an event-driven interface between the agent and frontend.
Keep application events separate from private model reasoning.
Use structured event types.
Propagate cancellation through the entire agent workflow.
Apply authorization before tools access user data.
Keep agent permissions narrowly scoped.
Monitor model and tool latency.
Design for network failures.
Avoid streaming unnecessary internal state.
Keep event payloads small and meaningful.
Correlate events with a run or request identifier.
Test slow networks and interrupted connections.
Use standard .NET cancellation patterns.
Validate the complete frontend-to-agent workflow before production deployment.

Advantages and Disadvantages

Advantages

Enables responsive agent interfaces
Supports streaming responses
Makes tool activity visible
Works with distributed agent workflows
Separates agent backend from frontend implementation
Fits naturally with long-running operations
Can support multiple UI frameworks

Disadvantages

More complex than a normal request-response API
Requires careful event-state management
Network failures become more important
Cancellation must be implemented correctly
Authorization becomes critical when agents access user data
Streaming can expose sensitive information if poorly designed

When Should You Use AG-UI?

AG-UI is particularly useful when the application needs an interactive interface around an AI agent.

Good use cases include:

AI assistants
Coding agents
Research agents
Enterprise support agents
Data-analysis assistants
Workflow automation agents
Agents that use multiple tools
Long-running AI tasks

A simple application that only needs a short text response may not require the additional event-streaming architecture.

Summary

AG-UI provides a structured way to connect AI agents with real-time user interfaces.

For .NET developers, an ASP.NET Core backend can host an agent and stream structured events to a frontend such as Blazor, React, Angular, or another web client. The UI can then display messages, tool activity, progress, and completion events as the agent works.

The most important architectural shift is moving from a single response to an event stream.

A production implementation should combine structured events with cancellation, authorization, observability, error handling, and careful control over what information reaches the browser.

When these pieces are designed correctly, AG-UI can turn an AI agent from a black-box API into a responsive, interactive application experience.