Easily Build a Frontend for your AWS Strands Agents using AG-UI in 30 minutes

npx copilotkit@latest create -f aws-strands-py

# Using pnpm (recommended)
pnpm install

# Using npm
npm install

# Using yarn
yarn install

# Using bun
bun install

OPENAI_API_KEY="your-open-api-key-here”

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

# Using bun
bun run dev

uv pip install ag-ui-protocol strands-agents[OpenAI] strands-agents-tools ag_ui_strands

# AG-UI / Strands integration helpers:
# - StrandsAgent: Wrapper that makes a Strands Agent compatible with AG-UI protocol
# - StrandsAgentConfig: Configuration for shared state and tool behaviors
# - ToolBehavior: Defines how specific tools interact with the AG-UI state system
# - create_strands_app: Factory function that creates a FastAPI application
from ag_ui_strands import (
    StrandsAgent,
    StrandsAgentConfig,
    ToolBehavior,
    create_strands_app,
)

# dotenv: Loads environment variables from a .env file for local development
from dotenv import load_dotenv

# Pydantic: Used for data validation and schema definition
from pydantic import BaseModel, Field

# Strands SDK:
# - Agent: The core agent class that orchestrates LLM interactions
# - tool: Decorator to mark functions as tools the agent can call
from strands import Agent, tool

# OpenAI model wrapper from Strands for using GPT models
from strands.models.openai import OpenAIModel

// ...

# Pydantic: Used for data validation and schema definition
from pydantic import BaseModel, Field

// ...

class ProverbsList(BaseModel):
    """Pydantic model representing the entire proverbs list.

    We use a dedicated model to validate tool inputs for `update_proverbs`.
    The `proverbs` field is a list of strings describing the stored proverbs.
    """

    # The proverbs field is a list of strings with a description for the LLM
    proverbs: List[str] = Field(description="The complete list of proverbs")

 // ...

// ...

@tool
def get_weather(location: str):
    """Backend tool example: returns weather information for a location.

    This is a simple synchronous tool demonstrating a backend operation. In a
    real app this would call an external weather API. Here it returns a JSON
    string for simplicity so agents and UI can display structured data.

    Args:
        location: The location to get weather for (e.g., "Seattle, WA")

    Returns:
        A JSON string containing weather information.
    """
    # Return a JSON-encoded placeholder response
    # In production, this would call an actual weather API like OpenWeatherMap
    return json.dumps({"location": "70 degrees"})

@tool
def set_theme_color(theme_color: str):
    """Frontend-only tool example: request a UI theme color change.

    Frontend tools are declared on the backend so the agent can request UI
    actions, but actual execution happens in the browser via a frontend
    integration (e.g., `useFrontendTool`). Because the frontend performs the
    action, this backend implementation returns `None`.

    Args:
        theme_color: CSS color (hex, name, or rgb) that the UI should apply
    """
    # Return None because the actual implementation is in the frontend
    # The frontend will intercept this tool call and apply the theme change
    return None

@tool
def update_proverbs(proverbs_list: ProverbsList):
    """Backend tool: replace the entire proverbs list.

    IMPORTANT: This tool expects the complete list of proverbs, not just
    additions. When the UI or user wants to modify the list, always send the
    full array so the backend can store a canonical snapshot.

    Args:
        proverbs_list: A validated `ProverbsList` instance containing the
                        complete array of proverbs.

    Returns:
        A success message string on completion.
    """
    # In a real app, this would persist to a DB. Here we return success.
    # The state synchronization happens via the ToolBehavior config below.
    return "Proverbs updated successfully."

 // ...

// ...

def build_proverbs_prompt(input_data, user_message: str) -> str:
    """Build a model prompt that includes the current proverbs state.

    When the agent composes messages for the model, we inject the current
    `proverbs` array into the prompt so the model can reference or modify it.

    This function acts as a "state context builder" - it takes the current
    shared state and incorporates it into the prompt sent to the LLM.

    Args:
        input_data: The shared state container (may include a `state` key)
        user_message: The user's raw request/message

    Returns:
        The combined prompt string includes proverbs when available.
    """
    # Step 5a: Try to extract the state dictionary from input_data
    state_dict = getattr(input_data, "state", None)

    # Step 5b: Check if we have a valid state with proverbs
    if isinstance(state_dict, dict) and "proverbs" in state_dict:
        # Step 5c: Pretty-print the proverbs array for the model to read easily
        # Using indent=2 makes the JSON human-readable in the prompt
        proverbs_json = json.dumps(state_dict["proverbs"], indent=2)

        # Step 5d: Combine the proverbs context with the user message
        return (
            f"Current proverbs list:\n{proverbs_json}\n\nUser request: {user_message}"
        )

    # Step 5e: Fall back to the plain user message if no proverbs state is available
    return user_message

