fast-agent-mcp 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

mcp_agent/resources/examples/workflows/chaining.py

@@ -0,0 +1,31 @@
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("Agent Chaining")
+
+
+@fast.agent(
+    "url_fetcher",
+    instruction="Given a URL, provide a complete and comprehensive summary",
+    servers=["fetch"],
+    model="haiku",
+)
+@fast.agent(
+    "social_media",
+    instruction="""
+    Write a 280 character social media post for any given text. 
+    Respond only with the post, never use hashtags.
+    """,
+)
+async def main():
+    async with fast.run() as agent:
+        await agent.social_media(
+            await agent.url_fetcher("http://llmindset.co.uk/resources/mcp-hfspace/")
+        )
+
+    # alternative syntax for above is agent["social_media"].send(message)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/{decorator/optimizer.py → workflows/evaluator.py}

@@ -1,5 +1,4 @@
 """
-Example showing how to use the evaluator-optimizer functionality with the decorator API.
 This demonstrates creating an optimizer and evaluator to iteratively improve content.
 """
 
@@ -7,22 +6,21 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-agent_app = FastAgent("Cover Letter Writer")
-agent_app.app._human_input_callback = None
+fast = FastAgent("Evaluator-Optimizer")
 
 
 # Define optimizer agent
-@agent_app.agent(
+@fast.agent(
     name="optimizer",
     instruction="""You are a career coach specializing in cover letter writing.
     You are tasked with generating a compelling cover letter given the job posting,
     candidate details, and company information. Tailor the response to the company and job requirements.
     """,
     servers=["fetch"],
-    model="gpt-4o-mini",  # Using a capable model for content generation
+    model="gpt-4o-mini",
 )
 # Define evaluator agent
-@agent_app.agent(
+@fast.agent(
     name="evaluator",
     instruction="""Evaluate the following response based on the criteria below:
     1. Clarity: Is the language clear, concise, and grammatically correct?
@@ -40,11 +38,10 @@ agent_app.app._human_input_callback = None
     Summarize your evaluation as a structured response with:
     - Overall quality rating.
     - Specific feedback and areas for improvement.""",
-    servers=[],  # Evaluator doesn't need special server access
-    model="sonnet",  # Using a capable model for evaluation
+    model="sonnet",
 )
 # Define the evaluator-optimizer workflow
-@agent_app.evaluator_optimizer(
+@fast.evaluator_optimizer(
     name="cover_letter_writer",
     optimizer="optimizer",  # Reference to optimizer agent
     evaluator="evaluator",  # Reference to evaluator agent
@@ -52,7 +49,7 @@ agent_app.app._human_input_callback = None
     max_refinements=3,  # Maximum iterations
 )
 async def main():
-    async with agent_app.run() as agent:
+    async with fast.run() as agent:
         job_posting = (
             "Software Engineer at LastMile AI. Responsibilities include developing AI systems, "
             "collaborating with cross-functional teams, and enhancing scalability. Skills required: "

mcp_agent/resources/examples/workflows/fastagent.config.yaml

@@ -0,0 +1,9 @@
+default_model: sonnet
+mcp:
+    servers:
+        fetch:
+            command: "uvx"
+            args: ["mcp-server-fetch"]
+        filesystem:
+            command: "npx"
+            args: ["@modelcontextprotocol/server-filesystem","."]

mcp_agent/resources/examples/workflows/human_input.py

@@ -0,0 +1,25 @@
+"""
+Agent which demonstrates Human Input tool
+"""
+
+import asyncio
+from mcp_agent.core.fastagent import FastAgent
+
+# Create the application
+fast = FastAgent("Human Input")
+
+
+# Define the agent
+@fast.agent(
+    instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
+    human_input=True,
+)
+async def main():
+    async with fast.run() as agent:
+        # this usually causes the LLM to request the Human Input Tool
+        await agent("print the next number in the sequence")
+        await agent.prompt(default="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_agent/resources/examples/{decorator → workflows}/orchestrator.py

@@ -1,5 +1,4 @@
 """
-Example showing how to use the orchestrator functionality with the decorator API.
 This demonstrates creating multiple agents and an orchestrator to coordinate them.
 """
 
@@ -7,11 +6,18 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-agent_app = FastAgent("Orchestrator Example")
+fast = FastAgent("Orchestrator-Workers")
 
 
+@fast.agent(
+    "author",
+    instruction="""You are to role play a poorly skilled writer, 
+    who makes frequent grammar, punctuations and spelling errors. You enjoy
+    writing short stories, but the narrative doesn't always make sense""",
+    servers=["filesystem"],
+)
 # Define worker agents
-@agent_app.agent(
+@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 
@@ -20,15 +26,14 @@ agent_app = FastAgent("Orchestrator Example")
     servers=["fetch", "filesystem"],
     model="gpt-4o-mini",
 )
-@agent_app.agent(
+@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"],
-    model="gpt-4o",
 )
-@agent_app.agent(
+@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. 
@@ -37,19 +42,17 @@ agent_app = FastAgent("Orchestrator Example")
     model="gpt-4o",
 )
 # Define the orchestrator to coordinate the other agents
-@agent_app.orchestrator(
-    name="document_processor",
-    instruction="""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""",
+@fast.orchestrator(
+    name="orchestrate",
     agents=["finder", "writer", "proofreader"],
-    model="sonnet",  # Orchestrators typically need more capable models
+    model="sonnet",
 )
 async def main():
-    async with agent_app.run() as agent:
+    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, 
@@ -61,7 +64,7 @@ async def main():
         )
 
         # Send the task
-        await agent.send("document_processor", task)
+        await agent.orchestrate(task)
 
 
 if __name__ == "__main__":

mcp_agent/resources/examples/{decorator → workflows}/parallel.py

@@ -1,18 +1,14 @@
 """
-Example MCP Agent application showing simplified agent access.
+Parallel Workflow showing Fan Out and Fan In agents, using different models
 """
 
 import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-app = FastAgent(
-    "Parallel Workflow Example",
-    # config={
-    #     "human_input_handler": None  # Disable human input handling
-    # },
+fast = FastAgent(
+    "Parallel Workflow",
 )
-app.app._human_input_callback = None
 SHORT_STORY = """
 The Battle of Glimmerwood
 
@@ -36,45 +32,45 @@ and whispers of a hidden agenda linger among the villagers.
 """
 
 
-@app.agent(
+@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.""",
 )
-@app.agent(
+@fast.agent(
     name="fact_checker",
-    model="gpt-4o",
     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.""",
+    model="gpt-4o",
 )
-@app.agent(
+@fast.agent(
     name="style_enforcer",
-    model="sonnet",
     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",
 )
-@app.agent(
+@fast.agent(
     name="grader",
-    model="o3-mini.high",
     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.""",
+    model="o3-mini.low",
 )
-@app.parallel(
+@fast.parallel(
     fan_out=["proofreader", "fact_checker", "style_enforcer"],
     fan_in="grader",
     name="parallel",
 )
 async def main():
     # Use the app's context manager
-    async with app.run() as agent:
-        await agent.send("parallel", f"student short story submission: {SHORT_STORY}")
+    async with fast.run() as agent:
+        await agent.parallel(f"student short story submission: {SHORT_STORY}")
         # follow-on prompt to task agent
-        # await agent.prompt("style_enforcer", default="STOP")
+        # await agent.style_enforcer.prompt(default="STOP")
 
 
 if __name__ == "__main__":

mcp_agent/resources/examples/{decorator → workflows}/router.py

@@ -9,10 +9,9 @@ import asyncio
 from mcp_agent.core.fastagent import FastAgent
 
 # Create the application
-agent_app = FastAgent(
-    "Router Workflow Example",
+fast = FastAgent(
+    "Router Workflow",
 )
-agent_app.app._human_input_callback = None
 
 # Sample requests demonstrating direct tool use vs agent delegation
 SAMPLE_REQUESTS = [
@@ -22,13 +21,13 @@ SAMPLE_REQUESTS = [
 ]
 
 
-@agent_app.agent(
+@fast.agent(
     name="fetcher",
     instruction="""You are an agent, with a tool enabling you to fetch URLs.""",
     servers=["fetch"],
     model="haiku",
 )
-@agent_app.agent(
+@fast.agent(
     name="code_expert",
     instruction="""You are an expert in code analysis and software engineering.
     When asked about code, architecture, or development practices,
@@ -36,20 +35,20 @@ SAMPLE_REQUESTS = [
     servers=["filesystem"],
     model="gpt-4o",
 )
-@agent_app.agent(
+@fast.agent(
     name="general_assistant",
     instruction="""You are a knowledgeable assistant that provides clear,
     well-reasoned responses about general topics, concepts, and principles.""",
 )
-@agent_app.router(
-    name="llm_router",
+@fast.router(
+    name="route",
     model="sonnet",
     agents=["code_expert", "general_assistant", "fetcher"],
 )
 async def main():
-    async with agent_app.run() as agent:
+    async with fast.run() as agent:
         for request in SAMPLE_REQUESTS:
-            await agent.send("llm_router", request)
+            await agent.route(request)
 
 
 if __name__ == "__main__":

mcp_agent/workflows/llm/augmented_llm_anthropic.py

@@ -1,10 +1,11 @@
 import json
+import os
 from typing import Iterable, List, Type
 
 from pydantic import BaseModel
 
 import instructor
-from anthropic import Anthropic
+from anthropic import Anthropic, AuthenticationError
 from anthropic.types import (
     ContentBlock,
     DocumentBlockParam,
@@ -36,6 +37,7 @@ from mcp_agent.workflows.llm.augmented_llm import (
     ProviderToMCPConverter,
     RequestParams,
 )
+from mcp_agent.core.exceptions import ProviderKeyError
 from mcp_agent.logging.logger import get_logger
 
 DEFAULT_ANTHROPIC_MODEL = "claude-3-5-sonnet-latest"
@@ -77,10 +79,18 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
         Process a query using an LLM and available tools.
         Override this method to use a different LLM.
         """
-        config = self.context.config
-        anthropic = Anthropic(api_key=config.anthropic.api_key)
-        messages: List[MessageParam] = []
-        params = self.get_request_params(request_params)
+
+        api_key = self._api_key(self.context.config)
+        try:
+            anthropic = Anthropic(api_key=api_key)
+            messages: List[MessageParam] = []
+            params = self.get_request_params(request_params)
+        except AuthenticationError as e:
+            raise ProviderKeyError(
+                "Invalid Anthropic API key",
+                "The configured Anthropic API key was rejected.\n"
+                "Please check that your API key is valid and not expired.",
+            ) from e
 
         if params.use_history:
             messages.extend(self.history.get())
@@ -131,15 +141,24 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
 
             response = executor_result[0]
 
-            if isinstance(response, BaseException):
+            if isinstance(response, AuthenticationError):
+                raise ProviderKeyError(
+                    "Invalid Anthropic API key",
+                    "The configured Anthropic API key was rejected.\n"
+                    "Please check that your API key is valid and not expired.",
+                ) from response
+            elif isinstance(response, BaseException):
                 self.logger.error(f"Error: {executor_result}")
-                # Don't break, instead create an error response
+                # Convert other errors to text response
                 error_message = f"Error during generation: {str(response)}"
                 response = Message(
+                    id="error",  # Required field
+                    model="error",  # Required field
                     role="assistant",
                     type="message",
                     content=[TextBlock(type="text", text=error_message)],
-                    stop_reason="error",
+                    stop_reason="end_turn",  # Must be one of the allowed values
+                    usage={"input_tokens": 0, "output_tokens": 0},  # Required field
                 )
 
             self.logger.debug(
@@ -228,6 +247,27 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
 
         return responses
 
+    def _api_key(self, config):
+        api_key = None
+
+        if hasattr(config, "anthropic") and config.anthropic:
+            api_key = config.anthropic.api_key
+            if api_key == "<your-api-key-here>":
+                api_key = None
+
+        if api_key is None:
+            api_key = os.getenv("ANTHROPIC_API_KEY")
+
+        if not api_key:
+            raise ProviderKeyError(
+                "Anthropic API key not configured",
+                "The Anthropic API key is required but not set.\n"
+                "Add it to your configuration file under anthropic.api_key "
+                "or set the ANTHROPIC_API_KEY environment variable.",
+            )
+
+        return api_key
+
     async def generate_str(
         self,
         message,
@@ -249,11 +289,11 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
             for content in response.content:
                 if content.type == "text":
                     final_text.append(content.text)
-                elif content.type == "tool_use":
-                    final_text.append(
-                        f"[Calling tool {content.name} with args {content.input}]"
-                    )
-
+        #             elif content.type == "tool_use":
+        #                 final_text.append(
+        #                     f"[Calling tool {content.name} with args {content.input}]"
+        #                 )
+        # TODO -- check whether this should be reinstated - OpenAI doesn't return this....
         return "\n".join(final_text)
 
     async def generate_structured(
@@ -277,7 +317,7 @@ class AnthropicAugmentedLLM(AugmentedLLM[MessageParam, Message]):
 
         # Next we pass the text through instructor to extract structured data
         client = instructor.from_anthropic(
-            Anthropic(api_key=self.context.config.anthropic.api_key),
+            Anthropic(api_key=self._api_key(self.context.config)),
         )
 
         params = self.get_request_params(request_params)

mcp_agent/workflows/llm/augmented_llm_openai.py

@@ -1,8 +1,9 @@
 import json
+import os
 from typing import Iterable, List, Type
 
 import instructor
-from openai import OpenAI
+from openai import OpenAI, AuthenticationError
 from openai.types.chat import (
     ChatCompletionAssistantMessageParam,
     ChatCompletionContentPartParam,
@@ -33,6 +34,7 @@ from mcp_agent.workflows.llm.augmented_llm import (
     ProviderToMCPConverter,
     RequestParams,
 )
+from mcp_agent.core.exceptions import ProviderKeyError
 from mcp_agent.logging.logger import get_logger
 from rich.text import Text
 
@@ -102,13 +104,34 @@ class OpenAIAugmentedLLM(
         Override this method to use a different LLM.
         """
         config = self.context.config
-        if not config.openai.api_key:
-            raise "OpenAI API key is not set"
-        openai_client = OpenAI(
-            api_key=config.openai.api_key, base_url=config.openai.base_url
-        )
-        messages: List[ChatCompletionMessageParam] = []
-        params = self.get_request_params(request_params)
+        api_key = None
+
+        if hasattr(config, "openai") and config.openai:
+            api_key = config.openai.api_key
+            if api_key == "<your-api-key-here>":
+                api_key = None
+
+        if api_key is None:
+            api_key = os.getenv("OPENAI_API_KEY")
+
+        if not api_key:
+            raise ProviderKeyError(
+                "OpenAI API key not configured",
+                "The OpenAI API key is required but not set.\n"
+                "Add it to your configuration file under openai.api_key\n"
+                "Or set the OPENAI_API_KEY environment variable",
+            )
+
+        try:
+            openai_client = OpenAI(api_key=api_key, base_url=config.openai.base_url)
+            messages: List[ChatCompletionMessageParam] = []
+            params = self.get_request_params(request_params)
+        except AuthenticationError as e:
+            raise ProviderKeyError(
+                "Invalid OpenAI API key",
+                "The configured OpenAI API key was rejected.\n"
+                "Please check that your API key is valid and not expired.",
+            ) from e
 
         system_prompt = self.instruction or params.systemPrompt
         if system_prompt:
@@ -189,7 +212,13 @@ class OpenAIAugmentedLLM(
                 data=response,
             )
 
-            if isinstance(response, BaseException):
+            if isinstance(response, AuthenticationError):
+                raise ProviderKeyError(
+                    "Invalid OpenAI API key",
+                    "The configured OpenAI API key was rejected.\n"
+                    "Please check that your API key is valid and not expired.",
+                ) from response
+            elif isinstance(response, BaseException):
                 self.logger.error(f"Error: {response}")
                 break