Agent Framework AG-UI Integration

Warnings

• breaking This library is currently in beta. APIs and internal implementations are subject to change without strict backward compatibility guarantees. The core `agent-framework` it depends on is also under active development.
  Fix: Monitor project releases closely. Expect potential breaking changes in minor/patch versions during beta. Pin exact beta versions for stability using `pip install agent-framework-ag-ui==1.0.0b260409`.
• gotcha This library is an *integration* for `agent-framework`. It does not provide the core agent capabilities itself. Users must understand and implement `agent-framework` agents to effectively use this integration.
  Fix: Ensure `agent-framework` is installed (`pip install agent-framework`) and review its documentation for core agent concepts (e.g., `Agent`, `Storage`, `Message`) before using `agent-framework-ag-ui`.
• gotcha The `agent-framework` ecosystem, including `agent-framework-ag-ui`, is entirely asynchronous. All interactions and server operations are `async`/`await` based, requiring an `asyncio` event loop.
  Fix: Always run the server and agent logic within an `asyncio` event loop (e.g., `asyncio.run(main())`). All functions interacting with the library typically need to be `async def` and calls to library methods require `await`.
• gotcha This library implements the AG-UI protocol. Effective use requires understanding the protocol's message types and interaction patterns for building compatible UIs or connecting to existing AG-UI frontends.
  Fix: Consult the AG-UI protocol specification or example UI implementations to understand how to interact with the exposed WebSocket endpoint and what messages to send/expect.

Install

• pip install agent-framework-ag-ui Install latest beta

Imports

• AgUiServer

  from agent_framework_ag_ui.server import AgUiServer

• AgUiAgent

  from agent_framework_ag_ui.agent import AgUiAgent

Quickstart

Sets up an `AgUiServer` to expose a basic `agent-framework` agent via the AG-UI WebSocket protocol. This allows AG-UI compatible frontends to connect and interact with the agent. The example includes a simple `agent-framework` agent that replies to received messages.

import asyncio
from agent_framework.agent import Agent
from agent_framework.storage import InMemoryStorage
from agent_framework_ag_ui.server import AgUiServer

class MySimpleAgent(Agent):
    def __init__(self, name, storage):
        super().__init__(name, storage)

    async def handle_message(self, message):
        print(f"MySimpleAgent received message from UI: {message.content}")
        # Example: Reply to the UI
        await self.send_message(message.create_reply("Acknowledged from agent!"))

async def main():
    # Setup core agent-framework components
    storage = InMemoryStorage()
    agent = MySimpleAgent("MyTestAgent", storage)

    # Initialize the AG-UI server
    ag_ui_server = AgUiServer(host="127.0.0.1", port=8000)

    # Register the core agent with the AG-UI server to expose it to the UI
    await ag_ui_server.register_agent(agent)

    print(f"AG-UI Server starting on ws://127.0.0.1:8000. Connect a UI to interact.")
    print("Press Ctrl+C to stop.")
    await ag_ui_server.run() # This will block and run the server

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nServer stopped.")