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

{fast_agent_mcp-0.0.14.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.14
+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,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,7 +257,9 @@ 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.
 
 ## Get started:
 
@@ -294,12 +296,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 +323,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 +354,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")` 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
 
-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, 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. 
+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 Agent results verbatim.
+
+The 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 +428,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 +445,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,6 +454,8 @@ 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
 
 ```python
@@ -474,5 +496,4 @@ When `human_input` is set to true for an Agent, it is presented with the option
 
 ### Features to add.
 
- - Chat History Clear.
-
+- Chat History Clear.

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

@@ -17,10 +17,16 @@ mcp_agent/cli/commands/bootstrap.py,sha256=z1wZSy8vO_GZPGLrFGzG3EKFQgAHC08jiIdVy
 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/error_handling.py,sha256=D3HMW5odrbJvaKqcpCGj6eDXrbFcuqYaCZz7fyYiTu4,623
 mcp_agent/core/exceptions.py,sha256=a2-JGRwFFRoQEPuAq0JC5PhAJ5TO3xVJfdS4-VN29cw,2225
-mcp_agent/core/fastagent.py,sha256=nMAOhxoS1KqV9IueIFpsYz7yZoVr2pNntI5FoHnzWFE,58011
+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,6 +59,7 @@ 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
@@ -63,7 +70,7 @@ mcp_agent/resources/examples/workflows/evaluator.py,sha256=FZy-ciZafdqSHUW67LKdH
 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.14.dist-info/METADATA,sha256=7qlGcDMbyR9SsI2Sx5bnSdZxrUmrGxptJLmSKVQm4l4,22080
-fast_agent_mcp-0.0.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.0.14.dist-info/entry_points.txt,sha256=2IXtSmDK9XjWN__RWuRIJTgWyW17wJnJ_h-pb0pZAxo,174
-fast_agent_mcp-0.0.14.dist-info/licenses/LICENSE,sha256=cN3FxDURL9XuzE5mhK9L2paZo82LTfjwCYVT7e3j0e4,10939
-fast_agent_mcp-0.0.14.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/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}")