fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/resources/examples/mcp/elicitations/forms_demo.py

@@ -0,0 +1,107 @@
+"""
+Quick Start: Elicitation Forms Demo
+
+This example demonstrates the elicitation forms feature of fast-agent.
+
+When Read Resource requests are sent to the MCP Server, it generates an Elicitation
+which creates a form for the user to fill out.
+The results are returned to the demo program which prints out the results in a rich format.
+"""
+
+import asyncio
+
+from rich.console import Console
+from rich.panel import Panel
+
+from fast_agent import FastAgent
+from fast_agent.mcp.helpers.content_helpers import get_resource_text
+
+fast = FastAgent("Elicitation Forms Demo", quiet=True)
+console = Console()
+
+
+@fast.agent(
+    "forms-demo",
+    servers=[
+        "elicitation_forms_server",
+    ],
+)
+async def main():
+    """Run the improved forms demo showcasing all elicitation features."""
+    async with fast.run() as agent:
+        console.print("\n[bold cyan]Welcome to the Elicitation Forms Demo![/bold cyan]\n")
+        console.print("This demo shows how to collect structured data using MCP Elicitations.")
+        console.print("We'll present several forms and display the results collected for each.\n")
+
+        # Example 1: Event Registration
+        console.print("[bold yellow]Example 1: Event Registration Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: string validation, email format, URL format, date format, "
+            "multi-select enums[/dim]"
+        )
+        result = await agent["forms-demo"].get_resource("elicitation://event-registration")
+
+        if result_text := get_resource_text(result):
+            panel = Panel(
+                result_text,
+                title="🎫 Registration Confirmation",
+                border_style="green",
+                expand=False,
+            )
+            console.print(panel)
+        else:
+            console.print("[red]No registration data received[/red]")
+
+        # Example 2: Product Review
+        console.print("[bold yellow]Example 2: Product Review Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: number validation (range), radio selection, multiline text[/dim]"
+        )
+        result = await agent.get_resource("elicitation://product-review")
+
+        if result_text := get_resource_text(result):
+            review_panel = Panel(
+                result_text, title="🛍️ Product Review", border_style="cyan", expand=False
+            )
+            console.print(review_panel)
+
+        # Example 3: Account Settings
+        console.print("[bold yellow]Example 3: Account Settings Form[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: boolean selections, radio selection, number validation[/dim]"
+        )
+        result = await agent.get_resource("elicitation://account-settings")
+
+        if result_text := get_resource_text(result):
+            settings_panel = Panel(
+                result_text, title="⚙️ Account Settings", border_style="blue", expand=False
+            )
+            console.print(settings_panel)
+
+        # Example 4: Service Appointment
+        console.print("[bold yellow]Example 4: Service Appointment Booking[/bold yellow]")
+        console.print(
+            "[dim]Demonstrates: string validation, radio selection, boolean, datetime format[/dim]"
+        )
+        result = await agent.get_resource("elicitation://service-appointment")
+
+        if result_text := get_resource_text(result):
+            appointment_panel = Panel(
+                result_text, title="🔧 Appointment Confirmed", border_style="magenta", expand=False
+            )
+            console.print(appointment_panel)
+
+        console.print("\n[bold green]✅ Demo Complete![/bold green]")
+        console.print("\n[bold cyan]Features Demonstrated:[/bold cyan]")
+        console.print("• [green]String validation[/green] (min/max length)")
+        console.print("• [green]Number validation[/green] (range constraints)")
+        console.print("• [green]Radio selections[/green] (enum dropdowns)")
+        console.print("• [green]Multi-select enums[/green] (checkbox lists)")
+        console.print("• [green]Boolean selections[/green] (checkboxes)")
+        console.print("• [green]Format validation[/green] (email, URL, date, datetime)")
+        console.print("• [green]Multiline text[/green] (expandable text areas)")
+        console.print("\nThese forms demonstrate natural, user-friendly data collection patterns!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/mcp/elicitations/game_character.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Demonstration of Custom Elicitation Handler
+
+This example demonstrates a custom elicitation handler that creates
+an interactive game character creation experience with dice rolls,
+visual gauges, and fun interactions.
+"""
+
+import asyncio
+
+# Import our custom handler from the separate module
+from game_character_handler import game_character_elicitation_handler
+from rich.console import Console
+from rich.panel import Panel
+
+from fast_agent import FastAgent
+from fast_agent.mcp.helpers.content_helpers import get_resource_text
+
+fast = FastAgent("Game Character Creator", quiet=True)
+console = Console()
+
+
+@fast.agent(
+    "character-creator",
+    servers=["elicitation_game_server"],
+    # Register our handler from game_character_handler.py
+    elicitation_handler=game_character_elicitation_handler,
+)
+async def main():
+    """Run the game character creator with custom elicitation handler."""
+    async with fast.run() as agent:
+        console.print(
+            Panel(
+                "[bold cyan]Welcome to the Character Creation Studio![/bold cyan]\n\n"
+                "Create your hero with our magical character generator.\n"
+                "Watch as the cosmic dice determine your fate!",
+                title="🎮 Game Time 🎮",
+                border_style="magenta",
+            )
+        )
+
+        # Trigger the character creation
+        result = await agent.get_resource("elicitation://game-character")
+
+        if result_text := get_resource_text(result):
+            character_panel = Panel(
+                result_text, title="📜 Your Character 📜", border_style="green", expand=False
+            )
+            console.print(character_panel)
+
+            console.print("\n[italic]Your character is ready for adventure![/italic]")
+            console.print("[dim]The tavern door opens, and your journey begins...[/dim]\n")
+
+            # Fun ending based on character
+            if "Powerful character" in result_text:
+                console.print("⚔️  [bold]The realm trembles at your might![/bold]")
+            elif "Challenging build" in result_text:
+                console.print("🎯 [bold]True heroes are forged through adversity![/bold]")
+            else:
+                console.print("🗡️  [bold]Your legend begins now![/bold]")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/mcp/elicitations/game_character_handler.py

@@ -0,0 +1,256 @@
+"""
+Custom Elicitation Handler for Game Character Creation
+
+This module provides a whimsical custom elicitation handler that creates
+an interactive game character creation experience with dice rolls,
+visual gauges, and animated effects.
+"""
+
+import asyncio
+import random
+from typing import TYPE_CHECKING, Any
+
+from mcp.shared.context import RequestContext
+from mcp.types import ElicitRequestParams, ElicitResult
+from rich.console import Console
+from rich.progress import BarColumn, Progress, TextColumn
+from rich.prompt import Confirm
+from rich.table import Table
+
+from fast_agent.core.logging.logger import get_logger
+
+if TYPE_CHECKING:
+    from mcp import ClientSession
+
+logger = get_logger(__name__)
+console = Console()
+
+
+async def game_character_elicitation_handler(
+    context: RequestContext["ClientSession", Any],
+    params: ElicitRequestParams,
+) -> ElicitResult:
+    """Custom handler that creates an interactive character creation experience."""
+    logger.info(f"Game character elicitation handler called: {params.message}")
+
+    if params.requestedSchema:
+        properties = params.requestedSchema.get("properties", {})
+        content: dict[str, Any] = {}
+
+        console.print("\n[bold magenta]🎮 Character Creation Studio 🎮[/bold magenta]\n")
+
+        # Character name with typewriter effect
+        if "character_name" in properties:
+            console.print("[cyan]✨ Generating your character's name...[/cyan] ", end="")
+            name_prefixes = ["Hero", "Legend", "Epic", "Mighty", "Brave", "Noble"]
+            name_suffixes = ["blade", "heart", "storm", "fire", "shadow", "star"]
+
+            name = f"{random.choice(name_prefixes)}{random.choice(name_suffixes)}{random.randint(1, 999)}"
+
+            for char in name:
+                console.print(char, end="", style="bold green")
+                await asyncio.sleep(0.03)
+            console.print("\n")
+            content["character_name"] = name
+
+        # Class selection with visual menu and fate dice
+        if "character_class" in properties:
+            class_enum = properties["character_class"].get("enum", [])
+            class_names = properties["character_class"].get("enumNames", class_enum)
+
+            table = Table(title="🎯 Choose Your Destiny", show_header=False, box=None)
+            table.add_column("Option", style="cyan", width=8)
+            table.add_column("Class", style="yellow", width=20)
+            table.add_column("Description", style="dim", width=30)
+
+            descriptions = [
+                "Master of sword and shield",
+                "Wielder of arcane mysteries",
+                "Silent shadow striker",
+                "Nature's deadly archer",
+                "Holy warrior of light",
+                "Inspiring magical performer",
+            ]
+
+            for i, (cls, name, desc) in enumerate(zip(class_enum, class_names, descriptions)):
+                table.add_row(f"[{i + 1}]", name, desc)
+
+            console.print(table)
+
+            # Dramatic fate dice roll
+            console.print("\n[bold yellow]🎲 The Fates decide your path...[/bold yellow]")
+            for _ in range(8):
+                dice_face = random.choice(["⚀", "⚁", "⚂", "⚃", "⚄", "⚅"])
+                console.print(f"\r  Rolling... {dice_face}", end="")
+                await asyncio.sleep(0.2)
+
+            fate_roll = random.randint(1, 6)
+            selected_idx = (fate_roll - 1) % len(class_enum)
+            console.print(f"\n  🎲 Fate dice: [bold red]{fate_roll}[/bold red]!")
+            console.print(
+                f"✨ Destiny has chosen: [bold yellow]{class_names[selected_idx]}[/bold yellow]!\n"
+            )
+            content["character_class"] = class_enum[selected_idx]
+
+        # Stats rolling with animated progress bars and cosmic effects
+        stat_names = ["strength", "intelligence", "dexterity", "charisma"]
+        stats_info = {
+            "strength": {"emoji": "💪", "desc": "Physical power"},
+            "intelligence": {"emoji": "🧠", "desc": "Mental acuity"},
+            "dexterity": {"emoji": "🏃", "desc": "Agility & speed"},
+            "charisma": {"emoji": "✨", "desc": "Personal magnetism"},
+        }
+
+        console.print("[bold]🌟 Rolling cosmic dice for your abilities...[/bold]\n")
+
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(bar_width=25, style="cyan", complete_style="green"),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            console=console,
+        ) as progress:
+            for stat in stat_names:
+                if stat in properties:
+                    # Roll 3d6 for classic D&D feel with bonus potential
+                    rolls = [random.randint(1, 6) for _ in range(3)]
+                    total = sum(rolls)
+
+                    # Add cosmic bonus chance
+                    if random.random() < 0.15:  # 15% chance for cosmic boost
+                        cosmic_bonus = random.randint(1, 3)
+                        total = min(18, total + cosmic_bonus)
+                        cosmic_text = f" ✨+{cosmic_bonus} COSMIC✨"
+                    else:
+                        cosmic_text = ""
+
+                    stat_info = stats_info.get(stat, {"emoji": "📊", "desc": stat.title()})
+                    task = progress.add_task(
+                        f"{stat_info['emoji']} {stat.capitalize()}: {stat_info['desc']}", total=18
+                    )
+
+                    # Animate the progress bar with suspense
+                    for i in range(total + 1):
+                        progress.update(task, completed=i)
+                        await asyncio.sleep(0.04)
+
+                    content[stat] = total
+                    console.print(
+                        f"   🎲 Rolled: {rolls} = [bold green]{total}[/bold green]{cosmic_text}"
+                    )
+
+        # Lucky dice legendary challenge
+        if "lucky_dice" in properties:
+            console.print("\n" + "=" * 60)
+            console.print("[bold yellow]🎰 LEGENDARY CHALLENGE: Lucky Dice! 🎰[/bold yellow]")
+            console.print("The ancient dice of fortune whisper your name...")
+            console.print("Do you dare tempt fate for legendary power?")
+            console.print("=" * 60)
+
+            # Epic dice rolling sequence
+            console.print("\n[cyan]🌟 Rolling the Dice of Destiny...[/cyan]")
+
+            for i in range(15):
+                dice_faces = ["⚀", "⚁", "⚂", "⚃", "⚄", "⚅"]
+                d20_faces = ["🎲"] * 19 + ["💎"]  # Special diamond for 20
+
+                if i < 10:
+                    face = random.choice(dice_faces)
+                else:
+                    face = random.choice(d20_faces)
+
+                console.print(f"\r  [bold]{face}[/bold] Rolling...", end="")
+                await asyncio.sleep(0.15)
+
+            final_roll = random.randint(1, 20)
+
+            if final_roll == 20:
+                console.print("\r  [bold red]💎 NATURAL 20! 💎[/bold red]")
+                console.print("  [bold green]🌟 LEGENDARY SUCCESS! 🌟[/bold green]")
+                console.print("  [gold1]You have been blessed by the gods themselves![/gold1]")
+                bonus_text = "🏆 Divine Champion status unlocked!"
+            elif final_roll >= 18:
+                console.print(f"\r  [bold yellow]⭐ {final_roll} - EPIC ROLL! ⭐[/bold yellow]")
+                bonus_text = "🎁 Epic treasure discovered!"
+            elif final_roll >= 15:
+                console.print(f"\r  [green]🎲 {final_roll} - Great success![/green]")
+                bonus_text = "🌟 Rare magical item found!"
+            elif final_roll >= 10:
+                console.print(f"\r  [yellow]🎲 {final_roll} - Good fortune.[/yellow]")
+                bonus_text = "🗡️ Modest blessing received."
+            elif final_roll == 1:
+                console.print("\r  [bold red]💀 CRITICAL FUMBLE! 💀[/bold red]")
+                bonus_text = "😅 Learning experience gained... try again!"
+            else:
+                console.print(f"\r  [dim]🎲 {final_roll} - The dice are silent.[/dim]")
+                bonus_text = "🎯 Your destiny remains unwritten."
+
+            console.print(f"  [italic]{bonus_text}[/italic]")
+            content["lucky_dice"] = final_roll >= 10
+
+        # Epic character summary with theatrical flair
+        console.print("\n" + "=" * 70)
+        console.print("[bold cyan]📜 Your Character Has Been Rolled! 📜[/bold cyan]")
+        console.print("=" * 70)
+
+        # Show character summary
+        total_stats = sum(content.get(stat, 10) for stat in stat_names if stat in content)
+
+        # Create a simple table
+        stats_table = Table(show_header=False, box=None)
+        stats_table.add_column("Label", style="cyan", width=15)
+        stats_table.add_column("Value", style="bold white")
+
+        if "character_name" in content:
+            stats_table.add_row("Name:", content["character_name"])
+        if "character_class" in content:
+            class_idx = class_enum.index(content["character_class"])
+            stats_table.add_row("Class:", class_names[class_idx])
+
+        stats_table.add_row("", "")  # Empty row for spacing
+
+        # Add stats
+        for stat in stat_names:
+            if stat in content:
+                stat_label = f"{stat.capitalize()}:"
+                stats_table.add_row(stat_label, str(content[stat]))
+
+        stats_table.add_row("", "")
+        stats_table.add_row("Total Power:", str(total_stats))
+
+        console.print(stats_table)
+
+        # Power message
+        if total_stats > 60:
+            console.print("✨ [bold gold1]The realm trembles before your might![/bold gold1] ✨")
+        elif total_stats > 50:
+            console.print("⚔️ [bold green]A formidable hero rises![/bold green] ⚔️")
+        elif total_stats < 35:
+            console.print("🎯 [bold blue]The underdog's tale begins![/bold blue] 🎯")
+        else:
+            console.print("🗡️ [bold white]Adventure awaits the worthy![/bold white] 🗡️")
+
+        # Ask for confirmation
+        console.print("\n[bold yellow]Do you accept this character?[/bold yellow]")
+        console.print("[dim]Press Enter to accept, 'n' to decline, or Ctrl+C to cancel[/dim]\n")
+
+        try:
+            accepted = Confirm.ask("Accept character?", default=True)
+
+            if accepted:
+                console.print(
+                    "\n[bold green]✅ Character accepted! Your adventure begins![/bold green]"
+                )
+                return ElicitResult(action="accept", content=content)
+            else:
+                console.print(
+                    "\n[yellow]❌ Character declined. The fates will roll again...[/yellow]"
+                )
+                return ElicitResult(action="decline")
+        except KeyboardInterrupt:
+            console.print("\n[red]❌ Character creation cancelled![/red]")
+            return ElicitResult(action="cancel")
+
+    else:
+        # No schema, return a fun message
+        content = {"response": "⚔️ Ready for adventure! ⚔️"}
+        return ElicitResult(action="accept", content=content)

fast_agent/resources/examples/mcp/elicitations/tool_call.py

@@ -0,0 +1,21 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("fast-agent example")
+
+
+# Define the agent
+@fast.agent(
+    instruction="You are a helpful AI Agent",
+    servers=["elicitation_account_server"],
+)
+async def main():
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
+        await agent.send('***CALL_TOOL create_user_account {"service_name": "fast-agent"}')
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/mcp/state-transfer/agent_one.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("fast-agent agent_one (mcp server)")
+
+
+# Define the agent
+@fast.agent(name="agent_one", instruction="You are a helpful AI Agent.")
+async def main():
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
+        await agent.interactive()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/mcp/state-transfer/agent_two.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("fast-agent agent_two (mcp client)")
+
+
+# Define the agent
+@fast.agent(name="agent_two", instruction="You are a helpful AI Agent.", servers=["agent_one"])
+async def main():
+    # use the --model command line switch or agent arguments to change model
+    async with fast.run() as agent:
+        await agent.interactive()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/mcp/state-transfer/fastagent.config.yaml

@@ -0,0 +1,27 @@
+# Model string takes format:
+#   <provider>.<model_string>.<reasoning_effort?> (e.g. anthropic.claude-3-5-sonnet-20241022 or openai.o3-mini.low)
+#
+# Can be overriden with a command line switch --model=<model>, or within the Agent decorator.
+# Check here for current details: https://fast-agent.ai/models/
+
+# set the default model for fast-agent below:
+default_model: gpt-4.1
+
+# Logging and Console Configuration:
+logger:
+  # Switched off to avoid polluting the console
+  progress_display: false
+
+  # Show chat User/Assistant messages on the console
+  show_chat: true
+  # Show tool calls on the console
+  show_tools: true
+  # Truncate long tool responses on the console
+  truncate_tools: true
+
+# MCP Servers
+mcp:
+  servers:
+    agent_one:
+      transport: http
+      url: http://localhost:8001/mcp

fast_agent/resources/examples/mcp/state-transfer/fastagent.secrets.yaml.example

@@ -0,0 +1,15 @@
+# FastAgent Secrets Configuration
+# WARNING: Keep this file secure and never commit to version control
+
+# Alternatively set OPENAI_API_KEY, ANTHROPIC_API_KEY or other environment variables.
+# Keys in the configuration file override environment variables.
+
+openai:
+  api_key: <your-api-key-here>
+anthropic:
+  api_key: <your-api-key-here>
+deepseek:
+  api_key: <your-api-key-here>
+openrouter:
+  api_key: <your-api-key-here>
+

fast_agent/resources/examples/researcher/fastagent.config.yaml

@@ -0,0 +1,61 @@
+#
+# Please edit this configuration file to match your environment (on Windows).
+# Examples in comments below - check/change the paths.
+#
+#
+
+logger:
+  type: console
+  level: error
+  truncate_tools: true
+
+mcp:
+  servers:
+    brave:
+      # On windows replace the command and args line to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-brave-search` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-brave-search"]
+      env:
+        # You can also place your BRAVE_API_KEY in the fastagent.secrets.yaml file.
+        BRAVE_API_KEY: <your_brave_api_key>
+    filesystem:
+      # On windows update the command and arguments to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-filesystem` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js","./agent_folder"]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "./agent_folder/"]
+    interpreter:
+      command: "docker"
+      args: [
+          "run",
+          "-i",
+          "--rm",
+          "--pull=always",
+          "-v",
+          "./agent_folder:/mnt/data/",
+          # Docker needs the absolute path on Windows (e.g. "x:/fastagent/agent_folder:/mnt/data/")
+          # "./agent_folder:/mnt/data/",
+          "ghcr.io/evalstate/mcp-py-repl:latest",
+        ]
+      roots:
+        - uri: "file://./agent_folder/"
+          name: "agent_folder"
+          server_uri_alias: "file:///mnt/data/"
+    fetch:
+      command: "uvx"
+      args: ["mcp-server-fetch"]
+    sequential:
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+#    webmcp:
+#      command: "node"
+#      args: ["/home/ssmith/.webmcp/server.cjs"]
+#      env:
+#         WEBMCP_SERVER_TOKEN: 96e22896d8143fc1d61fec09208fc5ed
+

fast_agent/resources/examples/researcher/researcher-eval.py

@@ -0,0 +1,53 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+agents = FastAgent(name="Researcher Agent (EO)")
+
+
+@agents.agent(
+    name="Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed.
+
+You must always provide a summary of the specific sources you have used in your research.
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+@agents.agent(
+    name="Evaluator",
+    model="sonnet",
+    instruction="""
+Evaluate the response from the researcher based on the criteria:
+ - Sources cited. Has the researcher provided a summary of the specific sources used in the research?
+ - Validity. Has the researcher cross-checked and validated data and assumptions.
+ - Alignment. Has the researher acted and addressed feedback from any previous assessments?
+ 
+For each criterion:
+- Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+- Offer specific feedback or suggestions for improvement.
+
+Summarize your evaluation as a structured response with:
+- Overall quality rating.
+- Specific feedback and areas for improvement.""",
+)
+@agents.evaluator_optimizer(
+    generator="Researcher",
+    evaluator="Evaluator",
+    max_refinements=5,
+    min_rating="EXCELLENT",
+    name="Researcher_Evaluator",
+)
+async def main() -> None:
+    async with agents.run() as agent:
+        await agent.prompt("Researcher_Evaluator")
+
+        print("Ask follow up quesions to the Researcher?")
+        await agent.prompt("Researcher", default_prompt="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())