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

fast_agent/resources/examples/workflows/orchestrator.py

@@ -0,0 +1,70 @@
+"""
+This demonstrates creating multiple agents and an orchestrator to coordinate them.
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Orchestrator-Workers")
+
+
+@fast.agent(
+    "author",
+    instruction="""You are to role play a poorly skilled writer, 
+    who makes frequent grammar, punctuation and spelling errors. You enjoy
+    writing short stories, but the narrative doesn't always make sense""",
+    servers=["filesystem"],
+)
+# Define worker agents
+@fast.agent(
+    name="finder",
+    instruction="""You are an agent with access to the filesystem, 
+            as well as the ability to fetch URLs. Your job is to identify 
+            the closest match to a user's request, make the appropriate tool calls, 
+            and return the URI and CONTENTS of the closest match.""",
+    servers=["fetch", "filesystem"],
+    model="gpt-4.1",
+)
+@fast.agent(
+    name="writer",
+    instruction="""You are an agent that can write to the filesystem.
+            You are tasked with taking the user's input, addressing it, and 
+            writing the result to disk in the appropriate location.""",
+    servers=["filesystem"],
+)
+@fast.agent(
+    name="proofreader",
+    instruction=""""Review the short story for grammar, spelling, and punctuation errors.
+            Identify any awkward phrasing or structural issues that could improve clarity. 
+            Provide detailed feedback on corrections.""",
+    servers=["fetch"],
+    model="gpt-4.1",
+)
+# Define the orchestrator to coordinate the other agents
+@fast.iterative_planner(
+    name="orchestrate",
+    agents=["finder", "writer", "proofreader"],
+    model="sonnet",
+    plan_iterations=5,
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        # await agent.author(
+        #     "write a 250 word short story about kittens discovering a castle, and save it to short_story.md"
+        # )
+
+        # The orchestrator can be used just like any other agent
+        task = """Load the student's short story from short_story.md, 
+        and generate a report with feedback across proofreading, 
+        factuality/logical consistency and style adherence. Use the style rules from 
+        https://apastyle.apa.org/learn/quick-guide-on-formatting and 
+        https://apastyle.apa.org/learn/quick-guide-on-references.
+        Write the graded report to graded_report.md in the same directory as short_story.md"""
+
+        await agent.orchestrate(task)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/parallel.py

@@ -0,0 +1,56 @@
+"""
+Parallel Workflow showing Fan Out and Fan In agents, using different models
+"""
+
+import asyncio
+from pathlib import Path
+
+from fast_agent import FastAgent
+from fast_agent.core.prompt import Prompt
+
+# Create the application
+fast = FastAgent(
+    "Parallel Workflow",
+)
+
+
+@fast.agent(
+    name="proofreader",
+    instruction=""""Review the short story for grammar, spelling, and punctuation errors.
+    Identify any awkward phrasing or structural issues that could improve clarity. 
+    Provide detailed feedback on corrections.""",
+)
+@fast.agent(
+    name="fact_checker",
+    instruction="""Verify the factual consistency within the story. Identify any contradictions,
+    logical inconsistencies, or inaccuracies in the plot, character actions, or setting. 
+    Highlight potential issues with reasoning or coherence.""",
+)
+@fast.agent(
+    name="style_enforcer",
+    instruction="""Analyze the story for adherence to style guidelines.
+    Evaluate the narrative flow, clarity of expression, and tone. Suggest improvements to 
+    enhance storytelling, readability, and engagement.""",
+    model="sonnet",
+)
+@fast.agent(
+    name="grader",
+    instruction="""Compile the feedback from the Proofreader, Fact Checker, and Style Enforcer
+    into a structured report. Summarize key issues and categorize them by type. 
+    Provide actionable recommendations for improving the story, 
+    and give an overall grade based on the feedback.""",
+)
+@fast.parallel(
+    fan_out=["proofreader", "fact_checker", "style_enforcer"],
+    fan_in="grader",
+    name="parallel",
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        await agent.parallel.send(
+            Prompt.user("Student short story submission", Path("short_story.txt"))
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())  # type: ignore

fast_agent/resources/examples/workflows/router.py

@@ -0,0 +1,69 @@
+"""
+Example MCP Agent application showing router workflow with decorator syntax.
+Demonstrates router's ability to either:
+1. Use tools directly to handle requests
+2. Delegate requests to specialized agents
+"""
+
+import asyncio
+import sys
+
+from rich.console import Console
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent(
+    "Router Workflow",
+)
+
+# Sample requests demonstrating direct tool use vs agent delegation
+SAMPLE_REQUESTS = [
+    "Download and summarize https://llmindset.co.uk/posts/2024/12/mcp-build-notes/",  # Router handles directly with fetch
+    "Analyze the quality of the Python codebase in the current working directory",  # Delegated to code expert
+    "What are the key principles of effective beekeeping?",  # Delegated to general assistant
+]
+
+
+@fast.agent(
+    name="fetcher",
+    model="haiku",
+    instruction="""You are an agent, with a tool enabling you to fetch URLs.""",
+    servers=["fetch"],
+)
+@fast.agent(
+    name="code_expert",
+    model="haiku",
+    instruction="""You are an expert in code analysis and software engineering.
+    When asked about code, architecture, or development practices,
+    you provide thorough and practical insights.""",
+    servers=["filesystem"],
+)
+@fast.agent(
+    name="general_assistant",
+    model="haiku",
+    instruction="""You are a knowledgeable assistant that provides clear,
+    well-reasoned responses about general topics, concepts, and principles.""",
+)
+@fast.router(
+    name="route",
+    model="sonnet",
+    default=True,
+    agents=["code_expert", "general_assistant", "fetcher"],
+)
+async def main() -> None:
+    console = Console(file=sys.stderr)
+    console.print(
+        "\n[bright_red]Router Workflow Demo[/bright_red]\n\n"
+        "Enter a request to route it to the appropriate agent.\nEnter [bright_red]STOP[/bright_red] to run the demo, [bright_red]EXIT[/bright_red] to leave"
+    )
+
+    async with fast.run() as agent:
+        await agent.interactive(agent_name="route")
+        for request in SAMPLE_REQUESTS:
+            await agent.route(request)
+        await agent.interactive()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/short_story.md

@@ -0,0 +1,13 @@
+The Kittens Castle Adventuer
+
+One sunny day, three lil kittens name Whiskers, Socks, and Mittens was walkin threw a mystirus forrest. They hadnt never seen such a big forrest before! The trees was tall an spooky, an the ground was coverd in moss an stikks.
+
+Suddenlee, thru the trees, they sawd somthing HUUUUGE! It was a castell, but not just eny castell. This castell was made of sparkling chese an glittery windos. The turrits was so high they tuch the clowds, an the doars was big enuff for a elefant to walk threw!
+
+"Lookk!" sed Whiskers, his tale all poofy wit exsitement. "We fowned a castell!" Socks meowed loudly an jumped up an down. Mittens, who was the smallist kitten, just stared wit her big rond eyes.
+
+They climed up the cheesy walls, slip-slidin on the smoth surfase. Inside, they discoverd rooms ful of soft pillows an dangling strings an shiny things that went JINGEL when they tuch them. It was like a kitten paradyse!
+
+But then, a big shadowy figur apeared... was it the castell gaurd? Or sumthing mor mystirus? The kittens hudeld togethar, there lil hearts beating fast. What wud happan next in there amazeing adventuer?
+
+THE END??

fast_agent/resources/examples/workflows/short_story.txt

@@ -0,0 +1,19 @@
+The Battle of Glimmerwood
+
+In the heart of Glimmerwood, a mystical forest knowed for its radiant trees, a small village thrived. 
+The villagers, who were live peacefully, shared their home with the forest's magical creatures, 
+especially the Glimmerfoxes whose fur shimmer like moonlight.
+
+One fateful evening, the peace was shaterred when the infamous Dark Marauders attack. 
+Lead by the cunning Captain Thorn, the bandits aim to steal the precious Glimmerstones which was believed to grant immortality.
+
+Amidst the choas, a young girl named Elara stood her ground, she rallied the villagers and devised a clever plan.
+Using the forests natural defenses they lured the marauders into a trap. 
+As the bandits aproached the village square, a herd of Glimmerfoxes emerged, blinding them with their dazzling light, 
+the villagers seized the opportunity to captured the invaders.
+
+Elara's bravery was celebrated and she was hailed as the "Guardian of Glimmerwood". 
+The Glimmerstones were secured in a hidden grove protected by an ancient spell.
+
+However, not all was as it seemed. The Glimmerstones true power was never confirm, 
+and whispers of a hidden agenda linger among the villagers.

fast_agent/resources/setup/.gitignore

@@ -0,0 +1,30 @@
+# Secrets
+fastagent.secrets.yaml
+
+# Python cache/bytecode
+__pycache__/
+*.py[cod]
+
+# Local env and virtualenvs
+.env
+.venv/
+venv/
+env/
+
+# OS cruft
+.DS_Store
+Thumbs.db
+
+# Logs/artifacts
+fastagent.jsonl
+*.jsonl
+
+# Editors (optional)
+.idea/
+.vscode/
+
+# Packaging metadata
+*.dist-info/
+*.egg-info/
+dist/
+build/

fast_agent/resources/setup/agent.py

@@ -0,0 +1,28 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("fast-agent example")
+
+
+default_instruction = """You are a helpful AI Agent.
+
+{{serverInstructions}}
+{{agentSkills}}
+{{file_silent:AGENTS.md}}
+{{env}}
+
+The current date is {{currentDate}}."""
+
+
+# Define the agent
+@fast.agent(instruction=default_instruction)
+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/setup/fastagent.config.yaml

@@ -0,0 +1,65 @@
+# fast-agent configuration File
+
+# Default Model Configuration:
+#
+# Takes format:
+#   <provider>.<model_string>.<reasoning_effort?> (e.g. anthropic.claude-3-5-sonnet-20241022 or openai.o3-mini.low)
+# Accepts aliases for Anthropic Models: haiku, haiku3, sonnet, sonnet35, opus, opus3
+# and OpenAI Models: gpt-4.1, gpt-4.1-mini, o1, o1-mini, o3-mini
+#
+# If not specified, defaults to "gpt-5-mini.low".
+# Can be overriden with a command line switch --model=<model>, or within the Agent constructor.
+
+default_model: gpt-5-mini.low
+
+# Number of times to retry transient LLM API errors (falls back to FAST_AGENT_RETRIES env var)
+# llm_retries: 0
+
+# otel:
+#   enabled: true
+
+# mcp-ui support: disabled, enabled or auto. "auto" opens the web browser on the asset automatically
+# mcp_ui_output_dir: ".fast-agent/ui"  # Where to write MCP-UI HTML files (relative to CWD if not absolute)
+# mcp_ui_mode: enabled
+
+# MCP timeline display (adjust activity window/intervals in MCP UI + fast-agent check)
+mcp_timeline:
+  steps: 20 # number of timeline buckets to render
+  step_seconds: 15 # seconds per bucket (accepts values like "45s", "2m")
+
+#shell_execution:
+# length of time before terminating subprocess
+#  timeout_seconds: 20
+# warning interval if no output seen
+#  warning_seconds: 5
+
+# Logging and Console Configuration:
+logger:
+  # level: "debug" | "info" | "warning" | "error"
+  # type: "none" | "console" | "file" | "http"
+  # path: "/path/to/logfile.jsonl"
+
+  # Switch the progress display on or off
+  progress_display: true
+  # 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
+  # Streaming renderer for assistant responses: "markdown", "plain", or "none"
+  streaming: markdown
+
+# MCP Servers
+mcp:
+  servers:
+    fetch:
+      command: "uvx"
+      args: ["mcp-server-fetch"]
+    filesystem:
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    huggingface:
+      url: "https://huggingface.co/mcp?login"
+      # headers:
+      # "Authorization": "Bearer ${ENV_VAR}"

fast_agent/resources/setup/fastagent.secrets.yaml.example

@@ -0,0 +1,38 @@
+# 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>
+deepseek:
+  api_key: <your-api-key-here>
+google:
+  api_key: <your-api-key-here>
+googleoai:
+  api_key: <your-api-key-here>
+azure:
+  api_key: <your-api-key-here>
+  base_url: "https://...resource_name....openai.azure.com/" # Resource name (do NOT include if using base_url)
+  azure_deployment: "gpt-4.1" # Required - the model deployment name
+#  api_version: "2024-10-21"
+xai:
+  api_key: <your-api-key-here>
+hf:
+  api_key: <your-api-key-here>
+groq:
+  api_key: <your-api-key-here>
+
+# Example of setting an MCP Server environment variable
+mcp:
+  servers:
+    brave:
+      env:
+        BRAVE_API_KEY: <your-api-key-here>

fast_agent/resources/setup/pyproject.toml.tmpl

@@ -0,0 +1,23 @@
+[project]
+name = "fast-agent-app"
+version = "0.1.0"
+description = "a simple fast-agent application"
+readme = "README.md"
+requires-python = "{{python_requires}}"
+dependencies = [
+  {{fast_agent_dep}}
+]
+
+[tool.uv]
+package = true
+
+# Optional convenience entry point if you later package this app:
+[project.scripts]
+fast-agent-app = "agent:main"
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["agent"]

fast_agent/skills/__init__.py

@@ -0,0 +1,9 @@
+"""Skill discovery utilities."""
+
+from .registry import SkillManifest, SkillRegistry, format_skills_for_prompt
+
+__all__ = [
+    "SkillManifest",
+    "SkillRegistry",
+    "format_skills_for_prompt",
+]

fast_agent/skills/registry.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Sequence
+
+import frontmatter
+
+from fast_agent.core.logging.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass(frozen=True)
+class SkillManifest:
+    """Represents a single skill description loaded from SKILL.md."""
+
+    name: str
+    description: str
+    body: str
+    path: Path
+    relative_path: Path | None = None
+
+
+class SkillRegistry:
+    """Simple registry that resolves a single skills directory and parses manifests."""
+
+    DEFAULT_CANDIDATES = (Path(".fast-agent/skills"), Path(".claude/skills"))
+
+    def __init__(
+        self, *, base_dir: Path | None = None, override_directory: Path | None = None
+    ) -> None:
+        self._base_dir = base_dir or Path.cwd()
+        self._directory: Path | None = None
+        self._original_override_directory: Path | None = None  # Store original before resolution
+        self._override_failed: bool = False
+        self._errors: list[dict[str, str]] = []
+        if override_directory:
+            self._original_override_directory = override_directory
+            resolved = self._resolve_directory(override_directory)
+            if resolved and resolved.exists() and resolved.is_dir():
+                self._directory = resolved
+            else:
+                logger.warning(
+                    "Skills directory override not found",
+                    data={"directory": str(resolved)},
+                )
+                self._override_failed = True
+        if self._directory is None and not self._override_failed:
+            self._directory = self._find_default_directory()
+
+    @property
+    def directory(self) -> Path | None:
+        return self._directory
+
+    @property
+    def override_failed(self) -> bool:
+        return self._override_failed
+
+    def load_manifests(self) -> list[SkillManifest]:
+        self._errors = []
+        if not self._directory:
+            return []
+        manifests = self._load_directory(self._directory, self._errors)
+
+        # Recompute relative paths to be from base_dir (workspace root) instead of skills directory
+        adjusted_manifests: list[SkillManifest] = []
+        for manifest in manifests:
+            try:
+                relative_path = manifest.path.relative_to(self._base_dir)
+                adjusted_manifest = replace(manifest, relative_path=relative_path)
+                adjusted_manifests.append(adjusted_manifest)
+            except ValueError:
+                # Path is outside workspace - compute relative to skills directory
+                # and prepend the original override path (e.g., ../skills/my-skill/SKILL.md)
+                if self._original_override_directory is not None:
+                    try:
+                        skill_relative = manifest.path.relative_to(self._directory)
+                        relative_path = self._original_override_directory / skill_relative
+                        adjusted_manifest = replace(manifest, relative_path=relative_path)
+                    except ValueError:
+                        # Fallback to absolute path if we can't compute relative
+                        adjusted_manifest = replace(manifest, relative_path=None)
+                else:
+                    adjusted_manifest = replace(manifest, relative_path=None)
+                adjusted_manifests.append(adjusted_manifest)
+
+        return adjusted_manifests
+
+    def load_manifests_with_errors(self) -> tuple[list[SkillManifest], list[dict[str, str]]]:
+        manifests = self.load_manifests()
+        return manifests, list(self._errors)
+
+    @property
+    def errors(self) -> list[dict[str, str]]:
+        return list(self._errors)
+
+    def _find_default_directory(self) -> Path | None:
+        for candidate in self.DEFAULT_CANDIDATES:
+            resolved = self._resolve_directory(candidate)
+            if resolved and resolved.exists() and resolved.is_dir():
+                return resolved
+        return None
+
+    def _resolve_directory(self, directory: Path) -> Path:
+        if directory.is_absolute():
+            return directory
+        return (self._base_dir / directory).resolve()
+
+    @classmethod
+    def load_directory(cls, directory: Path) -> list[SkillManifest]:
+        if not directory.exists() or not directory.is_dir():
+            logger.debug(
+                "Skills directory not found",
+                data={"directory": str(directory)},
+            )
+            return []
+        return cls._load_directory(directory)
+
+    @classmethod
+    def load_directory_with_errors(
+        cls, directory: Path
+    ) -> tuple[list[SkillManifest], list[dict[str, str]]]:
+        errors: list[dict[str, str]] = []
+        manifests = cls._load_directory(directory, errors)
+        return manifests, errors
+
+    @classmethod
+    def _load_directory(
+        cls,
+        directory: Path,
+        errors: list[dict[str, str]] | None = None,
+    ) -> list[SkillManifest]:
+        manifests: list[SkillManifest] = []
+        for entry in sorted(directory.iterdir()):
+            if not entry.is_dir():
+                continue
+            manifest_path = entry / "SKILL.md"
+            if not manifest_path.exists():
+                continue
+            manifest, error = cls._parse_manifest(manifest_path)
+            if manifest:
+                # Compute relative path from skills directory (not cwd)
+                # Old behavior: try both cwd and directory
+                # relative_path: Path | None = None
+                # for base in (cwd, directory):
+                #     try:
+                #         relative_path = manifest_path.relative_to(base)
+                #         break
+                #     except ValueError:
+                #         continue
+
+                # New behavior: always relative to skills directory
+                try:
+                    relative_path = manifest_path.relative_to(directory)
+                except ValueError:
+                    relative_path = None
+
+                manifest = replace(manifest, relative_path=relative_path)
+                manifests.append(manifest)
+            elif errors is not None:
+                errors.append(
+                    {
+                        "path": str(manifest_path),
+                        "error": error or "Failed to parse skill manifest",
+                    }
+                )
+        return manifests
+
+    @classmethod
+    def _parse_manifest(cls, manifest_path: Path) -> tuple[SkillManifest | None, str | None]:
+        try:
+            post = frontmatter.loads(manifest_path.read_text(encoding="utf-8"))
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Failed to parse skill manifest",
+                data={"path": str(manifest_path), "error": str(exc)},
+            )
+            return None, str(exc)
+
+        metadata = post.metadata or {}
+        name = metadata.get("name")
+        description = metadata.get("description")
+
+        if not isinstance(name, str) or not name.strip():
+            logger.warning("Skill manifest missing name", data={"path": str(manifest_path)})
+            return None, "Missing 'name' field"
+        if not isinstance(description, str) or not description.strip():
+            logger.warning("Skill manifest missing description", data={"path": str(manifest_path)})
+            return None, "Missing 'description' field"
+
+        body_text = (post.content or "").strip()
+
+        return SkillManifest(
+            name=name.strip(),
+            description=description.strip(),
+            body=body_text,
+            path=manifest_path,
+        ), None
+
+
+def format_skills_for_prompt(manifests: Sequence[SkillManifest]) -> str:
+    """
+    Format a collection of skill manifests into an XML-style block suitable for system prompts.
+    """
+    if not manifests:
+        return ""
+
+    preamble = (
+        "Skills provide specialized capabilities and domain knowledge. Use a Skill if it seems in any way "
+        "relevant to the Users task, intent or would increase your effectiveness. \n"
+        "Use 'execute' to run shell commands in the agent workspace. Files you create will be visible to the user."
+        "To use a Skill you must first read the SKILL.md file (use 'execute' tool).\n "
+        "Paths in Skill documentation are relative to that Skill's directory, NOT the workspace root.\n"
+        "For example if the 'test' skill has scripts/example.py access it with <skill_folder>/scripts/example.py.\n"
+        "Only use Skills listed in <available_skills> below.\n\n"
+    )
+    formatted_parts: list[str] = []
+
+    for manifest in manifests:
+        description = (manifest.description or "").strip()
+        relative_path = manifest.relative_path
+        path_attr = f' path="{relative_path}"' if relative_path is not None else ""
+        if relative_path is None and manifest.path:
+            path_attr = f' path="{manifest.path}"'
+
+        block_lines: list[str] = [f'<agent-skill name="{manifest.name}"{path_attr}>']
+        if description:
+            block_lines.append(f"{description}")
+        block_lines.append("</agent-skill>")
+        formatted_parts.append("\n".join(block_lines))
+
+    return "".join(
+        (f"{preamble}<available_skills>\n", "\n".join(formatted_parts), "\n</available_skills>")
+    )