# Agent Framework AG-UI Integration

AG-UI protocol integration for Agent Framework, enabling seamless integration with AG-UI's web interface and streaming protocol.

## Installation

```bash
pip install agent-framework-ag-ui
```

## Quick Start

### Using Example Agents with Any Chat Client

All example agents are factory functions that accept any `SupportsChatGetResponse`-compatible chat client:

```python
from fastapi import FastAPI
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.openai import OpenAIChatClient
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
from agent_framework_ag_ui_examples.agents import simple_agent, weather_agent

app = FastAPI()

# Option 1: Use Azure OpenAI
azure_client = OpenAIChatCompletionClient(model="gpt-4")
add_agent_framework_fastapi_endpoint(app, simple_agent(azure_client), "/chat")

# Option 2: Use OpenAI
openai_client = OpenAIChatClient(model="gpt-4o")
add_agent_framework_fastapi_endpoint(app, weather_agent(openai_client), "/weather")

# Run with: uvicorn main:app --reload
```

### Creating Your Own Agent

```python
from fastapi import FastAPI
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint

# Create your agent
agent = Agent(
    name="my_agent",
    instructions="You are a helpful assistant.",
    client=OpenAIChatCompletionClient(model="gpt-4o"),
)

# Create FastAPI app and add AG-UI endpoint
app = FastAPI()
add_agent_framework_fastapi_endpoint(app, agent, "/agent")

# Run with: uvicorn main:app --reload
```

## Features

This integration supports all 7 AG-UI features:

1. **Agentic Chat**: Basic streaming chat with tool calling support
2. **Backend Tool Rendering**: Tools executed on backend with results streamed via ToolCallResultEvent
3. **Human in the Loop**: Function approval requests for user confirmation before tool execution
4. **Agentic Generative UI**: Async tools for long-running operations with progress updates
5. **Tool-based Generative UI**: Custom UI components rendered on frontend based on tool calls
6. **Shared State**: Bidirectional state sync using StateSnapshotEvent and StateDeltaEvent
7. **Predictive State Updates**: Stream tool arguments as optimistic state updates during execution

## Examples

All example agents are implemented as **factory functions** that accept any chat client implementing `SupportsChatGetResponse`. This provides maximum flexibility to use Azure OpenAI, OpenAI, Anthropic, or any custom chat client implementation.

### Available Example Agents

Complete examples for all AG-UI features are available:

- `simple_agent(client)` - Basic agentic chat (Feature 1)
- `weather_agent(client)` - Backend tool rendering (Feature 2)
- `human_in_the_loop_agent(client)` - Human-in-the-loop with step customization (Feature 3)
- `task_steps_agent_wrapped(client)` - Agentic generative UI with step execution (Feature 4)
- `ui_generator_agent(client)` - Tool-based generative UI (Feature 5)
- `recipe_agent(client)` - Shared state management (Feature 6)
- `document_writer_agent(client)` - Predictive state updates (Feature 7)
- `research_assistant_agent(client)` - Research with progress events
- `task_planner_agent(client)` - Task planning with approvals
- `subgraphs_agent()` - Deterministic travel-planning subgraphs flow (Dojo `subgraphs` feature)

### Using Example Agents

```python
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.openai import OpenAIChatClient
from agent_framework_ag_ui_examples.agents import (
    simple_agent,
    weather_agent,
    recipe_agent,
)

# Create a chat client (use any SupportsChatGetResponse implementation)
azure_client = OpenAIChatCompletionClient(model="gpt-4")
openai_client = OpenAIChatClient(model="gpt-4o")

# Create agent instances by calling the factory functions
agent1 = simple_agent(azure_client)
agent2 = weather_agent(openai_client)
agent3 = recipe_agent(azure_client)
```

### Running the Example Server

The example server demonstrates all 7 AG-UI features:

```bash
# Install the package
pip install agent-framework-ag-ui

# Run the example server
python -m agent_framework_ag_ui_examples

# Or with debug logging
ENABLE_DEBUG_LOGGING=1 python -m agent_framework_ag_ui_examples
```

The server exposes endpoints at:
- `/agentic_chat` - Simple chat with `simple_agent`
- `/backend_tool_rendering` - Weather tools with `weather_agent`
- `/human_in_the_loop` - Step approval with `human_in_the_loop_agent`
- `/agentic_generative_ui` - Task steps with `task_steps_agent_wrapped`
- `/tool_based_generative_ui` - Custom UI components with `ui_generator_agent`
- `/shared_state` - Recipe management with `recipe_agent`
- `/predictive_state_updates` - Document writing with `document_writer_agent`
- `/subgraphs` - Travel planner with interrupt-driven flight/hotel choices via `subgraphs_agent`

### Interrupt and Resume Shape

Human-in-the-loop and workflow examples use the canonical AG-UI protocol shape. A paused run finishes with
`RUN_FINISHED.outcome.type == "interrupt"` and renders prompts from `RUN_FINISHED.outcome.interrupts`; it does not
depend on a stable top-level `RUN_FINISHED.interrupt` field.

Resume interrupted example threads with a canonical `resume` array:

```json
{
  "threadId": "thread-1",
  "messages": [],
  "resume": [
    {
      "interruptId": "interrupt_1",
      "status": "resolved",
      "payload": {
        "approved": true
      }
    }
  ]
}
```

### Complete FastAPI Example