async def proverbs_state_from_args(context):
    """Extract a `{'proverbs': [...]}` snapshot from tool arguments.

    This function is used by the shared state system when the `update_proverbs`
    tool runs. It inspects the tool input and returns a small dictionary
    containing only the `proverbs` array so AG-UI can update its local state.

    This is an async function because AG-UI's state handling may involve
    async operations in more complex scenarios.

    Args:
        context: ToolResultContext containing `tool_input` (string or dict)

    Returns:
        A dictionary like `{"proverbs": [...]}` or `None` on error.
    """
    try:
        # Step 5f: Get the raw tool input from the context
        tool_input = context.tool_input

        # Step 5g: If the tool input was serialized to a string, parse it back
        # This handles cases where the LLM sends the input as a JSON string
        if isinstance(tool_input, str):
            tool_input = json.loads(tool_input)

        # Step 5h: Some call sites may package the list under `proverbs_list` key
        # This provides flexibility in how the data is structured
        proverbs_data = tool_input.get("proverbs_list", tool_input)

        # Step 5i: Ensure we extract the array safely with proper type checking
        if isinstance(proverbs_data, dict):
            proverbs_array = proverbs_data.get("proverbs", [])
        else:
            proverbs_array = []

        # Step 5j: Return the state snapshot in the expected format
        return {"proverbs": proverbs_array}
    except Exception:
        # Step 5k: Return None to indicate we couldn't build a valid state snapshot
        # AG-UI will handle this gracefully and not update the state
        return None

    // ...

// ...

shared_state_config = StrandsAgentConfig(
    # Step 6a: Inject proverbs into the prompt using the builder function above
    # This ensures the LLM always has context about the current proverbs list
    state_context_builder=build_proverbs_prompt,

    # Step 6b: Define tool-specific behaviors for AG-UI integration
    # This dictionary maps tool names to their ToolBehavior configurations
    tool_behaviors={
        "update_proverbs": ToolBehavior(
            # Step 6c: Skip messages snapshot to avoid redundant state updates
            # When this is True, the tool result won't trigger a full message sync
            skip_messages_snapshot=True,

            # Step 6d: Use our custom state extractor function
            # This tells AG-UI how to extract state changes from tool arguments
            state_from_args=proverbs_state_from_args,
        )
    },
)

// ...

// ...

# Step 7a: Retrieve the OpenAI API key from environment variables
# Default to empty string if not set (will cause authentication errors)
api_key = os.getenv("OPENAI_API_KEY", "")

# Step 7b: Create the OpenAI model instance with configuration
model = OpenAIModel(
    # Pass API key through client_args for the underlying OpenAI client
    client_args={"api_key": api_key},
    # Use GPT-4o (the optimized version); change as appropriate for your account
    model_id="gpt-4o",
)

// ...

// ...

system_prompt = (
    "You are a helpful and wise assistant who helps manage a collection of proverbs."
)

// ...

// ...

strands_agent = Agent(
    model=model,                                          # The LLM to use
    system_prompt=system_prompt,                          # Agent's persona
    tools=[update_proverbs, get_weather, set_theme_color],  # Available tools
)

// ...

// ...

# Step 9a: Create a StrandsAgent wrapper that adds AG-UI capabilities
agui_agent = StrandsAgent(
    agent=strands_agent,       # The underlying Strands agent
    name="proverbs_agent",     # Unique identifier for this agent
    description="A proverbs assistant that collaborates with you to manage proverbs",
    config=shared_state_config,  # Shared state and tool behavior configuration
)

// ...

// ...

app = create_strands_app(agui_agent, "/")

if __name__ == "__main__":
    # Step 11a: Import uvicorn ASGI server (only needed when running directly)
    import uvicorn

    # Step 11b: Start the development server with auto-reload enabled
    # - "main:app": Module and app variable reference for uvicorn
    # - host="0.0.0.0": Listen on all network interfaces
    # - port=8000: Default HTTP port for development
    # - reload=True: Auto-restart on code changes (development mode)
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/client