feat: AG-UI adapter

AG-UI adapter enabling integration with the AG-UI protocol via
the Agent.to_ag_ui() method.

This includes a full example for all features in the AG-UI dojo.

Fixes: ag-ui-protocol/ag-ui/issues/5

Author: stevenh

adapter_ag_ui/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Pydantic Services Inc. 2024 to present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adapter_ag_ui/README.md

@@ -0,0 +1,13 @@
+# AG-UI Adapter
+
+[![CI](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/pydantic/pydantic-ai/actions/workflows/ci.yml?query=branch%3Amain)
+[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic-ai.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/pydantic/pydantic-ai)
+[![PyPI](https://img.shields.io/pypi/v/adapter-ag-ui.svg)](https://pypi.python.org/pypi/adapter-ag-ui)
+[![python versions](https://img.shields.io/pypi/pyversions/adapter-ag-ui.svg)](https://github.com/pydantic/pydantic-ai)
+[![license](https://img.shields.io/github/license/pydantic/pydantic-ai.svg)](https://github.com/pydantic/pydantic-ai/blob/main/LICENSE)
+
+To make it easier to implement use AG-UI with PydanticAI agents we've
+implemented an adapter which handles the translation between PydanticAI
+and AG-UI.
+
+See [the docs](https://ai.pydantic.dev/ag_ui/) for more information.

adapter_ag_ui/adapter_ag_ui/__init__.py

@@ -0,0 +1,17 @@
+"""Pydantic AI integration for ag-ui protocol.
+
+This package provides seamless integration between pydantic-ai agents and ag-ui
+for building interactive AI applications with streaming event-based communication.
+"""
+
+from __future__ import annotations
+
+from .adapter import AdapterAGUI
+from .consts import SSE_ACCEPT
+from .deps import StateDeps
+
+__all__ = [
+    'AdapterAGUI',
+    'SSE_ACCEPT',
+    'StateDeps',
+]

adapter_ag_ui/adapter_ag_ui/_enums.py

@@ -0,0 +1,16 @@
+"""Enums for AG-UI protocol."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+# TODO(steve): Remove this and all uses once https://github.com/ag-ui-protocol/ag-ui/pull/49 is merged.
+class Role(StrEnum):
+    """Enum for message roles in AG-UI protocol."""
+
+    ASSISTANT = 'assistant'
+    USER = 'user'
+    DEVELOPER = 'developer'
+    SYSTEM = 'system'
+    TOOL = 'tool'

adapter_ag_ui/adapter_ag_ui/_exceptions.py

@@ -0,0 +1,51 @@
+"""Exceptions for the AI Agent UI module."""
+
+from __future__ import annotations
+
+from dataclasses import InitVar, dataclass
+
+from pydantic import ValidationError as PydanticValidationError
+
+
+@dataclass
+class RunError(Exception):
+    """Exception raised for errors during agent runs."""
+
+    message: str
+    code: str
+
+    def __str__(self) -> str:
+        return self.message
+
+
+@dataclass(kw_only=True)
+class UnexpectedToolCallError(RunError):
+    """Exception raised when an unexpected tool call is encountered."""
+
+    tool_name: InitVar[str]
+    message: str = ''
+    code: str = 'unexpected_tool_call'
+
+    def __post_init__(self, tool_name: str) -> None:
+        """Set the message for the unexpected tool call.
+
+        Args:
+            tool_name: The name of the tool that was unexpectedly called.
+        """
+        self.message = f'unexpected tool call name={tool_name}'
+
+
+@dataclass
+class NoMessagesError(RunError):
+    """Exception raised when no messages are found in the input."""
+
+    message: str = 'no messages found in the input'
+    code: str = 'no_messages'
+
+
+@dataclass
+class InvalidStateError(RunError, PydanticValidationError):
+    """Exception raised when an invalid state is provided."""
+
+    message: str = 'invalid state provided'
+    code: str = 'invalid_state'