AG-UI Protocol Python SDK

raw JSON →
0.1.15 verified Wed May 13 auth: no python

AG-UI (Agent-User Interaction Protocol) is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications. The `ag-ui-protocol` Python SDK provides strongly-typed data structures and event encoding for building AG-UI compatible agent servers. It's built on Pydantic for robust validation and automatic camelCase serialization for seamless frontend integration, and is currently at version 0.1.15. The library has a continuous release cadence, reflecting ongoing development in the AG-UI ecosystem.

pip install ag-ui-protocol
error ModuleNotFoundError: No module named 'ag_ui'
cause The 'ag_ui' module is not installed or not found in the Python environment.
fix
Ensure the 'ag-ui-protocol' package is installed by running 'pip install ag-ui-protocol'.
error ImportError: cannot import name 'TextMessageContentEvent' from 'ag_ui.core'
cause The 'TextMessageContentEvent' class is not available in the 'ag_ui.core' module.
fix
Verify the correct import path and ensure you are using the appropriate version of 'ag-ui-protocol'.
error AttributeError: module 'ag_ui.encoder' has no attribute 'EventEncoder'
cause The 'EventEncoder' class is not defined in the 'ag_ui.encoder' module.
fix
Check the module's documentation for the correct usage or alternative classes.
error TypeError: __init__() missing 1 required positional argument: 'type'
cause An instance of an event class is being created without specifying the required 'type' argument.
fix
Provide the 'type' argument when initializing the event class, e.g., 'event = TextMessageContentEvent(type=EventType.TEXT_MESSAGE_CONTENT, ...)'
error ValueError: Invalid event type: 'INVALID_EVENT_TYPE'
cause An invalid or unrecognized event type is being used.
fix
Use a valid event type from the 'EventType' enumeration provided by the library.
breaking The AG-UI protocol is under active development. While efforts are made to use versioned schemas, specific event types, data models, or API structures may change in future releases, potentially requiring updates to integrated agents and UIs.
fix Refer to the official AG-UI documentation and release notes for migration guides and updated API specifications with each new major version. Test integrations thoroughly on upgrade.
gotcha AG-UI servers should not be directly exposed to untrusted clients (e.g., browsers, mobile apps) due to security risks. A trusted frontend server should mediate communication to validate and control the construction of AG-UI protocol messages, preventing malicious client input.
fix Implement a trusted intermediary server between the AG-UI agent server and untrusted clients. This server is responsible for sanitizing inputs, validating requests, and constructing valid AG-UI messages.
gotcha Integrating AG-UI with existing agent frameworks or custom tooling often requires explicit configuration for features like tool exposure and event translation. Automatic handling might not be sufficient or desired. For instance, in `ag-ui-adk`, client tools are not automatically added to the root agent's toolset and require explicit `AGUIToolset` addition.
fix Carefully review the integration guides for your specific agent framework (e.g., LangGraph, Agent Framework, Pydantic AI) when implementing AG-UI. Expect to explicitly define and configure how AG-UI events, tools, and state are handled and mapped.
gotcha Effective state management in AG-UI requires understanding when to use `STATE_SNAPSHOT` (full state replacement) versus `STATE_DELTA` (incremental JSON Patch updates). Incorrect usage can lead to inefficient data transfer or inconsistent state between agent and UI.
fix Utilize `STATE_SNAPSHOT` for initial state establishment or major refreshes. Employ `STATE_DELTA` events (which use JSON Patch format) for frequent, small, incremental updates to optimize bandwidth and maintain real-time synchronization. Design state objects to support partial updates.
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - 0.57s 28.0M 12.2M clean
3.10 alpine (musl) - - 0.63s 28.0M 12.2M -
3.10 slim (glibc) wheel 3.6s 0.40s 28M 12.2M clean
3.10 slim (glibc) - - 0.43s 28M 12.2M -
3.11 alpine (musl) wheel - 0.82s 30.6M 13.3M clean
3.11 alpine (musl) - - 0.96s 30.6M 13.3M -
3.11 slim (glibc) wheel 3.0s 0.71s 30M 13.3M clean
3.11 slim (glibc) - - 0.74s 30M 13.3M -
3.12 alpine (musl) wheel - 0.94s 22.3M 13.2M clean
3.12 alpine (musl) - - 1.07s 22.3M 13.2M -
3.12 slim (glibc) wheel 2.5s 0.94s 22M 13.2M clean
3.12 slim (glibc) - - 0.99s 22M 13.2M -
3.13 alpine (musl) wheel - 0.52s 22.0M 9.6M clean
3.13 alpine (musl) - - 0.53s 21.9M 9.6M -
3.13 slim (glibc) wheel 2.7s 0.56s 22M 9.6M clean
3.13 slim (glibc) - - 0.60s 22M 9.6M -
3.9 alpine (musl) wheel - 0.50s 27.5M 11.3M clean
3.9 alpine (musl) - - 0.55s 27.5M 11.3M -
3.9 slim (glibc) wheel 4.2s 0.44s 27M 11.3M clean
3.9 slim (glibc) - - 0.48s 27M 11.3M -

This quickstart demonstrates how to set up a basic AG-UI compatible FastAPI endpoint that receives `RunAgentInput` and streams `AgentEvent` responses, specifically `TextMessageContent` and `RunFinished` events, using Server-Sent Events (SSE). It echoes the last user message received.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from ag_ui.core import RunAgentInput, TextMessageContent, RunFinished, AgentEvent
from ag_ui.encoder import AgentEventEncoder
import uvicorn
import asyncio
import json
import os

app = FastAPI(title="AG-UI Endpoint Example")

@app.post("/awp")
async def my_endpoint(input_data: RunAgentInput):
    async def event_generator():
        # Initial greeting event
        yield AgentEventEncoder.encode(TextMessageContent(text="Hello from AG-UI!"))
        
        # Echo the last text message from the input
        if input_data.messages:
            last_message = input_data.messages[-1]
            # Ensure the last message is a TextMessageContent for echoing
            if isinstance(last_message, TextMessageContent):
                yield AgentEventEncoder.encode(TextMessageContent(text=f"You said: {last_message.text}"))
            else:
                yield AgentEventEncoder.encode(TextMessageContent(text="Received a non-text message type."))
        else:
            yield AgentEventEncoder.encode(TextMessageContent(text="No messages provided in input."))

        # Simulate some asynchronous work
        await asyncio.sleep(0.5)
        yield AgentEventEncoder.encode(TextMessageContent(text="Performing some agent actions..."))
        await asyncio.sleep(0.5)

        # End the run with a RunFinished event
        yield AgentEventEncoder.encode(RunFinished())

    # Use StreamingResponse for Server-Sent Events (SSE)
    return StreamingResponse(event_generator(), media_type="text/event-stream")

if __name__ == "__main__":
    # To run this, you'll need fastapi and uvicorn installed:
    # pip install "fastapi[all]" uvicorn
    # Then, run this script directly:
    # python your_script_name.py
    # Or, if saved as main.py:
    # uvicorn main:app --host 0.0.0.0 --port 8000
    uvicorn.run(app, host="0.0.0.0", port=8000)