Rediger

AG-UI Integration with Agent Framework

AG-UI is a protocol that enables you to build web-based AI agent applications with advanced features like real-time streaming, state management, and interactive UI components. The Agent Framework AG-UI integration provides seamless connectivity between your agents and web clients.

What is AG-UI?

AG-UI is a standardized protocol for building AI agent interfaces that provides:

  • Remote Agent Hosting: Deploy AI agents as web services accessible by multiple clients
  • Real-time Streaming: Stream agent responses using Server-Sent Events (SSE) for immediate feedback
  • Standardized Communication: Consistent message format for reliable agent interactions
  • Session Management: Maintain conversation context across multiple requests
  • Advanced Features: Human-in-the-loop approvals, state synchronization, and custom UI rendering

When to Use AG-UI

Consider using AG-UI when you need to:

  • Build web or mobile applications that interact with AI agents
  • Deploy agents as services accessible by multiple concurrent users
  • Stream agent responses in real-time to provide immediate user feedback
  • Implement approval workflows where users confirm actions before execution
  • Synchronize state between client and server for interactive experiences
  • Render custom UI components based on agent tool calls

AG-UI scenarios

AG-UI defines seven showcase scenarios. MAF support varies by SDK; use the language-specific section on this page for the current support level and implementation guidance.

  1. Agentic Chat: Basic streaming chat with automatic tool calling
  2. Backend Tool Rendering: Tools executed on backend with results streamed to client
  3. Human in the Loop: Function approval requests for user confirmation
  4. Agentic Generative UI: Async tools for long-running operations with progress updates
  5. Tool-based Generative UI: Custom UI components rendered based on tool calls
  6. Shared State: Bidirectional state synchronization between client and server
  7. Predictive State Updates: Stream tool arguments as optimistic state updates

Build agent UIs with CopilotKit

CopilotKit provides rich UI components for building agent user interfaces based on the standard AG-UI protocol. CopilotKit supports streaming chat interfaces, frontend & backend tool calling, human-in-the-loop interactions, generative UI, shared state, and much more. You can see examples of the various agent UI scenarios that CopilotKit supports in the AG-UI Dojo sample application.

To connect a CopilotKit React frontend to an Agent Framework AG-UI backend, register your endpoint as an HttpAgent in the CopilotKit runtime. This allows CopilotKit's frontend tools to flow through as AG-UI client tools, and all AG-UI features (streaming, approvals, state sync) work automatically.

CopilotKit helps you focus on your agent’s capabilities while delivering a polished user experience without reinventing the wheel. To learn more about getting started with Microsoft Agent Framework and CopilotKit, see the Microsoft Agent Framework integration for CopilotKit documentation.

.NET integration

The .NET integration exposes a MAF AIAgent as an AG-UI HTTP endpoint. The hosting adapter converts the agent's response stream into AG-UI events; core agent behavior such as tool execution and approval remains part of MAF.

Use the .NET integration to:

AG-UI clients decide how to render text, tool, approval, and state events.

Architecture

The C# hosting package adds an ASP.NET Core endpoint around an ordinary MAF agent:

AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent

MapAGUIServer adapts the AG-UI request to MAF messages and run options. It then converts the agent's streaming response to AG-UI events using the AG-UI .NET SDK.

Installation

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease

Next steps

Get started with AG-UI

AG-UI vs. Direct Agent Usage

While you can run agents directly in your application using Agent Framework's run and run(..., stream=True) methods, AG-UI provides additional capabilities:

Feature Direct Agent Usage AG-UI Integration
Deployment Embedded in application Remote service via HTTP
Client Access Single application Multiple clients (web, mobile)
Streaming In-process async iteration Server-Sent Events (SSE)
State Management Application-managed Bidirectional protocol-level sync
Thread Context Application-managed Protocol-managed thread IDs
Approval Workflows Custom implementation Built-in protocol support

Architecture Overview

The AG-UI integration uses a clean, modular architecture:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Key Components

  • FastAPI Endpoint: HTTP endpoint that handles SSE streaming, configurable keepalive comments, and request routing
  • AgentFrameworkAgent: Lightweight wrapper that adapts Agent Framework agents to AG-UI protocol
  • Orchestrators: Handle different execution flows (default, human-in-the-loop, state management)
  • Event Bridge: Converts Agent Framework events to AG-UI protocol events
  • Message Adapters: Bidirectional conversion between AG-UI and Agent Framework message formats
  • Confirmation Strategies: Extensible strategies for domain-specific confirmation messages

How Agent Framework Translates to AG-UI

Understanding how Agent Framework concepts map to AG-UI helps you build effective integrations:

Agent Framework Concept AG-UI Equivalent Description
Agent Agent Endpoint Each agent becomes an HTTP endpoint
agent.run() HTTP POST Request Client sends messages via HTTP
agent.run(..., stream=True) Server-Sent Events Streaming responses via SSE
Agent response updates AG-UI Events TEXT_MESSAGE_CONTENT, TOOL_CALL_START, etc.
Function tools (@tool) Backend Tools Executed on server, results streamed to client
Tool approval mode Human-in-the-Loop Approval requests/responses via protocol
Conversation history Thread Management threadId maintains context across requests

Installation

Install the AG-UI integration package:

pip install agent-framework-ag-ui --pre

This installs both the core agent framework and AG-UI integration components.

Next Steps

To get started with AG-UI integration:

  1. Getting Started: Build your first AG-UI server and client
  2. Backend Tool Rendering: Add function tools to your agents
  3. Workflows: Expose multi-agent workflows through AG-UI
  4. Human-in-the-Loop: Implement approval workflows
  5. MCP Apps Compatibility: Use MCP Apps with your AG-UI endpoint
  6. State Management: Synchronize state between client and server

Additional Resources

Go supports AG-UI through provider/aguiprovider for both servers and clients.

import "github.com/microsoft/agent-framework-go/provider/aguiprovider"

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Tip

See the AG-UI Go examples for complete server and client samples.

  • Last updated on