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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.0.14
+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
@@ -247,7 +247,7 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-**`fast-agent`** lets you build and interact with Agents and Workflows in minutes.
+**`fast-agent`** enables you to create and interact with sophisticated Agents and Workflows in minutes.
 
 The simple declarative syntax lets you concentrate on composing your Prompts and MCP Servers to [build effective agents](https://www.anthropic.com/research/building-effective-agents).
 
@@ -257,14 +257,19 @@ Evaluate how different models handle Agent and MCP Server calling tasks, then bu
 
 Prompts and configurations that define your Agent Applications are stored in simple files, with minimal boilerplate, enabling simple management and version control.
 
-Chat with individual Agents and Components before, during and after workflow execution to tune and diagnose your agent application. Simple model selection makes testing Model <-> MCP Server interaction painless.
+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. 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
@@ -273,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
@@ -294,12 +300,14 @@ async with fast.run() as agent:
 ```
 
 Or start an interactive chat with the Agent:
+
 ```python
-async with fast.run() as agent:  
+async with fast.run() as agent:
   await agent()
 ```
 
 Here is the complete `sizer.py` Agent application, with boilerplate code:
+
 ```python
 import asyncio
 from mcp_agent.core.fastagent import FastAgent
@@ -319,22 +327,25 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-The Agent can be run with `uv run sizer.py` and with a specific model using the command line option `--model gpt-4o-mini`.
+The Agent can then be run with `uv run sizer.py`.
+
+Specify a model with the `--model` switch - for example `uv run sizer.py --model sonnet`.
 
 ### Combining Agents and using MCP Servers
 
 _To generate examples use `fast-agent bootstrap workflow`. This example can be run with `uv run chaining.py`. fast-agent looks for configuration files in the current directory before checking parent directories recursively._
 
-Agents can be chained to build a workflow:
+Agents can be chained to build a workflow, using MCP Servers defined in the `fastagent.config.yaml` file:
+
 ```python
 @fast.agent(
     "url_fetcher",
-    instruction="Given a URL, provide a complete and comprehensive summary",
+    "Given a URL, provide a complete and comprehensive summary",
     servers=["fetch"], # Name of an MCP Server defined in fastagent.config.yaml
 )
 @fast.agent(
     "social_media",
-    instruction="""
+    """
     Write a 280 character social media post for any given text.
     Respond only with the post, never use hashtags.
     """,
@@ -347,53 +358,66 @@ async def main():
         )
 ```
 
-All Agents and Workflows respond to `.send("message")` to send a 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:
+
+```bash
+uv run social.py --agent social_media --message "<url>"
+```
+
+Add the `--quiet` switch to only return the final response, which is useful for simple automations.
 
 ## Workflows
 
 ### Chain
 
-Alternatively, use the `chain` workflow type and the `prompt()` method to capture user input:
+The `chain` workflow offers a more declarative approach to calling Agents in sequence:
+
 ```python
 
 @fast.chain(
   "post_writer",
-  sequence=["url_fetcher","social_media"]
+   sequence=["url_fetcher","social_media"]
 )
 
 # we can them prompt it directly:
 async with fast.run() as agent:
-  await agent.post_writer.prompt()
+  await agent.post_writer()
 
 ```
+
+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.
 
 ### Parallel
 
-The Parallel Workflow sends the same message to multiple Agents simultaneously (`fan-out`), then uses the `fan-in` agent to process the combined content. 
+The Parallel Workflow sends the same message to multiple Agents simultaneously (`fan-out`), then uses the `fan-in` Agent to process the combined content.
 
 ```python
-
-@fast.agent(
-  name="consolidator"
-  instruction="combine the lists, remove duplicates"
-)
+@fast.agent("translate_fr", "Translate the text to French")
+@fast.agent("translate_de", "Translate the text to German")
+@fast.agent("translate_es", "Translate the text to Spanish")
 
 @fast.parallel(
-  name="ensemble"
-  fan_out=["agent_o3-mini","agent_sonnet37",...]
-  fan_in="consolidator"
+  name="translate",
+  fan_out=["translate_fr","translate_de","translate_es"]
 )
 
-async with fast.run() as agent:
-  result = agent.ensemble.send("what are the 10 most important aspects of project management")
+@fast.chain(
+  "post_writer",
+   sequence=["url_fetcher","social_media","translate"]
+)
 ```
 
-Look at the `parallel.py` workflow example for more details.
+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.
+
+`parallel` is also useful to ensemble ideas from different LLMs.
 
 ### Evaluator-Optimizer
 
-Evaluator-Optimizers use 2 agents: one to generate content (the `generator`), and one to judge the content and provide actionable feedback (the `evaluator`). Messages are sent to the generator first, then the pair run in a loop until either the evaluator is satisfied with the quality, or the maximum number of refinements is reached.
+Evaluator-Optimizers combine 2 agents: one to generate content (the `generator`), and the other to judge that content and provide actionable feedback (the `evaluator`). Messages are sent to the generator first, then the pair run in a loop until either the evaluator is satisfied with the quality, or the maximum number of refinements is reached.
 
 ```python
 @fast.evaluator_optimizer(
@@ -408,11 +432,11 @@ async with fast.run() as agent:
   await agent.researcher.send("produce a report on how to make the perfect espresso")
 ```
 
-See the `evaluator.py` workflow example, or `fast-agent bootstrap researcher` for a more complete example. 
+See the `evaluator.py` workflow example, or `fast-agent bootstrap researcher` for a more complete example.
 
 ### Router
 
-Routers use an LLM to assess a message, and route it to the most appropriate Agent direct . The routing prompt is automatically generated by the router.
+Routers use an LLM to assess a message, and route it to the most appropriate Agent. The routing prompt is automatically generated based on the Agent instructions and available Servers.
 
 ```python
 @fast.router(
@@ -425,7 +449,7 @@ Look at the `router.py` workflow for an example.
 
 ### Orchestrator
 
-Given a task, an Orchestrator uses an LLM to generate a plan to divide the task amongst the available agents and aggregate a result. The planning and aggregation prompts are generated by the Orchestrator, which benefits from using more capable models. Plans can either be built once at the beginning (`plantype="full"`) or iteratively (`plantype="iterative"`).  
+Given a complex task, the Orchestrator uses an LLM to generate a plan to divide the task amongst the available Agents. The planning and aggregation prompts are generated by the Orchestrator, which benefits from using more capable models. Plans can either be built once at the beginning (`plantype="full"`) or iteratively (`plantype="iterative"`).
 
 ```python
 @fast.orchestrator(
@@ -434,22 +458,111 @@ Given a task, an Orchestrator uses an LLM to generate a plan to divide the task
 )
 ```
 
+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
+)
+```
+
+#### 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
+)
+```
+
+#### 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
 )
 ```
 
-### Human Input
+#### Router
 
-When `human_input` is set to true for an Agent, it is presented with the option to prompt the User for input.
+```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
 
@@ -457,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
@@ -471,8 +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.
+- Chat History Clear.
+
+```
 
+```