Build a Frontend for your Microsoft Agent Framework (Python) Agents with AG-UI

npx copilotkit@latest init -m microsoft-agent-framework-py

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

# Using bun
bun install

OPENAI_API_KEY=sk-...your-openai-key-here...
OPENAI_CHAT_MODEL_ID=gpt-4o-mini

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=gpt-4o-mini
# If you are not relying on az login:
# AZURE_OPENAI_API_KEY=...

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

# Using bun
bun run dev

uv pip install agent-framework, agent-framework-ag-ui, azure-identity

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

# STATE_SCHEMA: Defines the structure of agent state 
STATE_SCHEMA: dict[str, object] = {
    "proverbs": {
        "type": "array",  # Proverbs is a list/array of items
        "items": {"type": "string"},  # Each item in the array is a string
        "description": "Ordered list of the user's saved proverbs.",  # Human-readable description
    }
}

// ...

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

# PREDICT_STATE_CONFIG: Maps state fields to the tools that modify them.
# This tells your agent which tool function to call when the agent needs to update
# a particular piece of state, and which argument of that tool contains the new state value.
PREDICT_STATE_CONFIG: dict[str, dict[str, str]] = {
    "proverbs": {
        "tool": "update_proverbs",  # The name of the tool function that updates proverbs
        "tool_argument": "proverbs",  # The parameter name in that tool that receives the new proverb list
    }
}

// ...

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

# @ai_function decorator: Marks this as a tool that the AI agent can call.
# The name and description help the LLM understand when and how to use this tool.
@ai_function(
    name="update_proverbs",
    description=(
        "Replace the entire list of proverbs with the provided values. "
        "Always include every proverb you want to keep."
    ),
)
def update_proverbs(
    proverbs: Annotated[
        list[str],  # The function accepts a list of strings
        Field(
            description=(
                # This description guides the LLM on how to use this parameter correctly.
                # Emphasises that this should be the COMPLETE list, not a partial update.
                "The complete source of truth for the user's proverbs. "
                "Maintain ordering and include the full list on each call."
            )
        ),
    ],
) -> str:
    """
    Persist the provided set of proverbs.

    Returns:
        A confirmation message indicating how many proverbs are now tracked.
    """
    return f"Proverbs updated. Tracking {len(proverbs)} item(s)."

# Weather tool: Demonstrates frontend UI integration through tool calls.
# When the agent calls this function, CopilotKit can render a weather card in the UI.
@ai_function(
    name="get_weather",
    description="Share a quick weather update for a location. Use this to render the frontend weather card.",
)
def get_weather(
    location: Annotated[str, Field(description="The city or region to describe. Use fully spelled out names.")],
) -> str:
    """
    Return a short natural language weather summary.

    Args:
        location: The city or region name to get the weather for.

    Returns:
        A friendly weather description string that can be displayed to the user.
    """
    # Normalise the location string: remove whitespace, capitalise words
    normalized = location.strip().title() or "the requested location"

    # Return a mock weather response (in production, this would query a real API)
    return (
        f"The weather in {normalised} is mild with a light breeze. "
        "Skies are mostly clear—perfect for planning something fun."
    )

# Human-in-the-loop tool: Demonstrates requiring explicit user approval before executing.
# The approval_mode="always_require" parameter ensures this function will pause execution
# and wait for the user to explicitly approve or reject the action via the UI.
@ai_function(
    name="go_to_moon",
    description="Request a playful human-in-the-loop confirmation before launching a mission to the moon.",
    approval_mode="always_require",  # CRITICAL: Forces user approval before this tool executes
)
def go_to_moon() -> str:
    """
    Request human approval before continuing.


    Returns:
        A message confirming the approval request has been initiated.
    """
    return "Mission control requested. Awaiting human approval for the lunar launch."

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

def create_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
    """
    Instantiate the Microsoft Agent Framework with AG-UI.

    This is the main entry point for creating the agent. It configures the base ChatAgent
    with instructions and tools, then wraps it in an AgentFrameworkAgent for AG-UI integration.

    Args:
        chat_client: The chat client protocol implementation that handles LLM communication.

    Returns:
        A fully configured AgentFrameworkAgent ready to handle user interactions.
    """
    # Step 1: Create the base ChatAgent with Microsoft Agent Framework
    # This agent handles the core conversational logic and tool execution
    base_agent = ChatAgent(
        name="proverbs_agent",  # Internal identifier for this agent

        # System instructions: These guide the agent's behaviour throughout the conversation.
        # The instructions are carefully crafted to ensure proper state management,
        # tool usage, and user experience.
        instructions=dedent(
            """
            You help users brainstorm, organize, and refine proverbs while coordinating UI updates.

            // ...

            """.strip()
        ),

        # The chat client handles actual LLM API calls (e.g., to OpenAI, Azure OpenAI, etc.)
        chat_client=chat_client,

        # Tools: These are the functions the agent can call to perform actions
        tools=[update_proverbs, get_weather, go_to_moon],
    )

    // ...

