Agent Framework AG-UI Integration

AG-UI protocol integration for Agent Framework, enabling seamless integration with AG-UI's web interface and streaming protocol.

Installation

pip install agent-framework-ag-ui

Quick Start

Server (Host an AI Agent)

from fastapi import FastAPI
from agent_framework import ChatAgent
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint

# Create your agent
agent = ChatAgent(
    name="my_agent",
    instructions="You are a helpful assistant.",
    chat_client=AzureOpenAIChatClient(
        endpoint="https://your-resource.openai.azure.com/",
        deployment_name="gpt-4o-mini",
        api_key="your-api-key",
    ),
)

# Create FastAPI app and add AG-UI endpoint
app = FastAPI()
add_agent_framework_fastapi_endpoint(app, agent, "/")

# Run with: uvicorn main:app --reload

Client (Connect to an AG-UI Server)

import asyncio
from agent_framework import TextContent
from agent_framework.ag_ui import AGUIChatClient

async def main():
    async with AGUIChatClient(endpoint="http://localhost:8000/") as client:
        # Stream responses
        async for update in client.get_streaming_response("Hello!"):
            for content in update.contents:
                if isinstance(content, TextContent):
                    print(content.text, end="", flush=True)
        print()

asyncio.run(main())

The AGUIChatClient supports:

Streaming and non-streaming responses
Hybrid tool execution (client-side + server-side tools)
Automatic thread management for conversation continuity
Integration with ChatAgent for client-side history management

Documentation

Getting Started Tutorial - Step-by-step guide to building AG-UI servers and clients
- Server setup with FastAPI
- Client examples using AGUIChatClient
- Hybrid tool execution (client-side + server-side)
- Thread management and conversation continuity
Examples - Complete examples for AG-UI features

Features

This integration supports all 7 AG-UI features:

Agentic Chat: Basic streaming chat with tool calling support
Backend Tool Rendering: Tools executed on backend with results streamed to client
Human in the Loop: Function approval requests for user confirmation before tool execution
Agentic Generative UI: Async tools for long-running operations with progress updates
Tool-based Generative UI: Custom UI components rendered on frontend based on tool calls
Shared State: Bidirectional state sync between client and server
Predictive State Updates: Stream tool arguments as optimistic state updates during execution

Security: Authentication & Authorization

The AG-UI endpoint does not enforce authentication by default. For production deployments, you should add authentication using FastAPI's dependency injection system via the dependencies parameter.

API Key Authentication Example

import os
from fastapi import Depends, FastAPI, HTTPException, Security
from fastapi.security import APIKeyHeader
from agent_framework import ChatAgent
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint

# Configure API key authentication
API_KEY_HEADER = APIKeyHeader(name="X-API-Key", auto_error=False)
EXPECTED_API_KEY = os.environ.get("AG_UI_API_KEY")

async def verify_api_key(api_key: str | None = Security(API_KEY_HEADER)) -> None:
    """Verify the API key provided in the request header."""
    if not api_key or api_key != EXPECTED_API_KEY:
        raise HTTPException(status_code=401, detail="Invalid or missing API key")

# Create agent and app
agent = ChatAgent(name="my_agent", instructions="...", chat_client=...)
app = FastAPI()

# Register endpoint WITH authentication
add_agent_framework_fastapi_endpoint(
    app,
    agent,
    "/",
    dependencies=[Depends(verify_api_key)],  # Authentication enforced here
)

Other Authentication Options

The dependencies parameter accepts any FastAPI dependency, enabling integration with:

OAuth 2.0 / OpenID Connect - Use fastapi.security.OAuth2PasswordBearer
JWT Tokens - Validate tokens with libraries like python-jose
Azure AD / Entra ID - Use azure-identity for Microsoft identity platform
Rate Limiting - Add request throttling dependencies
Custom Authentication - Implement your organization's auth requirements

For a complete authentication example, see getting_started/server.py.

Architecture

The package uses a clean, orchestrator-based architecture:

AgentFrameworkAgent: Lightweight wrapper that delegates to orchestrators
Orchestrators: Handle different execution flows (default, human-in-the-loop, etc.)
Confirmation Strategies: Domain-specific confirmation messages (extensible)
AgentFrameworkEventBridge: Converts Agent Framework events to AG-UI events
Message Adapters: Bidirectional conversion between AG-UI and Agent Framework message formats
FastAPI Endpoint: Streaming HTTP endpoint with Server-Sent Events (SSE)

Next Steps

New to AG-UI? Start with the Getting Started Tutorial
Want to see examples? Check out the Examples for AG-UI features

License

MIT

Metadata

Release files for agent-framework-ag-ui 1.0.0b260116

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-framework-ag-ui 1.0.0b260116
File	Size	Uploaded
agent_framework_ag_ui-1.0.0b260116.tar.gz	104.7 kB	Jan 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agent-framework-ag-ui 1.0.0b260116
File	Interpreter	ABI	Platform	Reset
agent_framework_ag_ui-1.0.0b260116-py3-none-any.whl 75.5 kB Jan 16, 2026	Python 3	none	any	Details

Total release size: 180.3 kB

Release files / agent_framework_ag_ui-1.0.0b260116.tar.gz

Download URL	agent_framework_ag_ui-1.0.0b260116.tar.gz
Size	104.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`03f6c0ae126d588c2fe4fe04ad713b2b7001fa518ccc5bc792a927f3ad21c544`
BLAKE2b-256 checksum How to use checksums	`c2ce9efd5f577d6b8faa63b67a4482a3113b8d4159b230a253613a83b368c917`
Upload date	Jan 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.25 {"installer":{"name":"uv","version":"0.9.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / agent_framework_ag_ui-1.0.0b260116-py3-none-any.whl

Download URL	agent_framework_ag_ui-1.0.0b260116-py3-none-any.whl
Size	75.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f516da4955ddbc6d1a4821e328f08ed7f81828116e2e41d30c5557ac4ad27246`
BLAKE2b-256 checksum How to use checksums	`5604a7e6bd158ca03f266c671ad4834d2b16ed072725f67d8f6ca5f8ee6dd88a`
Upload date	Jan 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.25 {"installer":{"name":"uv","version":"0.9.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`