```python
from fastapi import FastAPI
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
from agent_framework_ag_ui_examples.agents import (
    simple_agent,
    weather_agent,
    human_in_the_loop_agent,
    task_steps_agent_wrapped,
    ui_generator_agent,
    recipe_agent,
    document_writer_agent,
    subgraphs_agent,
)

app = FastAPI(title="AG-UI Examples")

# Create a chat client (shared across all agents, or create individual ones)
client = OpenAIChatCompletionClient(model="gpt-4")

# Add all example endpoints
add_agent_framework_fastapi_endpoint(app, simple_agent(client), "/agentic_chat")
add_agent_framework_fastapi_endpoint(app, weather_agent(client), "/backend_tool_rendering")
add_agent_framework_fastapi_endpoint(app, human_in_the_loop_agent(client), "/human_in_the_loop")
add_agent_framework_fastapi_endpoint(app, task_steps_agent_wrapped(client), "/agentic_generative_ui")  # type: ignore[arg-type]
add_agent_framework_fastapi_endpoint(app, ui_generator_agent(client), "/tool_based_generative_ui")
add_agent_framework_fastapi_endpoint(app, recipe_agent(client), "/shared_state")
add_agent_framework_fastapi_endpoint(app, document_writer_agent(client), "/predictive_state_updates")
add_agent_framework_fastapi_endpoint(app, subgraphs_agent(), "/subgraphs")
```

## Architecture

The package uses a clean, orchestrator-based architecture:

- **AgentFrameworkAgent**: Lightweight wrapper that delegates to orchestrators
- **Orchestrators**: Handle different execution flows (default, human-in-the-loop, etc.)
- **Confirmation Strategies**: Domain-specific confirmation messages (extensible)
- **AgentFrameworkEventBridge**: Converts AgentResponseUpdate to AG-UI events
- **Message Adapters**: Bidirectional conversion between AG-UI and Agent Framework message formats
- **FastAPI Endpoint**: Streaming HTTP endpoint with Server-Sent Events (SSE)

### Key Design Patterns

- **Orchestrator Pattern**: Separates flow control from protocol translation
- **Strategy Pattern**: Pluggable confirmation message strategies
- **Context Object**: Lazy-loaded execution context passed to orchestrators
- **Event Bridge**: Stateless translation of Agent Framework events to AG-UI events

## Advanced Usage

### Creating Custom Agent Factories

You can create your own agent factories following the same pattern as the examples:

```python
from agent_framework import Agent, tool
from agent_framework import SupportsChatGetResponse
from agent_framework.ag_ui import AgentFrameworkAgent

@tool
def my_tool(param: str) -> str:
    """My custom tool."""
    return f"Result: {param}"

def my_custom_agent(client: SupportsChatGetResponse) -> AgentFrameworkAgent:
    """Create a custom agent with the specified chat client.

    Args:
        client: The chat client to use for the agent

    Returns:
        A configured AgentFrameworkAgent instance
    """
    agent = Agent(
        name="my_custom_agent",
        instructions="Custom instructions here",
        client=client,
        tools=[my_tool],
    )

    return AgentFrameworkAgent(
        agent=agent,
        name="MyCustomAgent",
        description="My custom agent description",
    )

# Use it
from agent_framework.openai import OpenAIChatCompletionClient
client = OpenAIChatCompletionClient()
agent = my_custom_agent(client)
```

### Shared State

State is injected as system messages and updated via predictive state updates:

```python
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.ag_ui import AgentFrameworkAgent

# Create your agent
agent = Agent(
    name="recipe_agent",
    client=OpenAIChatCompletionClient(model="gpt-4o"),
)

state_schema = {
    "recipe": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "ingredients": {"type": "array"}
        }
    }
}

# Configure which tool updates which state fields
predict_state_config = {
    "recipe": {"tool": "update_recipe", "tool_argument": "recipe_data"}
}

wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    state_schema=state_schema,
    predict_state_config=predict_state_config,
)
```

### Predictive State Updates

Predictive state updates automatically stream tool arguments as optimistic state updates:

```python
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework.ag_ui import AgentFrameworkAgent

# Create your agent
agent = Agent(
    name="document_writer",
    client=OpenAIChatCompletionClient(model="gpt-4o"),
)

predict_state_config = {
    "current_title": {"tool": "write_document", "tool_argument": "title"},
    "current_content": {"tool": "write_document", "tool_argument": "content"},
}

wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    state_schema={"current_title": {"type": "string"}, "current_content": {"type": "string"}},
    predict_state_config=predict_state_config,
    require_confirmation=True,  # User can approve/reject changes
)
```

### Human in the Loop

Human-in-the-loop is automatically handled when tools are marked for approval:

```python
from agent_framework import tool

@tool(approval_mode="always_require")
def sensitive_action(param: str) -> str:
    """This action requires user approval."""
    return f"Executed with {param}"

# The orchestrator automatically detects approval responses and handles them
```

### Custom Orchestrators

Add custom execution flows by implementing the Orchestrator pattern:

```python
from agent_framework.ag_ui._orchestrators import Orchestrator, ExecutionContext

class MyCustomOrchestrator(Orchestrator):
    def can_handle(self, context: ExecutionContext) -> bool:
        # Return True if this orchestrator should handle the request
        return context.input_data.get("custom_mode") == True

    async def run(self, context: ExecutionContext):
        # Custom execution logic
        yield RunStartedEvent(...)
        # ... your custom flow
        yield RunFinishedEvent(...)

wrapped_agent = AgentFrameworkAgent(
    agent=your_agent,
    orchestrators=[MyCustomOrchestrator(), DefaultOrchestrator()],
)

## License

MIT
