fast-agent-mcp 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

{fast_agent_mcp-0.0.13.dist-info → fast_agent_mcp-0.0.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.0.13
+Version: 0.0.15
 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,13 +247,21 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-**`fast-agent`** lets you define, test and interact with agents, tools 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 the prompts, MCP Servers and compositions to build effective agents.
+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).
 
-Quickly compare how different models perform at Agent and MCP Server calling tasks, and build mixed multi-model workflows using the best provider for each task.
+Evaluate how different models handle Agent and MCP Server calling tasks, then build multi-model workflows using the best provider for each task.
 
-### Get started:
+### Agent Application Development
+
+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 application.
+
+Simple model selection makes testing Model <-> MCP Server interaction painless.
+
+## Get started:
 
 Start by installing the [uv package manager](https://docs.astral.sh/uv/) for Python. Then:
 
@@ -265,15 +273,209 @@ uv run agent.py --model=o3-mini.low # specify a model
 fast-agent bootstrap workflow       # create "building effective agents" examples
 ```
 
-Other bootstrap examples include a Researcher (with Evaluator-Optimizer workflow) and Data Analysis (similar to ChatGPT experience), demonstrating MCP Roots support.
+Other bootstrap examples include a Researcher Agent (with Evaluator-Optimizer workflow) and Data Analysis Agent (similar to the ChatGPT experience), demonstrating MCP Roots support.
 
 > 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.
 
-## Agent Development
+### Basic Agents
+
+Defining an agent is as simple as:
+
+```python
+@fast.agent(
+  instruction="Given an object, respond only with an estimate of its size."
+)
+```
+
+We can then send messages to the Agent:
+
+```python
+async with fast.run() as agent:
+  moon_size = await agent("the moon")
+  print(moon_size)
+```
+
+Or start an interactive chat with the Agent:
+
+```python
+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
+
+# Create the application
+fast = FastAgent("Agent Example")
+
+@fast.agent(
+  instruction="Given an object, respond only with an estimate of its size."
+)
+
+async def main():
+  async with fast.run() as agent:
+    await agent()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+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, using MCP Servers defined in the `fastagent.config.yaml` file:
+
+```python
+@fast.agent(
+    "url_fetcher",
+    "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",
+    """
+    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/")
+        )
+```
+
+All Agents and Workflows respond to `.send("message")` and `.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.
+
+## Workflows
+
+### Chain
+
+The `chain` workflow offers a more declarative approach to calling Agents in sequence:
+
+```python
 
-FastAgent lets you interact with Agents during a workflow, enabling "warm-up" and diagnostic prompting to improve behaviour and refine prompts.
+@fast.chain(
+  "post_writer",
+   sequence=["url_fetcher","social_media"]
+)
 
-## MCP Server Development
+# we can them prompt it directly:
+async with fast.run() as agent:
+  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, by default it returns to a chat with last Agent in the chain.
+
+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.
+
+```python
+@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="translate",
+  fan_out=["translate_fr","translate_de","translate_es"]
+)
+
+@fast.chain(
+  "post_writer",
+   sequence=["url_fetcher","social_media","translate"]
+)
+```
+
+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.
+
+The Parallel is also useful to ensemble ideas from different LLMs.
+
+### Evaluator-Optimizer
+
+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(
+  name="researcher"
+  generator="web_searcher"
+  evaluator="quality_assurance"
+  min_rating="EXCELLENT"
+  max_refinements=3
+)
+
+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.
+
+### 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(
+  name="route"
+  agents["agent1","agent2","agent3"]
+)
+```
+
+Look at the `router.py` workflow for an example.
+
+### Orchestrator
+
+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(
+  name="orchestrate"
+  agents=["task1","task2","task3"]
+)
+```
+
+See `orchestrator.py` in the workflow examples.
+
+## Agent Features
+
+```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
+)
+```
+
+### Human Input
+
+When `human_input` is set to true for an Agent, it is presented with the option to prompt the User for input.
+
+## Project Notes
+
+`fast-agent` builds on the [`mcp-agent`](https://github.com/lastmile-ai/mcp-agent) project by Sarmad Qadri.
 
 ### llmindset.co.uk fork:
 
@@ -292,10 +494,6 @@ FastAgent lets you interact with Agents during a workflow, enabling "warm-up" an
 - Enhanced Human Input Messaging and Handling
 - Declarative workflows
 
-## Get Started
-
-We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python projects:
-
-## Table of Contents
+### Features to add.
 
-We welcome any and all kinds of contributions. Please see the [CONTRIBUTING guidelines](./CONTRIBUTING.md) to get started.
+- Chat History Clear.

{fast_agent_mcp-0.0.13.dist-info → fast_agent_mcp-0.0.15.dist-info}/RECORD

@@ -13,14 +13,20 @@ mcp_agent/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/cli/__main__.py,sha256=bhxe66GYqy0q78OQhi7dkuubY1Tn0bQL6hU5Nn47E34,73
 mcp_agent/cli/main.py,sha256=cqRxYTpeZ656lzf9qLR3LPnQXrFVDxlWm5gRuqyzUQg,2456
 mcp_agent/cli/terminal.py,sha256=5fqrKlJvIpKEuvpvZ653OueQSYFFktBEbosjr2ucMUc,1026
-mcp_agent/cli/commands/bootstrap.py,sha256=N7pGP7IWjL5HI99glk4BXzaAYwHGkJjQcDTBMOmDAGQ,10779
+mcp_agent/cli/commands/bootstrap.py,sha256=z1wZSy8vO_GZPGLrFGzG3EKFQgAHC08jiIdVyylo-58,10778
 mcp_agent/cli/commands/config.py,sha256=32YTS5jmsYAs9QzAhjkG70_daAHqOemf4XbZBBSMz6g,204
 mcp_agent/cli/commands/setup.py,sha256=8ofxUAF2nUSu1IarDZSAsTt6_6PoEht3TGbz9N6WSbs,6239
 mcp_agent/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_agent/core/agent_app.py,sha256=2gnORb52cpWYGjRDNTJ9lVCEEc11c7Xi874ho7bbYVQ,6097
+mcp_agent/core/agent_types.py,sha256=yKiMbv9QO2dduq4zXmoMZlOZpXJZhM4oNwIq1-134FE,318
+mcp_agent/core/agent_utils.py,sha256=yUJ-qvw5TblqqOsB1vj0Qvcz9mass9awPA6UNNvuw0A,1738
 mcp_agent/core/enhanced_prompt.py,sha256=0V5q0xcCk8PBwtc0p62B8JJ1VvqxN_wuJiXC2QPqv1M,12750
-mcp_agent/core/exceptions.py,sha256=pcI-JNn5Eql4weIKsDYnIwhPyzkc7CBJBJHOUT0w6kQ,2005
-mcp_agent/core/fastagent.py,sha256=_9PRnxZZJWgLxvcjF-KnibsxqYs2lVs-BD_gj9o_Neo,49733
+mcp_agent/core/error_handling.py,sha256=D3HMW5odrbJvaKqcpCGj6eDXrbFcuqYaCZz7fyYiTu4,623
+mcp_agent/core/exceptions.py,sha256=a2-JGRwFFRoQEPuAq0JC5PhAJ5TO3xVJfdS4-VN29cw,2225
+mcp_agent/core/fastagent.py,sha256=MLMdQ4_Cjb2svWyGVWLGf8EzI3dSFCl4BS5qq8UrKgg,56966
+mcp_agent/core/proxies.py,sha256=hXDUpsgGO4xBTIjdUeXj6vULPb8sf55vAFVQh6Ybn60,4411
 mcp_agent/core/server_validation.py,sha256=_59cn16nNT4HGPwg19HgxMtHK4MsdWYDUw_CuL-5xek,1696
+mcp_agent/core/types.py,sha256=Zhi9iW7uiOfdpSt9NC0FCtGRFtJPg4mpZPK2aYi7a7M,817
 mcp_agent/eval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/executor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/executor/decorator_registry.py,sha256=eONv5WvIcjKd43jVqeP7iB2EkAK-ErhdmXt6ogN0K_w,3848
@@ -53,17 +59,18 @@ mcp_agent/resources/examples/data-analysis/fastagent.config.yaml,sha256=eTKGbjnT
 mcp_agent/resources/examples/data-analysis/mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv,sha256=pcMeOL1_r8m8MziE6xgbBrQbjl5Ijo98yycZn7O-dlk,227977
 mcp_agent/resources/examples/internal/agent.py,sha256=f-jTgYabV3nWCQm0ZP9NtSEWjx3nQbRngzArRufcELg,384
 mcp_agent/resources/examples/internal/job.py,sha256=WEKIAANMEAuKr13__rYf3PqJeTAsNB_kqYqbqVYQlUM,4093
+mcp_agent/resources/examples/internal/social.py,sha256=Cot2lg3PLhLm13gPdVFvFEN28-mm6x3-jHu2YsV4N3s,1707
 mcp_agent/resources/examples/mcp_researcher/researcher-eval.py,sha256=kNPjIU-JwE0oIBQKwhv6lZsUF_SPtYVkiEEbY1ZVZxk,1807
 mcp_agent/resources/examples/researcher/fastagent.config.yaml,sha256=2_VXZneckR6zk6RWzzL-smV_oWmgg4uSkLWqZv8jF0I,1995
 mcp_agent/resources/examples/researcher/researcher-eval.py,sha256=kNPjIU-JwE0oIBQKwhv6lZsUF_SPtYVkiEEbY1ZVZxk,1807
 mcp_agent/resources/examples/researcher/researcher.py,sha256=jPRafm7jbpHKkX_dQiYGG3Sw-e1Dm86q-JZT-WZDhM0,1425
 mcp_agent/resources/examples/workflows/agent_build.py,sha256=vdjS02rZR88RU53WYzXxPscfFNEFFe_niHYE_i49I8Q,2396
-mcp_agent/resources/examples/workflows/chaining.py,sha256=sDymBRuU5V_tlnDuclOaMYHPbHOk8eyaWsya5vxzrGo,817
+mcp_agent/resources/examples/workflows/chaining.py,sha256=1G_0XBcFkSJCOXb6N_iXWlSc_oGAlhENR0k_CN1vJKI,1208
 mcp_agent/resources/examples/workflows/evaluator.py,sha256=FZy-ciZafdqSHUW67LKdHw0t9rvX6X67waMOoeIN3GY,3147
 mcp_agent/resources/examples/workflows/fastagent.config.yaml,sha256=k2AiapOcK42uqG2nWDVvnSLqN4okQIQZK0FTbZufBpY,809
 mcp_agent/resources/examples/workflows/human_input.py,sha256=c8cBdLEPbaMXddFwsfN3Z7RFs5PZXsdrjANfvq1VTPM,605
 mcp_agent/resources/examples/workflows/orchestrator.py,sha256=pRJqB-ok79_iEj8aG4FysHyXz6wAHLUX-5tS8khUI7k,2574
-mcp_agent/resources/examples/workflows/parallel.py,sha256=pLbQrtXfbdYqMVddxtg5dZnBnm5Wo2mXlIa1Vf2F1FQ,3096
+mcp_agent/resources/examples/workflows/parallel.py,sha256=dowCw6i8mVaWFWqLvyEEJz1kZDQqdeiltcM-hEz38iY,3222
 mcp_agent/resources/examples/workflows/router.py,sha256=XT_ewCrxPxdUTMCYQGw34qZQ3GGu8TYY_v5Lige8By4,1707
 mcp_agent/telemetry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/telemetry/usage_tracking.py,sha256=ePujKMSjPxB7k6X34DGaVlnsV1728mcWZq38OqahiCU,501
@@ -83,8 +90,8 @@ mcp_agent/workflows/intent_classifier/intent_classifier_llm.py,sha256=WSLUv2Casb
 mcp_agent/workflows/intent_classifier/intent_classifier_llm_anthropic.py,sha256=Hp4454IniWFxV4ml50Ml8ip9rS1La5FBn5pd7vm1FHA,1964
 mcp_agent/workflows/intent_classifier/intent_classifier_llm_openai.py,sha256=zj76WlTYnSCYjBQ_IDi5vFBQGmNwYaoUq1rT730sY98,1940
 mcp_agent/workflows/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_agent/workflows/llm/augmented_llm.py,sha256=8D0hUePn47ChZrmUL8nt60u-iw09EFnJIV7wiQDd2fo,23362
-mcp_agent/workflows/llm/augmented_llm_anthropic.py,sha256=yrOv1V6rOfm2TTDR58fnf8YU8hBnTIpOZhB2sUgZw6o,21246
+mcp_agent/workflows/llm/augmented_llm.py,sha256=Hyx-jwgbMjE_WQ--YjIUvdj6HAgX36IvXBesGy6uic0,25884
+mcp_agent/workflows/llm/augmented_llm_anthropic.py,sha256=4hyC8xI8zTLm7NgbyQRoWRu2ycoTP4Qu6bnPXR1p9ow,22473
 mcp_agent/workflows/llm/augmented_llm_openai.py,sha256=5PwTh0QJSQ29EtK0UuiltgX6snRSBoau75C35S4xQcQ,24477
 mcp_agent/workflows/llm/llm_selector.py,sha256=G7pIybuBDwtmyxUDov_QrNYH2FoI0qFRu2JfoxWUF5Y,11045
 mcp_agent/workflows/llm/model_factory.py,sha256=7zTJrO2ReHa_6dfh_gY6xO8dTySqGFCKlOG9-AMJ-i8,6920
@@ -95,7 +102,7 @@ mcp_agent/workflows/orchestrator/orchestrator_prompts.py,sha256=-ogkjDoCXBDOyYE9
 mcp_agent/workflows/parallel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/workflows/parallel/fan_in.py,sha256=EivpUL5-qftctws-tlfwmYS1QeSwr07POIbBUbwvwOk,13184
 mcp_agent/workflows/parallel/fan_out.py,sha256=J-yezgjzAWxfueW_Qcgwoet4PFDRIh0h4m48lIbFA4c,7023
-mcp_agent/workflows/parallel/parallel_llm.py,sha256=4oIrpTAPlfo3abd306RCdbTnKTjFqa9QndxR4AY4UyI,4785
+mcp_agent/workflows/parallel/parallel_llm.py,sha256=fk88DhBRAI41Ph0spe_yBtrMTSj0g47yoA-ozuOxZhE,5807
 mcp_agent/workflows/router/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/workflows/router/router_base.py,sha256=1Qr3Fx9_KxpotMV-eaNT79etayAxWuQOmanDfk1qjtI,10250
 mcp_agent/workflows/router/router_embedding.py,sha256=wEU49li9OqTX-Xucm0HDUFLZjlND1WuewOcQVAo0s2E,7944
@@ -106,8 +113,8 @@ mcp_agent/workflows/swarm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 mcp_agent/workflows/swarm/swarm.py,sha256=-lAIeSWDqbGHGRPTvjiP9nIKWvxxy9DAojl9yQzO1Pw,11050
 mcp_agent/workflows/swarm/swarm_anthropic.py,sha256=pW8zFx5baUWGd5Vw3nIDF2oVOOGNorij4qvGJKdYPcs,1624
 mcp_agent/workflows/swarm/swarm_openai.py,sha256=wfteywvAGkT5bLmIxX_StHJq8144whYmCRnJASAjOes,1596
-fast_agent_mcp-0.0.13.dist-info/METADATA,sha256=5Mu-PczPn7wfDWw_j_UXpYWlUYhDHOQEcGRvHyxg5MA,16777
-fast_agent_mcp-0.0.13.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.0.13.dist-info/entry_points.txt,sha256=2IXtSmDK9XjWN__RWuRIJTgWyW17wJnJ_h-pb0pZAxo,174
-fast_agent_mcp-0.0.13.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
-fast_agent_mcp-0.0.13.dist-info/RECORD,,
+fast_agent_mcp-0.0.15.dist-info/METADATA,sha256=KL03PExGMGz9tQ9E72MKAnDS6Fi6rSGjoqyYAV3JLd4,22779
+fast_agent_mcp-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fast_agent_mcp-0.0.15.dist-info/entry_points.txt,sha256=2IXtSmDK9XjWN__RWuRIJTgWyW17wJnJ_h-pb0pZAxo,174
+fast_agent_mcp-0.0.15.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
+fast_agent_mcp-0.0.15.dist-info/RECORD,,

mcp_agent/cli/commands/bootstrap.py

@@ -28,7 +28,7 @@ EXAMPLE_TYPES = {
             "router.py",
             "fastagent.config.yaml",
         ],
-        "create_subdir": False,
+        "create_subdir": True,
     },
     "researcher": {
         "description": "Research agent example with additional evaluation/optimization\n"

mcp_agent/core/agent_app.py

@@ -0,0 +1,163 @@
+"""
+Main application wrapper for interacting with agents.
+"""
+
+from typing import Optional, Dict, TYPE_CHECKING
+
+from mcp_agent.app import MCPApp
+from mcp_agent.progress_display import progress_display
+from mcp_agent.workflows.orchestrator.orchestrator import Orchestrator
+from mcp_agent.workflows.parallel.parallel_llm import ParallelLLM
+from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import (
+    EvaluatorOptimizerLLM,
+)
+
+# Import proxies directly - they handle their own circular imports
+from mcp_agent.core.proxies import (
+    BaseAgentProxy,
+    AgentProxy,
+    LLMAgentProxy,
+    RouterProxy,
+    ChainProxy,
+    WorkflowProxy,
+)
+
+# Handle possible circular imports with types
+if TYPE_CHECKING:
+    from mcp_agent.core.types import ProxyDict
+else:
+    ProxyDict = Dict[str, BaseAgentProxy]
+
+
+class AgentApp:
+    """Main application wrapper"""
+
+    def __init__(self, app: MCPApp, agents: ProxyDict):
+        self._app = app
+        self._agents = agents
+        # Optional: set default agent for direct calls
+        self._default = next(iter(agents)) if agents else None
+
+    async def send(self, agent_name: str, message: Optional[str]) -> str:
+        """Core message sending"""
+        if agent_name not in self._agents:
+            raise ValueError(f"No agent named '{agent_name}'")
+
+        if not message or "" == message:
+            return await self.prompt(agent_name)
+
+        proxy = self._agents[agent_name]
+        return await proxy.generate_str(message)
+
+    async def prompt(self, agent_name: Optional[str] = None, default: str = "") -> str:
+        """
+        Interactive prompt for sending messages with advanced features.
+
+        Args:
+            agent_name: Optional target agent name (uses default if not specified)
+            default: Default message to use when user presses enter
+        """
+        from mcp_agent.core.enhanced_prompt import (
+            get_enhanced_input,
+            handle_special_commands,
+        )
+
+        agent = agent_name or self._default
+
+        if agent not in self._agents:
+            raise ValueError(f"No agent named '{agent}'")
+
+        # Pass all available agent names for auto-completion
+        available_agents = list(self._agents.keys())
+
+        # Create agent_types dictionary mapping agent names to their types
+        agent_types = {}
+        for name, proxy in self._agents.items():
+            # Determine agent type based on the proxy type
+            if isinstance(proxy, LLMAgentProxy):
+                # Convert AgentType.BASIC.value ("agent") to "Agent"
+                agent_types[name] = "Agent"
+            elif isinstance(proxy, RouterProxy):
+                agent_types[name] = "Router"
+            elif isinstance(proxy, ChainProxy):
+                agent_types[name] = "Chain"
+            elif isinstance(proxy, WorkflowProxy):
+                # For workflow proxies, check the workflow type
+                workflow = proxy._workflow
+                if isinstance(workflow, Orchestrator):
+                    agent_types[name] = "Orchestrator"
+                elif isinstance(workflow, ParallelLLM):
+                    agent_types[name] = "Parallel"
+                elif isinstance(workflow, EvaluatorOptimizerLLM):
+                    agent_types[name] = "Evaluator"
+                else:
+                    agent_types[name] = "Workflow"
+
+        result = ""
+        while True:
+            with progress_display.paused():
+                # Use the enhanced input method with advanced features
+                user_input = await get_enhanced_input(
+                    agent_name=agent,
+                    default=default,
+                    show_default=(default != ""),
+                    show_stop_hint=True,
+                    multiline=False,  # Default to single-line mode
+                    available_agent_names=available_agents,
+                    syntax=None,  # Can enable syntax highlighting for code input
+                    agent_types=agent_types,  # Pass agent types for display
+                )
+
+                # Handle special commands
+                command_result = await handle_special_commands(user_input, self)
+
+                # Check if we should switch agents
+                if (
+                    isinstance(command_result, dict)
+                    and "switch_agent" in command_result
+                ):
+                    agent = command_result["switch_agent"]
+                    continue
+
+                # Skip further processing if command was handled
+                if command_result:
+                    continue
+
+                if user_input.upper() == "STOP":
+                    return result
+                if user_input == "":
+                    continue
+
+            result = await self.send(agent, user_input)
+            
+            # Check if current agent is a chain that should continue with final agent
+            if agent_types.get(agent) == "Chain":
+                proxy = self._agents[agent]
+                if isinstance(proxy, ChainProxy) and proxy._continue_with_final:
+                    # Get the last agent in the sequence
+                    last_agent = proxy._sequence[-1]
+                    # Switch to that agent for the next iteration
+                    agent = last_agent
+
+        return result
+
+    def __getattr__(self, name: str) -> BaseAgentProxy:
+        """Support: agent.researcher"""
+        if name not in self._agents:
+            raise AttributeError(f"No agent named '{name}'")
+        return AgentProxy(self, name)
+
+    def __getitem__(self, name: str) -> BaseAgentProxy:
+        """Support: agent['researcher']"""
+        if name not in self._agents:
+            raise KeyError(f"No agent named '{name}'")
+        return AgentProxy(self, name)
+
+    async def __call__(
+        self, message: Optional[str] = "", agent_name: Optional[str] = None
+    ) -> str:
+        """Support: agent('message')"""
+        target = agent_name or self._default
+        if not target:
+            raise ValueError("No default agent available")
+        return await self.send(target, message)

mcp_agent/core/agent_types.py

@@ -0,0 +1,16 @@
+"""
+Enum definitions for supported agent types.
+"""
+
+from enum import Enum
+
+
+class AgentType(Enum):
+    """Enumeration of supported agent types."""
+
+    BASIC = "agent"
+    ORCHESTRATOR = "orchestrator"
+    PARALLEL = "parallel"
+    EVALUATOR_OPTIMIZER = "evaluator_optimizer"
+    ROUTER = "router"
+    CHAIN = "chain"

mcp_agent/core/agent_utils.py

@@ -0,0 +1,65 @@
+"""
+Utility functions for agent operations.
+"""
+
+from typing import List, TYPE_CHECKING
+
+from mcp_agent.event_progress import ProgressAction
+
+# Handle circular imports
+if TYPE_CHECKING:
+    from mcp_agent.core.proxies import BaseAgentProxy, LLMAgentProxy
+    from mcp_agent.core.types import AgentOrWorkflow, ProxyDict
+else:
+    from mcp_agent.core.proxies import BaseAgentProxy, LLMAgentProxy
+    # Define minimal types for runtime
+    AgentOrWorkflow = object  # Simple placeholder
+    ProxyDict = dict  # Simple placeholder
+
+
+def unwrap_proxy(proxy: BaseAgentProxy) -> AgentOrWorkflow:
+    """
+    Unwrap a proxy to get the underlying agent or workflow instance.
+
+    Args:
+        proxy: The proxy object to unwrap
+
+    Returns:
+        The underlying Agent or workflow instance
+    """
+    if isinstance(proxy, LLMAgentProxy):
+        return proxy._agent
+    return proxy._workflow
+
+
+def get_agent_instances(
+    agent_names: List[str], active_agents: ProxyDict
+) -> List[AgentOrWorkflow]:
+    """
+    Get list of actual agent/workflow instances from a list of names.
+
+    Args:
+        agent_names: List of agent names to look up
+        active_agents: Dictionary of active agent proxies
+
+    Returns:
+        List of unwrapped agent/workflow instances
+    """
+    return [unwrap_proxy(active_agents[name]) for name in agent_names]
+
+
+def log_agent_load(app, agent_name: str) -> None:
+    """
+    Log agent loading event to application logger.
+    
+    Args:
+        app: The application instance
+        agent_name: Name of the agent being loaded
+    """
+    app._logger.info(
+        f"Loaded {agent_name}",
+        data={
+            "progress_action": ProgressAction.LOADED,
+            "agent_name": agent_name,
+        },
+    )

mcp_agent/core/error_handling.py

@@ -0,0 +1,23 @@
+"""
+Error handling utilities for agent operations.
+"""
+
+from rich import print
+
+
+def handle_error(e: Exception, error_type: str, suggestion: str = None) -> None:
+    """
+    Handle errors with consistent formatting and messaging.
+
+    Args:
+        e: The exception that was raised
+        error_type: Type of error to display
+        suggestion: Optional suggestion message to display
+    """
+    print(f"\n[bold red]{error_type}:")
+    print(getattr(e, "message", str(e)))
+    if hasattr(e, "details") and e.details:
+        print("\nDetails:")
+        print(e.details)
+    if suggestion:
+        print(f"\n{suggestion}")

mcp_agent/core/exceptions.py

@@ -56,6 +56,13 @@ class ModelConfigError(FastAgentError):
         super().__init__(message, details)
 
 
+class CircularDependencyError(FastAgentError):
+    """Raised when we detect a Circular Dependency in the workflow"""
+
+    def __init__(self, message: str, details: str = ""):
+        super().__init__(message, details)
+
+
 class PromptExitError(FastAgentError):
     """Raised from enhanced_prompt when the user requests hard exits"""