fast-agent-mcp 0.0.15__tar.gz → 0.0.16__tar.gz

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.0.15
+Version: 0.0.16
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>, Sarmad Qadri <sarmad@lastmileai.dev>
 License:                                  Apache License
@@ -259,14 +259,17 @@ Prompts and configurations that define your Agent Applications are stored in sim
 
 Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your application.
 
-Simple model selection makes testing Model <-> MCP Server interaction painless.
+Simple model selection makes testing Model <-> MCP Server interaction painless. You can read more about the motivation behind this project [here](https://llmindset.co.uk/resources/fast-agent/)
+
+![fast-agent](https://github.com/user-attachments/assets/3e692103-bf97-489a-b519-2d0fee036369)
 
 ## Get started:
 
 Start by installing the [uv package manager](https://docs.astral.sh/uv/) for Python. Then:
 
 ```bash
-uv pip install fast-agent-mcp       # install fast-agent
+uv pip install fast-agent-mcp       # install fast-agent!
+
 fast-agent setup                    # create an example agent and config files
 uv run agent.py                     # run your first agent
 uv run agent.py --model=o3-mini.low # specify a model
@@ -275,6 +278,7 @@ fast-agent bootstrap workflow       # create "building effective agents" example
 
 Other bootstrap examples include a Researcher Agent (with Evaluator-Optimizer workflow) and Data Analysis Agent (similar to the ChatGPT experience), demonstrating MCP Roots support.
 
+> [!TIP]
 > Windows Users - there are a couple of configuration changes needed for the Filesystem and Docker MCP Servers - necessary changes are detailed within the configuration files.
 
 ### Basic Agents
@@ -354,7 +358,7 @@ async def main():
         )
 ```
 
-All Agents and Workflows respond to `.send("message")` and `.prompt()` to begin a chat session.
+All Agents and Workflows respond to `.send("message")` or `.prompt()` to begin a chat session.
 
 Saved as `social.py` we can now run this workflow from the command line with:
 
@@ -362,7 +366,7 @@ Saved as `social.py` we can now run this workflow from the command line with:
 uv run social.py --agent social_media --message "<url>"
 ```
 
-Add the `--quiet` switch to only return the final response.
+Add the `--quiet` switch to only return the final response, which is useful for simple automations.
 
 ## Workflows
 
@@ -383,7 +387,7 @@ async with fast.run() as agent:
 
 ```
 
-This starts an interactive session, which produces a short social media post for a given URL. If a _chain_ is prompted, by default it returns to a chat with last Agent in the chain.
+This starts an interactive session, which produces a short social media post for a given URL. If a _chain_ is prompted it returns to a chat with last Agent in the chain. You can switch the agent to prompt by typing `@agent-name`.
 
 Chains can be incorporated in other workflows, or contain other workflow elements (including other Chains). You can set an `instruction` to precisely describe it's capabilities to other workflow steps if needed.
 
@@ -407,9 +411,9 @@ The Parallel Workflow sends the same message to multiple Agents simultaneously (
 )
 ```
 
-Look at the `parallel.py` workflow example for more examples. If you don't specify a `fan-in` agent, the `parallel` returns Agent results verbatim.
+Look at the `parallel.py` workflow example for more examples. If you don't specify a `fan-in` agent, the `parallel` returns the combined Agent results verbatim.
 
-The Parallel is also useful to ensemble ideas from different LLMs.
+`parallel` is also useful to ensemble ideas from different LLMs.
 
 ### Evaluator-Optimizer
 
@@ -458,20 +462,107 @@ See `orchestrator.py` in the workflow examples.
 
 ## Agent Features
 
+### Calling Agents
+
+All definitions allow omitting the name and instructions arguments for brevity:
+
+```python
+@fast.agent("You are a helpful agent")          # Create an agent with a default name.
+@fast.agent("greeter","Respond cheerfully!")    # Create an agent with the name "greeter"
+
+moon_size = await agent("the moon")             # Call the default (first defined agent) with a message
+
+result = await agent.greeter("Good morning!")   # Send a message to an agent by name using dot notation
+result = await agent.greeter.send("Hello!")     # You can call 'send' explicitly
+
+await agent.greeter()                           # If no message is specified, a chat session will open
+await agent.greeter.prompt()                    # that can be made more explicit
+await agent.greeter.prompt(default_prompt="OK") # and supports setting a default prompt
+
+agent["greeter"].send("Good Evening!")          # Dictionary access is supported if preferred
+```
+
+### Defining Agents
+
+#### Basic Agent
+
 ```python
 @fast.agent(
-  name="agent",
-  instructions="instructions",
-  servers=["filesystem"],     # list of MCP Servers for the agent, configured in fastagent.config.yaml
-  model="o3-mini.high",       # specify a model for the agent
-  use_history=True,           # agent can maintain chat history
-  human_input=True,           # agent can request human input
+  name="agent",                          # name of the agent
+  instruction="You are a helpful Agent", # base instruction for the agent
+  servers=["filesystem"],                # list of MCP Servers for the agent
+  model="o3-mini.high",                  # specify a model for the agent
+  use_history=True,                      # agent maintains chat history
+  request_params={"temperature": 0.7},   # additional parameters for the LLM (or RequestParams())
+  human_input=True,                      # agent can request human input
+)
+```
+
+#### Chain
+
+```python
+@fast.chain(
+  name="chain",                          # name of the chain
+  sequence=["agent1", "agent2", ...],    # list of agents in execution order
+  instruction="instruction",             # instruction to describe the chain for other workflows
+  continue_with_final=True,              # open chat with agent at end of chain after prompting
 )
 ```
 
-### Human Input
+#### Parallel
+
+```python
+@fast.parallel(
+  name="parallel",                       # name of the parallel workflow
+  fan_out=["agent1", "agent2"],          # list of agents to run in parallel
+  fan_in="aggregator",                   # name of agent that combines results (optional)
+  instruction="instruction",             # instruction to describe the parallel for other workflows
+  include_request=True,                  # include original request in fan-in message
+)
+```
 
-When `human_input` is set to true for an Agent, it is presented with the option to prompt the User for input.
+#### Evaluator-Optimizer
+
+```python
+@fast.evaluator_optimizer(
+  name="researcher",                     # name of the workflow
+  generator="web_searcher",              # name of the content generator agent
+  evaluator="quality_assurance",         # name of the evaluator agent
+  min_rating="GOOD",                     # minimum acceptable quality (EXCELLENT, GOOD, FAIR, POOR)
+  max_refinements=3,                     # maximum number of refinement iterations
+)
+```
+
+#### Router
+
+```python
+@fast.router(
+  name="route",                          # name of the router
+  agents=["agent1", "agent2", "agent3"], # list of agent names router can delegate to
+  model="o3-mini.high",                  # specify routing model
+  use_history=True,                      # router maintains chat history
+  human_input=False,                     # whether router can request human input
+)
+```
+
+#### Orchestrator
+
+```python
+@fast.orchestrator(
+  name="orchestrator",                   # name of the orchestrator
+  instruction="instruction",             # base instruction for the orchestrator
+  agents=["agent1", "agent2"],           # list of agent names this orchestrator can use
+  model="o3-mini.high",                  # specify orchestrator planning model
+  use_history=False,                     # orchestrator doesn't maintain chat history by default
+  human_input=False,                     # whether orchestrator can request human input
+  plan_type="full",                      # planning approach: "full" or "iterative"
+)
+```
+
+### Secrets File
+
+> [!TIP]
+> fast-agent will look recursively for a fastagent.secrets.yaml file, so you only need to manage this at the root folder of your agent definitions.
 
 ## Project Notes
 
@@ -479,8 +570,11 @@ When `human_input` is set to true for an Agent, it is presented with the option
 
 ### llmindset.co.uk fork:
 
+- Remove instructor use for Orchestrator
+- Improved handling of Parallel/Fan-In and respose option
+- XML based generated prompts
 - "FastAgent" style prototyping, with per-agent models
-- Api keys through Environment Variables
+- API keys through Environment Variables
 - Warm-up / Post-Workflow Agent Interactions
 - Quick Setup
 - Interactive Prompt Mode
@@ -493,7 +587,12 @@ When `human_input` is set to true for an Agent, it is presented with the option
 - OpenAI o1/o3-mini support with reasoning level
 - Enhanced Human Input Messaging and Handling
 - Declarative workflows
+- Numerous defect fixes
 
 ### Features to add.
 
 - Chat History Clear.
+
+```
+
+```

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/README.md

@@ -22,14 +22,17 @@ Prompts and configurations that define your Agent Applications are stored in sim
 
 Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your application.
 
-Simple model selection makes testing Model <-> MCP Server interaction painless.
+Simple model selection makes testing Model <-> MCP Server interaction painless. You can read more about the motivation behind this project [here](https://llmindset.co.uk/resources/fast-agent/)
+
+![fast-agent](https://github.com/user-attachments/assets/3e692103-bf97-489a-b519-2d0fee036369)
 
 ## Get started:
 
 Start by installing the [uv package manager](https://docs.astral.sh/uv/) for Python. Then:
 
 ```bash
-uv pip install fast-agent-mcp       # install fast-agent
+uv pip install fast-agent-mcp       # install fast-agent!
+
 fast-agent setup                    # create an example agent and config files
 uv run agent.py                     # run your first agent
 uv run agent.py --model=o3-mini.low # specify a model
@@ -38,6 +41,7 @@ fast-agent bootstrap workflow       # create "building effective agents" example
 
 Other bootstrap examples include a Researcher Agent (with Evaluator-Optimizer workflow) and Data Analysis Agent (similar to the ChatGPT experience), demonstrating MCP Roots support.
 
+> [!TIP]
 > Windows Users - there are a couple of configuration changes needed for the Filesystem and Docker MCP Servers - necessary changes are detailed within the configuration files.
 
 ### Basic Agents
@@ -117,7 +121,7 @@ async def main():
         )
 ```
 
-All Agents and Workflows respond to `.send("message")` and `.prompt()` to begin a chat session.
+All Agents and Workflows respond to `.send("message")` or `.prompt()` to begin a chat session.
 
 Saved as `social.py` we can now run this workflow from the command line with:
 
@@ -125,7 +129,7 @@ Saved as `social.py` we can now run this workflow from the command line with:
 uv run social.py --agent social_media --message "<url>"
 ```
 
-Add the `--quiet` switch to only return the final response.
+Add the `--quiet` switch to only return the final response, which is useful for simple automations.
 
 ## Workflows
 
@@ -146,7 +150,7 @@ async with fast.run() as agent:
 
 ```
 
-This starts an interactive session, which produces a short social media post for a given URL. If a _chain_ is prompted, by default it returns to a chat with last Agent in the chain.
+This starts an interactive session, which produces a short social media post for a given URL. If a _chain_ is prompted it returns to a chat with last Agent in the chain. You can switch the agent to prompt by typing `@agent-name`.
 
 Chains can be incorporated in other workflows, or contain other workflow elements (including other Chains). You can set an `instruction` to precisely describe it's capabilities to other workflow steps if needed.
 
@@ -170,9 +174,9 @@ The Parallel Workflow sends the same message to multiple Agents simultaneously (
 )
 ```
 
-Look at the `parallel.py` workflow example for more examples. If you don't specify a `fan-in` agent, the `parallel` returns Agent results verbatim.
+Look at the `parallel.py` workflow example for more examples. If you don't specify a `fan-in` agent, the `parallel` returns the combined Agent results verbatim.
 
-The Parallel is also useful to ensemble ideas from different LLMs.
+`parallel` is also useful to ensemble ideas from different LLMs.
 
 ### Evaluator-Optimizer
 
@@ -221,20 +225,107 @@ See `orchestrator.py` in the workflow examples.
 
 ## Agent Features
 
+### Calling Agents
+
+All definitions allow omitting the name and instructions arguments for brevity:
+
+```python
+@fast.agent("You are a helpful agent")          # Create an agent with a default name.
+@fast.agent("greeter","Respond cheerfully!")    # Create an agent with the name "greeter"
+
+moon_size = await agent("the moon")             # Call the default (first defined agent) with a message
+
+result = await agent.greeter("Good morning!")   # Send a message to an agent by name using dot notation
+result = await agent.greeter.send("Hello!")     # You can call 'send' explicitly
+
+await agent.greeter()                           # If no message is specified, a chat session will open
+await agent.greeter.prompt()                    # that can be made more explicit
+await agent.greeter.prompt(default_prompt="OK") # and supports setting a default prompt
+
+agent["greeter"].send("Good Evening!")          # Dictionary access is supported if preferred
+```
+
+### Defining Agents
+
+#### Basic Agent
+
 ```python
 @fast.agent(
-  name="agent",
-  instructions="instructions",
-  servers=["filesystem"],     # list of MCP Servers for the agent, configured in fastagent.config.yaml
-  model="o3-mini.high",       # specify a model for the agent
-  use_history=True,           # agent can maintain chat history
-  human_input=True,           # agent can request human input
+  name="agent",                          # name of the agent
+  instruction="You are a helpful Agent", # base instruction for the agent
+  servers=["filesystem"],                # list of MCP Servers for the agent
+  model="o3-mini.high",                  # specify a model for the agent
+  use_history=True,                      # agent maintains chat history
+  request_params={"temperature": 0.7},   # additional parameters for the LLM (or RequestParams())
+  human_input=True,                      # agent can request human input
+)
+```
+
+#### Chain
+
+```python
+@fast.chain(
+  name="chain",                          # name of the chain
+  sequence=["agent1", "agent2", ...],    # list of agents in execution order
+  instruction="instruction",             # instruction to describe the chain for other workflows
+  continue_with_final=True,              # open chat with agent at end of chain after prompting
 )
 ```
 
-### Human Input
+#### Parallel
+
+```python
+@fast.parallel(
+  name="parallel",                       # name of the parallel workflow
+  fan_out=["agent1", "agent2"],          # list of agents to run in parallel
+  fan_in="aggregator",                   # name of agent that combines results (optional)
+  instruction="instruction",             # instruction to describe the parallel for other workflows
+  include_request=True,                  # include original request in fan-in message
+)
+```
 
-When `human_input` is set to true for an Agent, it is presented with the option to prompt the User for input.
+#### Evaluator-Optimizer
+
+```python
+@fast.evaluator_optimizer(
+  name="researcher",                     # name of the workflow
+  generator="web_searcher",              # name of the content generator agent
+  evaluator="quality_assurance",         # name of the evaluator agent
+  min_rating="GOOD",                     # minimum acceptable quality (EXCELLENT, GOOD, FAIR, POOR)
+  max_refinements=3,                     # maximum number of refinement iterations
+)
+```
+
+#### Router
+
+```python
+@fast.router(
+  name="route",                          # name of the router
+  agents=["agent1", "agent2", "agent3"], # list of agent names router can delegate to
+  model="o3-mini.high",                  # specify routing model
+  use_history=True,                      # router maintains chat history
+  human_input=False,                     # whether router can request human input
+)
+```
+
+#### Orchestrator
+
+```python
+@fast.orchestrator(
+  name="orchestrator",                   # name of the orchestrator
+  instruction="instruction",             # base instruction for the orchestrator
+  agents=["agent1", "agent2"],           # list of agent names this orchestrator can use
+  model="o3-mini.high",                  # specify orchestrator planning model
+  use_history=False,                     # orchestrator doesn't maintain chat history by default
+  human_input=False,                     # whether orchestrator can request human input
+  plan_type="full",                      # planning approach: "full" or "iterative"
+)
+```
+
+### Secrets File
+
+> [!TIP]
+> fast-agent will look recursively for a fastagent.secrets.yaml file, so you only need to manage this at the root folder of your agent definitions.
 
 ## Project Notes
 
@@ -242,8 +333,11 @@ When `human_input` is set to true for an Agent, it is presented with the option
 
 ### llmindset.co.uk fork:
 
+- Remove instructor use for Orchestrator
+- Improved handling of Parallel/Fan-In and respose option
+- XML based generated prompts
 - "FastAgent" style prototyping, with per-agent models
-- Api keys through Environment Variables
+- API keys through Environment Variables
 - Warm-up / Post-Workflow Agent Interactions
 - Quick Setup
 - Interactive Prompt Mode
@@ -256,7 +350,12 @@ When `human_input` is set to true for an Agent, it is presented with the option
 - OpenAI o1/o3-mini support with reasoning level
 - Enhanced Human Input Messaging and Handling
 - Declarative workflows
+- Numerous defect fixes
 
 ### Features to add.
 
 - Chat History Clear.
+
+```
+
+```

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fast-agent-mcp"
-version = "0.0.15"
+version = "0.0.16"
 description = "Define, Prompt and Test MCP enabled Agents and Workflows"
 readme = "README.md"
 license = { file = "LICENSE" }

fast_agent_mcp-0.0.16/src/mcp_agent/cli/__main__.py

@@ -0,0 +1,7 @@
+from mcp_agent.cli.main import app
+
+# This must be here for the console entry points defined in pyproject.toml
+# DO NOT REMOVE!
+
+if __name__ == "__main__":
+    app()

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/src/mcp_agent/config.py

@@ -313,17 +313,25 @@ def get_settings(config_path: str | None = None) -> Settings:
             with open(config_file, "r", encoding="utf-8") as f:
                 yaml_settings = yaml.safe_load(f) or {}
                 merged_settings = yaml_settings
-
-            # Look for secrets file in the same directory
-            for secrets_file in [
-                config_file.parent / "mcp-agent.secrets.yaml",
-                config_file.parent / "mcp_agent.secrets.yaml",
-                config_file.parent / "fastagent.secrets.yaml",
-            ]:
-                if secrets_file.exists():
-                    with open(secrets_file, "r", encoding="utf-8") as f:
-                        yaml_secrets = yaml.safe_load(f) or {}
-                        merged_settings = deep_merge(merged_settings, yaml_secrets)
+            # Look for secrets files recursively up the directory tree
+            # but stop after finding the first one
+            current_dir = config_file.parent
+            found_secrets = False
+            while current_dir != current_dir.parent and not found_secrets:
+                for secrets_filename in [
+                    "mcp-agent.secrets.yaml",
+                    "mcp_agent.secrets.yaml",
+                    "fastagent.secrets.yaml",
+                ]:
+                    secrets_file = current_dir / secrets_filename
+                    if secrets_file.exists():
+                        with open(secrets_file, "r", encoding="utf-8") as f:
+                            yaml_secrets = yaml.safe_load(f) or {}
+                            merged_settings = deep_merge(merged_settings, yaml_secrets)
+                            found_secrets = True
+                            break
+                if not found_secrets:
+                    current_dir = current_dir.parent
 
             _settings = Settings(**merged_settings)
             return _settings

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/src/mcp_agent/core/enhanced_prompt.py

@@ -3,6 +3,7 @@ Enhanced prompt functionality with advanced prompt_toolkit features.
 """
 
 from typing import List
+from importlib.metadata import version
 from prompt_toolkit import PromptSession
 from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import InMemoryHistory
@@ -15,6 +16,12 @@ from rich import print as rich_print
 
 from mcp_agent.core.exceptions import PromptExitError
 
+# Get the application version
+try:
+    app_version = version("fast-agent-mcp")
+except:  # noqa: E722
+    app_version = "unknown"
+
 # Map of agent names to their history
 agent_histories = {}
 
@@ -204,7 +211,7 @@ async def get_enhanced_input(
 
         shortcut_text = " | ".join(f"{key}:{action}" for key, action in shortcuts)
         return HTML(
-            f" <{toolbar_color}> {agent_name} </{toolbar_color}> | <b>Mode:</b> <{mode_style}> {mode_text} </{mode_style}> {newline} | {shortcut_text}"
+            f" <{toolbar_color}> {agent_name} </{toolbar_color}> | <b>Mode:</b> <{mode_style}> {mode_text} </{mode_style}> {newline} | {shortcut_text} | <dim>v{app_version}</dim>"
         )
 
     # Create session with history and completions
@@ -318,7 +325,8 @@ async def handle_special_commands(command, agent_app=None):
         rich_print(
             "  Enter          - Submit (normal mode) / New line (multiline mode)"
         )
-        rich_print("  Ctrl+Enter      - Always submit (even in multiline mode)")
+        rich_print("  \\ + Enter     - Insert new line in normal mode")
+        rich_print("  Ctrl+Enter      - Always submit (in any mode)")
         rich_print("  Ctrl+T         - Toggle multiline mode")
         rich_print("  Ctrl+L         - Clear input")
         rich_print("  Up/Down        - Navigate history")

fast_agent_mcp-0.0.16/src/mcp_agent/resources/examples/data-analysis/analysis.py

@@ -0,0 +1,61 @@
+import asyncio
+
+from mcp_agent.core.fastagent import FastAgent
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
+
+# Create the application
+fast = FastAgent("Data Analysis (Roots)")
+
+
+@fast.agent(
+    name="data_analysis",
+    instruction="""
+You have access to a Python 3.12 interpreter and you can use this to analyse and process data. 
+Common analysis packages such as Pandas, Seaborn and Matplotlib are already installed. 
+You can add further packages if needed.
+Data files are accessible from the /mnt/data/ directory (this is the current working directory).
+Visualisations should be saved as .png files in the current working directory.
+""",
+    servers=["interpreter"],
+    request_params=RequestParams(maxTokens=8192),
+)
+@fast.agent(
+    "evaluator",
+    """You are collaborating with a Data Analysis tool that has the capability to analyse data and produce visualisations.
+    You must make sure that the tool has:
+     - Considered the best way for a Human to interpret the data
+     - Produced insightful visualasions.
+     - Provided a high level summary report for the Human.
+     - Has had its findings challenged, and justified
+    """,
+    request_params=RequestParams(maxTokens=8192),
+)
+@fast.evaluator_optimizer(
+    "analysis_tool",
+    generator="data_analysis",
+    evaluator="evaluator",
+    max_refinements=3,
+    min_rating="EXCELLENT",
+)
+@fast.passthrough(
+    "sample",
+)
+async def main():
+    # Use the app's context manager
+    async with fast.run() as agent:
+        # await agent(
+        #     "There is a csv file in the current directory. "
+        #     "Analyse the file, produce a detailed description of the data, and any patterns it contains.",
+        # )
+        # await agent(
+        #     "Consider the data, and how to usefully group it for presentation to a Human. Find insights, using the Python Interpreter as needed.\n"
+        #     "Use MatPlotLib to produce insightful visualisations. Save them as '.png' files in the current directory. Be sure to run the code and save the files.\n"
+        #     "Produce a summary with major insights to the data",
+        # )
+        await agent.analysis_tool.prompt(
+            "Analyse the CSV File in the working directory"
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/src/mcp_agent/resources/examples/workflows/evaluator.py

@@ -38,8 +38,6 @@ fast = FastAgent("Evaluator-Optimizer")
     Summarize your evaluation as a structured response with:
     - Overall quality rating.
     - Specific feedback and areas for improvement.""",
-    # instructor doesn't seem to work for sonnet37
-    # model="sonnet35",
 )
 # Define the evaluator-optimizer workflow
 @fast.evaluator_optimizer(

{fast_agent_mcp-0.0.15 → fast_agent_mcp-0.0.16}/src/mcp_agent/resources/examples/workflows/parallel.py

@@ -60,10 +60,6 @@ and whispers of a hidden agenda linger among the villagers.
     and give an overall grade based on the feedback.""",
     model="o3-mini.low",
 )
-@fast.agent(
-    name="cats-to-dogs",
-    instruction="you should take any text, and change references about cats to dogs",
-)
 @fast.parallel(
     fan_out=["proofreader", "fact_checker", "style_enforcer"],
     fan_in="grader",