chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,486 @@
+# Getting Started with AG-UI (Python)
+
+The AG-UI (Agent UI) protocol provides a standardized way for client applications to interact with AI agents over HTTP. This tutorial demonstrates how to build both server and client applications using the AG-UI protocol with Python.
+
+## Quick Start - Client Examples
+
+If you want to quickly try out the AG-UI client, we provide three ready-to-use examples:
+
+### Basic Interactive Client (`client.py`)
+
+A simple command-line chat client that demonstrates:
+- Streaming responses in real-time
+- Automatic thread management for conversation continuity
+- Direct `AGUIChatClient` usage (caller manages message history)
+
+**Run:**
+```bash
+python client.py
+```
+
+**Note:** This example sends only the current message to the server. The server is responsible for maintaining conversation history using the thread_id.
+
+### Advanced Features Client (`client_advanced.py`)
+
+Demonstrates advanced capabilities:
+- Tool/function calling
+- Both streaming and non-streaming responses
+- Multi-turn conversations
+- Error handling patterns
+
+**Run:**
+```bash
+python client_advanced.py
+```
+
+**Note:** This example shows direct `AGUIChatClient` usage. Tool execution and conversation continuity depend on server-side configuration and capabilities.
+
+### Agent Integration (`client_with_agent.py`)
+
+Best practice example using `Agent` wrapper with **AgentThread**
+- **AgentThread** maintains conversation state
+- Client-side conversation history management via `thread.message_store`
+- **Hybrid tool execution**: client-side + server-side tools simultaneously
+- Full conversation history sent on each request
+- Tool calling with conversation context
+
+**To demonstrate hybrid tools:**
+
+1. **Start server with server-side tool** (Terminal 1):
+   ```bash
+   # Server has get_time_zone tool
+   python server.py
+   ```
+
+2. **Run client with client-side tool** (Terminal 2):
+   ```bash
+   # Client has get_weather tool
+   python client_with_agent.py
+   ```
+
+All examples require a running AG-UI server (see Step 1 below for setup).
+
+## Understanding AG-UI Architecture
+
+### Thread Management
+
+The AG-UI protocol supports two approaches to conversation history:
+
+1. **Server-Managed Threads** (client.py, client_advanced.py)
+   - Client sends only the current message + thread_id
+   - Server maintains full conversation history
+   - Requires server to support stateful thread storage
+   - Lighter network payload
+
+2. **Client-Managed History** (client_with_agent.py)
+   - Client maintains full conversation history locally
+   - Full message history sent with each request
+   - Works with any AG-UI server (stateful or stateless)
+
+The `Agent` wrapper (used in client_with_agent.py) collects messages from local storage and sends the full history to `AGUIChatClient`, which then forwards everything to the server.
+
+### Tool/Function Calling
+
+The AG-UI protocol supports **hybrid tool execution** - both client-side AND server-side tools can coexist in the same conversation.
+
+**The Hybrid Pattern** (client_with_agent.py):
+```
+Client defines:           Server defines:
+- get_weather()          - get_current_time()
+- read_sensors()         - get_server_forecast()
+
+User: "What's the weather in SF and what time is it?"
+    ↓
+Agent sends: full history + tool definitions for get_weather, read_sensors
+    ↓
+Server LLM decides: "I need get_weather('SF') and get_current_time()"
+    ↓
+Server executes get_current_time() → "2025-11-11 14:30:00 UTC"
+Server sends function call request → get_weather('SF')
+    ↓
+Agent intercepts get_weather call → executes locally
+    ↓
+Client sends result → "Sunny, 72°F"
+    ↓
+Server combines both results → "It's sunny and 72°F in SF, and the current time is 2:30 PM UTC"
+    ↓
+Client receives final response
+```
+
+**How it works:**
+
+1. **Client-Side Tools** (`client_with_agent.py`):
+   - Tools defined in Agent's `tools` parameter execute locally
+   - Tool metadata (name, description, schema) sent to server for planning
+   - When server requests client tool → client intercepts → executes locally → sends result
+
+2. **Server-Side Tools**:
+   - Defined in server agent's configuration
+   - Server executes directly without client involvement
+   - Results included in server's response
+
+3. **Hybrid Pattern (Both Together)**:
+   - Server LLM sees ALL tool definitions (client + server)
+   - Decides which to use based on task
+   - Server tools execute server-side
+   - Client tools execute client-side
+
+**Direct AGUIChatClient Usage** (client_advanced.py):
+Even without Agent wrapper, client-side tools work:
+- Tools passed in ChatOptions execute locally
+- Server can also have its own tools
+- Hybrid execution works automatically
+
+### Interrupts and Resume Entries
+
+Human-in-the-loop approvals and workflow input requests pause by emitting a terminal `RUN_FINISHED` event whose
+`outcome.type` is `"interrupt"`. Generic AG-UI clients should read prompts from `RUN_FINISHED.outcome.interrupts`
+and resume the same `threadId` with a canonical `resume` array of `ResumeEntry` values.
+
+```json
+{
+  "threadId": "thread-1",
+  "messages": [],
+  "resume": [
+    {
+      "interruptId": "approval_1",
+      "status": "resolved",
+      "payload": {
+        "approved": true
+      }
+    }
+  ]
+}
+```
+
+`Interrupt` and `ResumeEntry` are AG-UI protocol models from `ag_ui.core`; Agent Framework does not define a
+separate interrupt model. New interrupted runs use `RUN_FINISHED.outcome.interrupts`, not a stable top-level
+`RUN_FINISHED.interrupt` field.
+
+## What is AG-UI?
+
+AG-UI is a protocol that enables:
+- **Remote agent hosting**: Host AI agents as web services that can be accessed by multiple clients
+- **Streaming responses**: Real-time streaming of agent responses using Server-Sent Events (SSE)
+- **Standardized communication**: Consistent message format for agent interactions
+- **Thread management**: Maintain conversation context across multiple requests
+- **Advanced features**: Human-in-the-loop, state management, tool rendering
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- Python 3.10 or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for DefaultAzureCredential)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+
+**Note**: These samples use `DefaultAzureCredential` for authentication. Make sure you're authenticated with Azure (e.g., via `az login`, or environment variables). For more information, see the [Azure Identity documentation](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential).
+
+> **Warning**
+> The AG-UI protocol is still under development and subject to change.
+> We will keep these samples updated as the protocol evolves.
+
+## Step 1: Creating an AG-UI Server
+
+The AG-UI server hosts your AI agent and exposes it via HTTP endpoints using FastAPI.
+
+### Install Required Packages
+
+```bash
+pip install agent-framework-ag-ui
+```
+
+Or using uv:
+
+```bash
+uv pip install agent-framework-ag-ui
+```
+
+### Server Code
+
+Create a file named `server.py`:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI server example."""
+
+import os
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatCompletionClient
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
+from fastapi import FastAPI
+
+# Read required configuration
+endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
+model = os.environ.get("AZURE_OPENAI_MODEL")
+api_key = os.environ.get("AZURE_OPENAI_API_KEY")
+
+if not endpoint:
+    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
+if not model:
+    raise ValueError("AZURE_OPENAI_MODEL environment variable is required")
+if not api_key:
+    raise ValueError("AZURE_OPENAI_API_KEY environment variable is required")
+
+# Create the AI agent
+agent = Agent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant.",
+    client=OpenAIChatCompletionClient(
+        azure_endpoint=endpoint,
+        model=model,
+        api_key=api_key,
+    ),
+)
+
+# Create FastAPI app
+app = FastAPI(title="AG-UI Server")
+
+# Register the AG-UI endpoint
+add_agent_framework_fastapi_endpoint(app, agent, "/")
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=5100)
+```
+
+### Key Concepts
+
+- **`add_agent_framework_fastapi_endpoint`**: Registers the AG-UI endpoint with automatic request/response handling and SSE streaming
+- **`Agent`**: The agent that will handle incoming requests
+- **FastAPI Integration**: Uses FastAPI's native async support for streaming responses
+- **Instructions**: The agent is created with default instructions, which can be overridden by client messages
+- **Configuration**: `OpenAIChatCompletionClient` can read from environment variables (`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_MODEL`, `AZURE_OPENAI_API_KEY`) or accept parameters directly
+
+**Alternative (simpler)**: Use environment variables only:
+
+```python
+# No need to read environment variables manually
+agent = Agent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant.",
+    client=OpenAIChatCompletionClient(),  # Reads from environment automatically
+)
+```
+
+### Configure and Run the Server
+
+Set the required environment variables:
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_MODEL="gpt-4o-mini"
+# Optional: Set API key if not using DefaultAzureCredential
+# export AZURE_OPENAI_API_KEY="your-api-key"
+```
+
+Run the server:
+
+```bash
+python server.py
+```
+
+Or using uvicorn directly:
+
+```bash
+uvicorn server:app --host 127.0.0.1 --port 5100
+```
+
+The server will start listening on `http://127.0.0.1:5100`.
+
+## Step 2: Creating an AG-UI Client
+
+The AG-UI client connects to the remote server and displays streaming responses. The `AGUIChatClient` is a built-in implementation that integrates with the Agent Framework's standard chat interface.
+
+### Install Required Packages
+
+The `AGUIChatClient` is included in the `agent-framework-ag-ui` package (already installed if you installed the server packages).
+
+```bash
+pip install agent-framework-ag-ui
+```
+
+### Client Code
+
+Create a file named `client.py`:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI client example using AGUIChatClient."""
+
+import asyncio
+import os
+
+from agent_framework.ag_ui import AGUIChatClient
+
+
+async def main():
+    """Main client loop demonstrating AGUIChatClient usage."""
+    # Get server URL from environment or use default
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+    print(f"Connecting to AG-UI server at: {server_url}\n")
+
+    # Create client with context manager for automatic cleanup
+    async with AGUIChatClient(endpoint=server_url) as client:
+        thread_id: str | None = None
+
+        try:
+            while True:
+                # Get user input
+                message = input("\nUser (:q or quit to exit): ")
+                if not message.strip():
+                    print("Request cannot be empty.")
+                    continue
+
+                if message.lower() in (":q", "quit"):
+                    break
+
+                # Send message and stream the response
+                print("\nAssistant: ", end="", flush=True)
+
+                # Use metadata to maintain conversation continuity
+                metadata = {"thread_id": thread_id} if thread_id else None
+
+                async for update in client.get_response(message, metadata=metadata, stream=True):
+                    # Extract thread ID from first update
+                    if not thread_id and update.additional_properties:
+                        thread_id = update.additional_properties.get("thread_id")
+                        if thread_id:
+                            print(f"\n[Thread: {thread_id}]")
+                            print("Assistant: ", end="", flush=True)
+
+                    # Stream text content as it arrives
+                    for content in update.contents:
+                        if content.type == "text" and content.text:
+                            print(content.text, end="", flush=True)
+
+                print()  # New line after response
+
+        except KeyboardInterrupt:
+            print("\n\nExiting...")
+        except Exception as e:
+            print(f"\nAn error occurred: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Key Concepts
+
+- **`AGUIChatClient`**: Built-in client that implements the Agent Framework's `BaseChatClient` interface
+- **Automatic Event Handling**: The client automatically converts AG-UI events to Agent Framework types
+- **Thread Management**: Pass `thread_id` in metadata to maintain conversation context across requests
+- **Streaming Responses**: Use `get_response(..., stream=True)` for real-time streaming or `get_response(..., stream=False)` for non-streaming
+- **Context Manager**: Use `async with` for automatic cleanup of HTTP connections
+- **Standard Interface**: Works with all Agent Framework patterns (Agent, tools, etc.)
+- **Hybrid Tool Execution**: Supports both client-side and server-side tools executing together in the same conversation
+
+### Configure and Run the Client
+
+Optionally set a custom server URL:
+
+```bash
+export AGUI_SERVER_URL="http://127.0.0.1:5100/"
+```
+
+Run the client (in a separate terminal):
+
+```bash
+python client.py
+```
+
+## Step 3: Testing the Complete System
+
+### Expected Output
+
+```
+$ python client.py
+Connecting to AG-UI server at: http://127.0.0.1:5100/
+
+User (:q or quit to exit): What is the capital of France?
+
+[Thread: abc123]
+Assistant: The capital of France is Paris. It is known for its rich history, culture,
+and iconic landmarks such as the Eiffel Tower and the Louvre Museum.
+
+User (:q or quit to exit): Tell me a fun fact about space
+```
+
+## Troubleshooting
+
+### Connection Refused
+
+Ensure the server is running before starting the client:
+
+```bash
+# Terminal 1
+python server.py
+
+# Terminal 2 (after server starts)
+python client.py
+```
+
+### Authentication Errors
+
+Make sure you're authenticated with Azure:
+
+```bash
+az login
+```
+
+Verify you have the correct role assignment on the Azure OpenAI resource.
+
+### Streaming Not Working
+
+Check that your client timeout is sufficient:
+
+```python
+httpx.AsyncClient(timeout=60.0)  # 60 seconds should be enough
+```
+
+For long-running agents, increase the timeout accordingly.
+
+### No Events Received
+
+Ensure you're using the correct `Accept` header:
+
+```python
+headers={"Accept": "text/event-stream"}
+```
+
+And parsing SSE format correctly (lines starting with `data: `).
+
+### Thread Context Lost
+
+The client automatically manages thread continuity. If context is lost:
+
+1. Check that `threadId` is being captured from `RUN_STARTED` events
+2. Ensure the same client instance is used across messages
+3. Verify the server is receiving the `thread_id` in subsequent requests
+
+### Event Type Mismatches
+
+Remember that event types are UPPERCASE with underscores (`RUN_STARTED`, not `run_started`) and field names are camelCase (`threadId`, not `thread_id`).
+
+### Import Errors
+
+Make sure all packages are installed:
+
+```bash
+pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn httpx
+```
+
+Or check your virtual environment is activated:
+
+```bash
+source venv/bin/activate  # Linux/macOS
+venv\Scripts\activate     # Windows
+```
@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI client example using AGUIChatClient.
+
+This example demonstrates how to use the AGUIChatClient to connect to
+a remote AG-UI server and interact with it using the Agent Framework's
+standard chat interface.
+"""
+
+import asyncio
+import os
+from typing import cast
+
+from agent_framework import ChatResponse, ChatResponseUpdate, Message, ResponseStream
+from agent_framework.ag_ui import AGUIChatClient
+
+
+async def main():
+    """Main client loop demonstrating AGUIChatClient usage."""
+    # Get server URL from environment or use default
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+    print(f"Connecting to AG-UI server at: {server_url}\n")
+    print("Using AGUIChatClient with automatic thread management and Agent Framework integration.\n")
+
+    # Create client with context manager for automatic cleanup
+    async with AGUIChatClient(endpoint=server_url) as client:
+        thread_id: str | None = None
+
+        try:
+            while True:
+                # Get user input
+                message = input("\nUser (:q or quit to exit): ")
+                if not message.strip():
+                    print("Request cannot be empty.")
+                    continue
+
+                if message.lower() in (":q", "quit"):
+                    break
+
+                # Send message and stream the response
+                print("\nAssistant: ", end="", flush=True)
+
+                # Use metadata to maintain conversation continuity
+                metadata = {"thread_id": thread_id} if thread_id else None
+
+                stream = client.get_response(
+                    [Message(role="user", contents=[message])],
+                    stream=True,
+                    options={"metadata": metadata} if metadata else None,
+                )
+                stream = cast(ResponseStream[ChatResponseUpdate, ChatResponse], stream)
+                async for update in stream:
+                    # Extract and display thread ID from first update
+                    if not thread_id and update.additional_properties:
+                        thread_id = update.additional_properties.get("thread_id")
+                        if thread_id:
+                            print(f"\n\033[93m[Thread: {thread_id}]\033[0m", end="", flush=True)
+                            print("\nAssistant: ", end="", flush=True)
+
+                    # Display text content as it streams
+                    for content in update.contents:
+                        if content.type == "text" and content.text:
+                            print(f"\033[96m{content.text}\033[0m", end="", flush=True)
+
+                    # Display finish reason if present
+                    if update.finish_reason:
+                        print(f"\n\033[92m[Finished: {update.finish_reason}]\033[0m", end="", flush=True)
+
+                print()  # New line after response
+
+        except KeyboardInterrupt:
+            print("\n\nExiting...")
+        except Exception as e:
+            print(f"\n\033[91mAn error occurred: {e}\033[0m")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,245 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Advanced AG-UI client example with tools and features.
+
+This example demonstrates advanced AGUIChatClient features including:
+- Tool/function calling
+- Non-streaming responses
+- Multiple conversation turns
+- Error handling
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import cast
+
+from agent_framework import ChatResponse, ChatResponseUpdate, Message, ResponseStream, tool
+from agent_framework.ag_ui import AGUIChatClient
+
+
+@tool
+def get_weather(location: str) -> str:
+    """Get the current weather for a location.
+
+    Args:
+        location: The city or location name
+    """
+    # Simulate weather lookup
+    weather_data = {
+        "seattle": "Rainy, 55°F",
+        "san francisco": "Foggy, 62°F",
+        "new york": "Sunny, 68°F",
+        "london": "Cloudy, 52°F",
+    }
+    return weather_data.get(location.lower(), f"Weather data not available for {location}")
+
+
+@tool
+def calculate(a: float, b: float, operation: str) -> str:
+    """Perform basic arithmetic operations.
+
+    Args:
+        a: First number
+        b: Second number
+        operation: Operation to perform (add, subtract, multiply, divide)
+    """
+    try:
+        if operation == "add":
+            result = a + b
+        elif operation == "subtract":
+            result = a - b
+        elif operation == "multiply":
+            result = a * b
+        elif operation == "divide":
+            result = a / b
+        else:
+            return f"Unsupported operation: {operation}"
+        return f"The result is: {result}"
+    except Exception as e:
+        return f"Error calculating: {e}"
+
+
+async def streaming_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate streaming responses."""
+    print("\n" + "=" * 60)
+    print("STREAMING EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: Tell me a short joke\n")
+    print("Assistant: ", end="", flush=True)
+
+    stream = client.get_response(
+        [Message(role="user", contents=["Tell me a short joke"])],
+        stream=True,
+        options={"metadata": metadata} if metadata else None,
+    )
+    stream = cast(ResponseStream[ChatResponseUpdate, ChatResponse], stream)
+    async for update in stream:
+        if not thread_id and update.additional_properties:
+            thread_id = update.additional_properties.get("thread_id")
+
+        for content in update.contents:
+            if content.type == "text" and content.text:  # type: ignore[attr-defined]
+                print(content.text, end="", flush=True)  # type: ignore[attr-defined]
+
+    print("\n")
+    return thread_id
+
+
+async def non_streaming_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate non-streaming responses."""
+    print("\n" + "=" * 60)
+    print("NON-STREAMING EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: What is 2 + 2?\n")
+
+    response = await client.get_response([Message(role="user", contents=["What is 2 + 2?"])], metadata=metadata)
+
+    print(f"Assistant: {response.text}")
+
+    if response.additional_properties:
+        thread_id = response.additional_properties.get("thread_id")
+        print(f"\n[Thread: {thread_id}]")
+
+    return thread_id
+
+
+async def tool_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate sending tool definitions to the server.
+
+    IMPORTANT: When using AGUIChatClient directly (without Agent wrapper):
+    - Tools are sent as DEFINITIONS only
+    - No automatic client-side execution (no function invocation middleware)
+    - Server must have matching tool implementations to execute them
+
+    For CLIENT-SIDE tool execution (like .NET AGUIClient sample):
+    - Use Agent wrapper with tools
+    - See client_with_agent.py for the hybrid pattern
+    - Agent middleware intercepts and executes client tools locally
+    - Server can have its own tools that execute server-side
+    - Both client and server tools work together in same conversation
+
+    This example sends tool definitions and assumes server-side execution.
+    """
+    print("\n" + "=" * 60)
+    print("TOOL DEFINITION EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: What's the weather in Seattle?\n")
+    print("Sending tool definitions to server...")
+    print("(Server must be configured with matching tools to execute them)\n")
+
+    response = await client.get_response(
+        [Message(role="user", contents=["What's the weather in Seattle?"])],
+        tools=[get_weather, calculate],
+        metadata=metadata,
+    )
+
+    print(f"Assistant: {response.text}")
+
+    # Show tool calls if any
+    tool_called = False
+    for message in response.messages:
+        for content in message.contents:
+            if content.type == "function_call":  # type: ignore[attr-defined]
+                print(f"\n[Tool Called: {content.name}]")  # type: ignore[attr-defined]
+                tool_called = True
+
+    if not tool_called:
+        print("\n[Note: No tools were called - server may not be configured for tool execution]")
+
+    if response.additional_properties:
+        thread_id = response.additional_properties.get("thread_id")
+
+    return thread_id
+
+
+async def conversation_example(client: AGUIChatClient):
+    """Demonstrate multi-turn conversation.
+
+    Note: Conversation continuity depends on the server maintaining thread state.
+    Some servers may require explicit message history to be sent with each request.
+    """
+    print("\n" + "=" * 60)
+    print("MULTI-TURN CONVERSATION EXAMPLE")
+    print("=" * 60)
+    print("\nNote: This example uses thread_id for context. Server must support thread-based state.\n")
+
+    # First turn
+    print("User: My name is Alice\n")
+    response1 = await client.get_response([Message(role="user", contents=["My name is Alice"])])
+    print(f"Assistant: {response1.text}")
+    thread_id = response1.additional_properties.get("thread_id")
+    print(f"\n[Thread: {thread_id}]")
+
+    # Second turn - using same thread
+    print("\nUser: What's my name?\n")
+    response2 = await client.get_response(
+        [Message(role="user", contents=["What's my name?"])], options={"metadata": {"thread_id": thread_id}}
+    )
+    print(f"Assistant: {response2.text}")
+
+    # Check if context was maintained
+    if "alice" not in response2.text.lower():
+        print("\n[Note: Server may not maintain thread context - consider using Agent for history management]")
+
+    # Third turn
+    print("\nUser: Can you also tell me what 10 * 5 is?\n")
+    response3 = await client.get_response(
+        [Message(role="user", contents=["Can you also tell me what 10 * 5 is?"])],
+        options={"metadata": {"thread_id": thread_id}},
+        tools=[calculate],
+    )
+    print(f"Assistant: {response3.text}")
+
+
+async def main():
+    """Run all examples."""
+    # Get server URL from environment or use default
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+
+    print("=" * 60)
+    print("AG-UI Chat Client Advanced Examples")
+    print("=" * 60)
+    print(f"\nServer: {server_url}")
+    print("\nThese examples demonstrate various AGUIChatClient features:")
+    print("  1. Streaming responses")
+    print("  2. Non-streaming responses")
+    print("  3. Tool/function calling")
+    print("  4. Multi-turn conversations")
+
+    try:
+        async with AGUIChatClient(endpoint=server_url) as client:
+            # Run examples in sequence
+            thread_id = await streaming_example(client)
+            thread_id = await non_streaming_example(client, thread_id)
+            await tool_example(client, thread_id)
+
+            # Separate conversation with new thread
+            await conversation_example(client)
+
+            print("\n" + "=" * 60)
+            print("All examples completed successfully!")
+            print("=" * 60)
+
+    except ConnectionError as e:
+        print(f"\n\033[91mConnection Error: {e}\033[0m")
+        print("\nMake sure an AG-UI server is running at the specified endpoint.")
+    except Exception as e:
+        print(f"\n\033[91mError: {e}\033[0m")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,150 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example showing Agent with AGUIChatClient for hybrid tool execution.
+
+This demonstrates the HYBRID pattern matching .NET AGUIClient implementation:
+
+1. AgentSession Pattern (like .NET):
+   - Create session with agent.create_session()
+   - Pass session to agent.run(stream=True) on each turn
+   - Session maintains conversation context via context providers
+
+2. Hybrid Tool Execution:
+   - AGUIChatClient uses function invocation mixin
+   - Client-side tools (get_weather) can execute locally when server requests them
+   - Server may also have its own tools that execute server-side
+   - Both work together: server LLM decides which tool to call, decorator handles client execution
+
+This matches .NET pattern: session maintains state, tools execute on appropriate side.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from agent_framework import Agent, tool
+from agent_framework.ag_ui import AGUIChatClient
+
+# Enable debug logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+@tool(description="Get the current weather for a location.")
+def get_weather(location: str) -> str:
+    """Get the current weather for a location.
+
+    Args:
+        location: The city or location name
+    """
+    print(f"[CLIENT] get_weather tool called with location: {location}")
+    weather_data = {
+        "seattle": "Rainy, 55°F",
+        "san francisco": "Foggy, 62°F",
+        "new york": "Sunny, 68°F",
+        "london": "Cloudy, 52°F",
+    }
+    result = weather_data.get(location.lower(), f"Weather data not available for {location}")
+    print(f"[CLIENT] get_weather returning: {result}")
+    return result
+
+
+async def main():
+    """Demonstrate Agent + AGUIChatClient hybrid tool execution.
+
+    This matches the .NET pattern from Program.cs where:
+    - AIAgent agent = chatClient.CreateAIAgent(tools: [...])
+    - AgentSession session = agent.CreateSession()
+    - RunStreamingAsync(messages, session)
+
+    Python equivalent:
+    - agent = Agent(client=AGUIChatClient(...), tools=[...])
+    - session = agent.create_session()  # Creates session
+    - agent.run(message, stream=True, session=session)  # Session tracks context
+    """
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+
+    print("=" * 70)
+    print("Agent + AGUIChatClient: Hybrid Tool Execution")
+    print("=" * 70)
+    print(f"\nServer: {server_url}")
+    print("\nThis example demonstrates:")
+    print("  1. AgentSession maintains conversation state (like .NET)")
+    print("  2. Client-side tools execute locally via function invocation mixin")
+    print("  3. Server may have additional tools that execute server-side")
+    print("  4. HYBRID: Client and server tools work together simultaneously\n")
+
+    try:
+        # Create remote client in async context manager
+        async with AGUIChatClient(endpoint=server_url) as remote_client:
+            # Wrap in Agent for conversation history management
+            agent = Agent(
+                name="remote_assistant",
+                instructions="You are a helpful assistant. Remember user information across the conversation.",
+                client=remote_client,
+                tools=[get_weather],
+            )
+
+            # Create a session to maintain conversation state (like .NET AgentSession)
+            session = agent.create_session()
+
+            print("=" * 70)
+            print("CONVERSATION WITH HISTORY")
+            print("=" * 70)
+
+            # Turn 1: Introduce
+            print("\nUser: My name is Alice and I live in Seattle\n")
+            async for chunk in agent.run("My name is Alice and I live in Seattle", stream=True, session=session):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 2: Ask about name (tests history)
+            print("User: What's my name?\n")
+            async for chunk in agent.run("What's my name?", stream=True, session=session):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 3: Ask about location (tests history)
+            print("User: Where do I live?\n")
+            async for chunk in agent.run("Where do I live?", stream=True, session=session):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 4: Test client-side tool (get_weather is client-side)
+            print("User: What's the weather forecast for today in Seattle?\n")
+            async for chunk in agent.run(
+                "What's the weather forecast for today in Seattle?",
+                stream=True,
+                session=session,
+            ):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 5: Test server-side tool (get_time_zone is server-side only)
+            print("User: What time zone is Seattle in?\n")
+            async for chunk in agent.run("What time zone is Seattle in?", stream=True, session=session):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+    except ConnectionError as e:
+        print(f"\n\033[91mConnection Error: {e}\033[0m")
+        print("\nMake sure an AG-UI server is running at the specified endpoint.")
+    except Exception as e:
+        print(f"\n\033[91mError: {e}\033[0m")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI server example with server-side tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from agent_framework import Agent, tool
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
+from agent_framework.openai import OpenAIChatCompletionClient
+from dotenv import load_dotenv
+from fastapi import Depends, FastAPI, HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+load_dotenv()
+
+# Enable debug logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+# Read required configuration
+endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
+model = os.environ.get("AZURE_OPENAI_MODEL")
+
+if not endpoint:
+    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
+if not model:
+    raise ValueError("AZURE_OPENAI_MODEL environment variable is required")
+
+
+# ============================================================================
+# AUTHENTICATION EXAMPLE
+# ============================================================================
+# This demonstrates how to secure the AG-UI endpoint with API key authentication.
+# In production, you should use a more robust authentication mechanism such as:
+# - OAuth 2.0 / OpenID Connect
+# - JWT tokens with proper validation
+# - Azure AD / Entra ID integration
+# - Your organization's identity provider
+#
+# The API key should be stored securely (e.g., Azure Key Vault, environment variables)
+# and rotated regularly.
+# ============================================================================
+
+# API key header configuration
+API_KEY_HEADER = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+# Get the expected API key from environment variable
+# In production, use a secrets manager like Azure Key Vault
+EXPECTED_API_KEY = os.environ.get("AG_UI_API_KEY")
+
+
+async def verify_api_key(api_key: str | None = Security(API_KEY_HEADER)) -> None:
+    """Verify the API key provided in the request header.
+
+    Args:
+        api_key: The API key from the X-API-Key header
+
+    Raises:
+        HTTPException: If the API key is missing or invalid
+    """
+    if not EXPECTED_API_KEY:
+        # If no API key is configured, log a warning but allow the request
+        # This maintains backward compatibility but warns about the security risk
+        logger.warning(
+            "AG_UI_API_KEY environment variable not set. "
+            "The endpoint is accessible without authentication. "
+            "Set AG_UI_API_KEY to enable API key authentication."
+        )
+        return
+
+    if not api_key:
+        raise HTTPException(
+            status_code=401,
+            detail="Missing API key. Provide X-API-Key header.",
+        )
+
+    if api_key != EXPECTED_API_KEY:
+        raise HTTPException(
+            status_code=403,
+            detail="Invalid API key.",
+        )
+
+
+# Server-side tool (executes on server)
+@tool(description="Get the time zone for a location.")
+def get_time_zone(location: str) -> str:
+    """Get the time zone for a location.
+
+    Args:
+        location: The city or location name
+    """
+    print(f"[SERVER] get_time_zone tool called with location: {location}")
+    timezone_data = {
+        "seattle": "Pacific Time (UTC-8)",
+        "san francisco": "Pacific Time (UTC-8)",
+        "new york": "Eastern Time (UTC-5)",
+        "london": "Greenwich Mean Time (UTC+0)",
+    }
+    result = timezone_data.get(location.lower(), f"Time zone data not available for {location}")
+    print(f"[SERVER] get_time_zone returning: {result}")
+    return result
+
+
+# Create the AI agent with ONLY server-side tools
+# IMPORTANT: Do NOT include tools that the client provides!
+# In this example:
+# - get_time_zone: SERVER-ONLY tool (only server has this)
+# - get_weather: CLIENT-ONLY tool (client provides this, server should NOT include it)
+# The client will send get_weather tool metadata so the LLM knows about it,
+# and the function invocation mixin on AGUIChatClient will execute it client-side.
+# This matches the .NET AG-UI hybrid execution pattern.
+agent = Agent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant. Use get_weather for weather and get_time_zone for time zones.",
+    client=OpenAIChatCompletionClient(
+        azure_endpoint=endpoint,
+        model=model,
+    ),
+    tools=[get_time_zone],  # ONLY server-side tools
+)
+
+# Create FastAPI app
+app = FastAPI(title="AG-UI Server")
+
+# Register the AG-UI endpoint with authentication
+# The dependencies parameter accepts FastAPI Depends() objects that run before the handler
+add_agent_framework_fastapi_endpoint(
+    app,
+    agent,
+    "/",
+    dependencies=[Depends(verify_api_key)],
+)
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=5100, log_level="debug", access_log=True)