Registry / llm-agents / ag-ui-protocol

ag-ui-protocol

JSON →
library0.1.21pypypi✓ verified 25d ago

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
INSTALL
IMPORT
SIG · AG-UI-PROTOCOL
A
ag-ui-protocol
llm-agentspythonv0.1.21
Install
3.2s avg
Import
622ms
Disk
26MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.21 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.650s · 28MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.2s · import 0.594s · 28MB
26MB installed
● package 26MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RunAgentInput
from ag_ui.core import RunAgentInput
from ag_ui.core.types import RunAgentInput
`RunAgentInput` is directly available from `ag_ui.core`, `ag_ui.core.types` is an unnecessary submodule access.
AgentEventEncoder
from ag_ui.encoder import AgentEventEncoder
Used for serializing AG-UI events into a streaming format (e.g., Server-Sent Events).
TextMessageContent
from ag_ui.core import TextMessageContent
A common event type for streaming text messages from the agent.

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)
Debug
Known issues
breakingThe 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.
affects: 0.1.x and earlier
gotchaAG-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.
affects: All versions
gotchaIntegrating 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.
affects: All versions
gotchaEffective 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ag_ui'
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'.
ImportError: cannot import name 'TextMessageContentEvent' from 'ag_ui.core'
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'.
AttributeError: module 'ag_ui.encoder' has no attribute 'EventEncoder'
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.
TypeError: __init__() missing 1 required positional argument: 'type'
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, ...)'
ValueError: Invalid event type: 'INVALID_EVENT_TYPE'
An invalid or unrecognized event type is being used.
fix
Use a valid event type from the 'EventType' enumeration provided by the library.
Upgrade
Version history
0.1.21latest on PyPI · released Aug 27, 2026
Audit
Dependencies
pydanticrequiredProvides core data models, validation, and serialization for AG-UI types.
Agent activity
96 hits · last 30 days
node
86
OpenAI (training)
1
Resources