Agent Groups & Handoffs¶

from litestar_mcp.agent import Agent, AgentGroup

barista = Agent(
    name="barista",
    description="Prepares coffee drinks, looks up menu pricing, and manages customer orders.",
    instructions="You are the lead barista. Handle menu questions and beverage customizations.",
    skills=[BaristaSkillController],
)

concierge = Agent(
    name="concierge",
    description="Greets customers and routes coffee questions to the barista specialist.",
    instructions="Greet customers warmly. Delegate ordering and coffee questions to the barista.",
)

coffee_group = AgentGroup(
    coordinator=concierge,
    specialists=[barista],
)

"""Executable reference example: Coffee Shop Barista Agent with Litestar MCP."""

from typing import Any

from litestar import Litestar

from litestar_mcp import (
    LitestarMCP,
    PromptController,
    PromptMessage,
    SkillController,
    prompt,
    tool,
)
from litestar_mcp.agent import (
    Agent,
    AgentChatController,
    AgentGroup,
    AgentRuntime,
    GoogleGenAIClient,
)


class BaristaSkillController(SkillController):
    """Barista skill providing beverage menu lookup and order preparation tools."""

    name = "barista"
    description = "Specialized skills for querying menu items and preparing coffee orders"
    instructions = (
        "Barista Operational Grounding:\n"
        "- Suggest seasonal single-origin roasts when asked for recommendations.\n"
        "- Confirm milk alternatives (oat, almond, soy) before finalizing espresso drinks.\n"
        "- Never accept orders for items outside the published menu.\n"
    )

    def __init__(self, owner: Any = None) -> None:
        """Initialize the barista skill with catalog menu and empty order list."""
        super().__init__(owner)
        self.menu: dict[str, dict[str, Any]] = {
            "espresso": {"price": 3.50, "roast": "Ethiopian Yirgacheffe", "decaf_available": True},
            "flat_white": {"price": 4.75, "roast": "Guatemalan Antigua", "decaf_available": True},
            "cold_brew": {"price": 5.00, "roast": "Colombian Huila", "decaf_available": False},
        }
        self.orders: list[dict[str, Any]] = []

    @tool
    def get_menu(self) -> dict[str, dict[str, Any]]:
        """Retrieve available coffee drinks and pricing."""
        return self.menu

    @tool
    def place_order(self, beverage: str, milk: str = "whole", shots: int = 2) -> dict[str, Any]:
        """Place a customized beverage order."""
        bev = beverage.lower().replace(" ", "_")
        if bev not in self.menu:
            return {"status": "error", "message": f"'{beverage}' is not on the menu."}

        order_record = {
            "order_id": len(self.orders) + 1,
            "beverage": bev,
            "milk": milk,
            "shots": shots,
            "price": self.menu[bev]["price"],
            "status": "in_queue",
        }
        self.orders.append(order_record)
        return {"status": "success", "order": order_record}


class CoffeePromptController(PromptController):
    """Prompt templates for greeting customers and authoring seasonal menus."""

    prefix = "coffee"
    instructions = (
        "Persona: Warm, knowledgeable neighborhood specialty coffee barista.\n"
        "Tone: Welcoming, concise, and focused on quality craft brewing.\n"
    )

    @prompt(title="Welcome Greeting", description="Greet a customer and introduce daily specials.")
    def welcome_customer(self, customer_name: str = "Friend") -> str:
        """Generate a warm barista greeting."""
        return f"Welcome to the coffee bar, {customer_name}! What can we craft for you today?"

    @prompt(title="Tasting Notes", description="Generate tasting notes for a given roast.")
    def roast_notes(self, roast_name: str) -> list[PromptMessage]:
        """Produce structured tasting notes for single-origin coffees."""
        return [
            PromptMessage.user(
                f"Produce professional SCA-style tasting notes and brewing parameters for `{roast_name}`."
            )
        ]


def create_model_client() -> GoogleGenAIClient:
    """Instantiate GoogleGenAIClient with a thinking budget and low temperature."""
    return GoogleGenAIClient(thinking_budget=2048, temperature=0.2)


def setup_coffee_agent_group() -> AgentGroup:
    """Build and configure the coffee shop agent group with specialists."""
    barista_agent = Agent(
        name="barista",
        description="Prepares coffee drinks, looks up menu pricing, and manages customer orders.",
        instructions="You are the lead barista. Handle menu questions and beverage customizations.",
        skills=[BaristaSkillController],
    )

    triage_coordinator = Agent(
        name="concierge",
        description="Greets customers and routes coffee questions to the barista specialist.",
        instructions="Greet customers warmly. Delegate ordering and coffee questions to the barista.",
    )

    return AgentGroup(
        coordinator=triage_coordinator,
        specialists=[barista_agent],
    )


app = Litestar(
    route_handlers=[AgentChatController, CoffeePromptController, BaristaSkillController],
    plugins=[
        AgentRuntime(setup_coffee_agent_group(), default_model=create_model_client()),
        LitestarMCP(),
    ],
)