from __future__ import annotations

from textwrap import dedent
from typing import Annotated

# Import core agent framework components for building conversational AI agents
from agent_framework import ChatAgent, ChatClientProtocol, ai_function
# Import CopilotKit integration layer that bridges Agent Framework with the frontend
from agent_framework_ag_ui import AgentFrameworkAgent
from pydantic import Field

// ...

def create_agent(chat_client: ChatClientProtocol) -> AgentFrameworkAgent:
    """
    Instantiate the Microsoft Agent Framework with AG-UI.

    This is the main entry point for creating the agent. It configures the base ChatAgent
    with instructions and tools, then wraps it in an AgentFrameworkAgent for CopilotKit integration.

    Args:
        chat_client: The chat client protocol implementation that handles LLM communication.

    Returns:
        A fully configured AgentFrameworkAgent ready to handle user interactions.
    """
    # Step 1: Create the base ChatAgent with Microsoft Agent Framework
    # This agent handles the core conversational logic and tool execution

    // ...

    # Step 2: Wrap the base agent in an AgentFrameworkAgent for AG-UI integration
    # This wrapper adds CopilotKit-specific features like state sync and frontend coordination
    return AgentFrameworkAgent(
        agent=base_agent,  # The underlying ChatAgent we just configured

        name="CopilotKitMicrosoftAgentFrameworkAgent",  # Display name for the agent
        description="Manages proverbs, weather snippets, and human-in-the-loop moon launches.",

        # STATE_SCHEMA tells CopilotKit what state this agent manages
        state_schema=STATE_SCHEMA,

        # PREDICT_STATE_CONFIG maps state fields to the tools that update them
        predict_state_config=PREDICT_STATE_CONFIG,

        # require_confirmation=False means the agent can update the state and continue
        # without waiting for explicit user confirmation after each state change.
        # This allows for smoother conversational flow.
        require_confirmation=False,
    )

from __future__ import annotations

import os

# Uvicorn: ASGI server for running FastAPI applications
import uvicorn
# ChatClientProtocol: Interface that all chat clients must implement
from agent_framework._clients import ChatClientProtocol

// ...

# Load environment variables from .env file (must be done before accessing os.getenv)
# This allows developers to configure API keys and endpoints without hardcoding them
load_dotenv()

def _build_chat_client() -> ChatClientProtocol:
    """
    Build and configure the appropriate chat client based on environment variables.

    Returns:
        ChatClientProtocol: A configured chat client ready to communicate with an LLM.

    Raises:
        RuntimeError: If credentials are missing or invalid.
    """
    try:
        # Option 1: Azure OpenAI Service
        # Check if Azure OpenAI endpoint is configured
        if bool(os.getenv("AZURE_OPENAI_ENDPOINT")):
            # Azure OpenAI uses deployment names instead of model IDs
            # Deployments are custom instances of models you create in Azure
            deployment_name = os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME", "gpt-4o-mini")

            return AzureOpenAIChatClient(
                # DefaultAzureCredential tries multiple authentication methods:
                # 1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, etc.)
                # 2. Managed Identity (if running on Azure infrastructure)
                # 3. Azure CLI credentials (for local development)
                credential=DefaultAzureCredential(),

                # The name of your deployed model in Azure OpenAI Studio
                deployment_name=deployment_name,

                # Your Azure OpenAI resource endpoint (e.g., https://my-resource.openai.azure.com/)
                endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
            )

        # Option 2: OpenAI API (public service)
        # Check if OpenAI API key is configured
        if bool(os.getenv("OPENAI_API_KEY")):
            return OpenAIChatClient(
                # Model identifier from OpenAI's catalogue (e.g., gpt-4o-mini, gpt-4, etc.)
                model_id=os.getenv("OPENAI_CHAT_MODEL_ID", "gpt-4o-mini"),

                # Your OpenAI API key from platform.openai.com
                api_key=os.getenv("OPENAI_API_KEY"),
            )

        # If neither Azure nor OpenAI credentials are found, raise an error
        raise ValueError("Either AZURE_OPENAI_ENDPOINT or OPENAI_API_KEY environment variable is required")

    except Exception as exc:  # pragma: no cover
        # Catch any initialization errors and provide a helpful message
        raise RuntimeError