{"id":1797,"library":"ag-ui-protocol","title":"AG-UI Protocol Python SDK","description":"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.","status":"active","version":"0.1.15","language":"en","source_language":"en","source_url":"https://github.com/ag-ui-protocol/ag-ui-protocol","tags":["AI","agents","protocol","event-driven","pydantic","fastapi","streaming","LLM","UI","real-time"],"install":[{"cmd":"pip install ag-ui-protocol","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides core data models, validation, and serialization for AG-UI types.","package":"pydantic","optional":false}],"imports":[{"note":"`RunAgentInput` is directly available from `ag_ui.core`, `ag_ui.core.types` is an unnecessary submodule access.","wrong":"from ag_ui.core.types import RunAgentInput","symbol":"RunAgentInput","correct":"from ag_ui.core import RunAgentInput"},{"note":"Used for serializing AG-UI events into a streaming format (e.g., Server-Sent Events).","symbol":"AgentEventEncoder","correct":"from ag_ui.encoder import AgentEventEncoder"},{"note":"A common event type for streaming text messages from the agent.","symbol":"TextMessageContent","correct":"from ag_ui.core import TextMessageContent"}],"quickstart":{"code":"from fastapi import FastAPI\nfrom fastapi.responses import StreamingResponse\nfrom ag_ui.core import RunAgentInput, TextMessageContent, RunFinished, AgentEvent\nfrom ag_ui.encoder import AgentEventEncoder\nimport uvicorn\nimport asyncio\nimport json\nimport os\n\napp = FastAPI(title=\"AG-UI Endpoint Example\")\n\n@app.post(\"/awp\")\nasync def my_endpoint(input_data: RunAgentInput):\n    async def event_generator():\n        # Initial greeting event\n        yield AgentEventEncoder.encode(TextMessageContent(text=\"Hello from AG-UI!\"))\n        \n        # Echo the last text message from the input\n        if input_data.messages:\n            last_message = input_data.messages[-1]\n            # Ensure the last message is a TextMessageContent for echoing\n            if isinstance(last_message, TextMessageContent):\n                yield AgentEventEncoder.encode(TextMessageContent(text=f\"You said: {last_message.text}\"))\n            else:\n                yield AgentEventEncoder.encode(TextMessageContent(text=\"Received a non-text message type.\"))\n        else:\n            yield AgentEventEncoder.encode(TextMessageContent(text=\"No messages provided in input.\"))\n\n        # Simulate some asynchronous work\n        await asyncio.sleep(0.5)\n        yield AgentEventEncoder.encode(TextMessageContent(text=\"Performing some agent actions...\"))\n        await asyncio.sleep(0.5)\n\n        # End the run with a RunFinished event\n        yield AgentEventEncoder.encode(RunFinished())\n\n    # Use StreamingResponse for Server-Sent Events (SSE)\n    return StreamingResponse(event_generator(), media_type=\"text/event-stream\")\n\nif __name__ == \"__main__\":\n    # To run this, you'll need fastapi and uvicorn installed:\n    # pip install \"fastapi[all]\" uvicorn\n    # Then, run this script directly:\n    # python your_script_name.py\n    # Or, if saved as main.py:\n    # uvicorn main:app --host 0.0.0.0 --port 8000\n    uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.1.x and earlier"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}