flock-core 0.2.17__py3-none-any.whl → 0.3.1__py3-none-any.whl

flock/core/flock_agent.py

@@ -4,168 +4,46 @@ import asyncio
 import json
 import os
 from abc import ABC
-from collections.abc import Awaitable, Callable
-from dataclasses import dataclass, field
+from collections.abc import Callable
 from typing import Any, TypeVar, Union
 
 import cloudpickle
+from opentelemetry import trace
 from pydantic import BaseModel, Field
 
 from flock.core.context.context import FlockContext
-from flock.core.logging.formatters.themed_formatter import (
-    ThemedAgentResultFormatter,
-)
-from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.flock_evaluator import FlockEvaluator
+from flock.core.flock_module import FlockModule
 from flock.core.logging.logging import get_logger
-from flock.core.mixin.dspy_integration import AgentType, DSPyIntegrationMixin
-from flock.core.mixin.prompt_parser import PromptParserMixin
-
-logger = get_logger("flock")
-
-
-from opentelemetry import trace
 
+logger = get_logger("agent")
 tracer = trace.get_tracer(__name__)
 
 
 T = TypeVar("T", bound="FlockAgent")
 
 
-@dataclass
-class FlockAgentConfig:
-    """Configuration options for a FlockAgent."""
-
-    agent_type_override: AgentType = field(
-        default=None,
-        metadata={
-            "description": "Overrides the agent type. TOOL USE ONLY WORKS WITH REACT"
-        },
-    )
-    disable_output: bool = field(
-        default=False, metadata={"description": "Disables the agent's output."}
-    )
-    temperature: float = field(
-        default=0.0, metadata={"description": "Temperature for the LLM"}
-    )
-    max_tokens: int = field(
-        default=2000, metadata={"description": "Max tokens for the LLM"}
-    )
-
-
-@dataclass
-class FlockAgentOutputConfig:
-    """Configuration options for a FlockAgent."""
-
-    render_table: bool = field(
-        default=False, metadata={"description": "Renders a table."}
-    )
-    theme: OutputTheme = field(  # type: ignore
-        default=OutputTheme.afterglow,
-        metadata={"description": "Disables the agent's output."},
-    )
-    max_length: int = field(
-        default=1000, metadata={"description": "Disables the agent's output."}
-    )
-    wait_for_input: bool = field(
-        default=False, metadata={"description": "Wait for input."}
-    )
-    write_to_file: bool = field(
-        default=False, metadata={"description": "Write to file."}
-    )
-
-
-@dataclass
-class HandOff:
+class HandOff(BaseModel):
     """Base class for handoff returns."""
 
-    next_agent: Union[str, "FlockAgent"] = field(
-        default="", metadata={"description": "Next agent to invoke"}
+    next_agent: Union[str, "FlockAgent"] = Field(
+        default="", description="Next agent to invoke"
     )
-    input: dict[str, Any] = field(
+    input: dict[str, Any] = Field(
         default_factory=dict,
-        metadata={"description": "Input data for the next agent"},
+        description="Input data for the next agent",
     )
-    context: FlockContext = field(
-        default=None, metadata={"description": "Override context parameters"}
+    context: FlockContext = Field(
+        default=None, descrio="Override context parameters"
     )
 
 
-class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
-    """FlockAgent is the core, declarative base class for all agents in the Flock framework.
-
-    Due to its declarative nature, FlockAgent does not rely on constructing classical prompts manually.
-    Instead, each agent is defined by simply declaring:
-    - Its expected inputs (what data it needs),
-    - Its expected outputs (what data it produces), and
-    - Any optional tools it can use during execution.
-
-    In a declarative model, you describe *what* you expect rather than *how* to compute it. This means that
-    instead of embedding prompt engineering logic directly in your code, you specify a concise signature.
-    At runtime, the Flock framework automatically:
-    - Resolves the inputs from a pre-computed context,
-    - Constructs a precise prompt for the underlying language model (using metadata such as type hints
-        and human-readable descriptions), and
-    - Invokes the appropriate tools if needed.
-
-    This approach minimizes hidden dependencies and boilerplate code. It allows developers to focus solely on
-    what data the agent should work with and what result it should produce, without worrying about the intricacies
-    of prompt formatting or context management.
-
-    For details on how Flock resolves inputs, please refer to the documentation.
-
-    Key benefits of the declarative approach include:
-    - **Clarity:** The agent's interface (inputs and outputs) is explicitly defined.
-    - **Reusability:** Agents can be easily serialized, shared, and reused since they are built as Pydantic models.
-    - **Modularity:** By receiving a dictionary of pre-resolved inputs, agents operate independently of the global context,
-        making them easier to test and debug.
-    - **Extensibility:** Additional metadata (like detailed descriptions for each key) can be embedded and later used to
-        refine the prompt for the LLM.
-
-    Since FlockAgent is a Pydantic BaseModel, it can be serialized to and from JSON. This ensures that the agent's
-    configuration and state are easily stored, transmitted, and reproduced.
-
-    **Implementation Example:**
-
-    Below is an example of how to define and instantiate a FlockAgent:
-
-        from flock_agent import FlockAgent
-        import basic_tools
-
-        # Define an agent by declaring its inputs, outputs, and optional tools.
-        idea_agent = FlockAgent(
-            name="idea_agent",
-            input="query: str | The search query, context: dict | The full conversation context",
-            output="a_fun_software_project_idea: str | The generated software project idea",
-            tools=[basic_tools.web_search_tavily],
-        )
-
-        # At runtime, Flock automatically resolves inputs and calls the agent:
-        resolved_inputs = {
-            "query": "A new social media app",
-            "context": {"previous_idea": "a messaging platform"}
-        }
-        result = await idea_agent.run(resolved_inputs)
-
-    In this example:
-    - The agent declares that it needs a `query` (a string describing what to search for) and a `context` (a dictionary
-        containing additional information).
-    - It produces a `a_fun_software_project_idea` (a string with the generated idea).
-    - The tool `basic_tools.web_search_tavily` is available for the agent to use if needed.
-    - When the agent is run, the Flock framework resolves the inputs, constructs the appropriate prompt using the
-        declared metadata, and returns the result.
-
-    This declarative style streamlines agent creation and execution, making the framework highly modular, testable,
-    and production-ready.
-
-    In the future options will be provided to optimize the "hidden" prompt generation and execution so the agent will
-    perform close to its theoretical maximum.
-    """
-
+class FlockAgent(BaseModel, ABC):
     name: str = Field(..., description="Unique identifier for the agent.")
     model: str | None = Field(
         None, description="The model to use (e.g., 'openai/gpt-4o')."
     )
-    description: str | Callable[..., str] = Field(
+    description: str | Callable[..., str] | None = Field(
         "", description="A human-readable description of the agent."
     )
 
@@ -194,7 +72,7 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
         description="Set to True to enable caching of the agent's results.",
     )
 
-    hand_off: str | Callable[..., Any] | None = Field(
+    hand_off: str | HandOff | Callable[..., HandOff] | None = Field(
         None,
         description=(
             "Specifies the next agent in the workflow or a callable that determines the handoff. "
@@ -202,160 +80,107 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
         ),
     )
 
-    termination: str | Callable[..., str] | None = Field(
+    evaluator: FlockEvaluator = Field(
         None,
-        description="An optional termination condition or phrase used to indicate when the agent should stop processing.",
+        description="Evaluator to use for agent evaluation",
     )
 
-    config: FlockAgentConfig = Field(
-        default_factory=FlockAgentConfig,
-        description="Configuration options for the agent, such as serialization settings.",
+    modules: dict[str, FlockModule] = Field(
+        default_factory=dict,
+        description="FlockModules attached to this agent",
     )
 
-    output_config: FlockAgentOutputConfig = Field(
-        default_factory=FlockAgentOutputConfig,
-        description="Configuration options for the agent's output.",
-    )
+    def add_module(self, module: FlockModule) -> None:
+        """Add a module to this agent."""
+        self.modules[module.name] = module
 
-    # Lifecycle callback fields: if provided, these callbacks are used instead of overriding the methods.
-    initialize_callback: Callable[[dict[str, Any]], Awaitable[None]] | None = (
-        Field(
-            default=None,
-            description="Optional callback function for initialization. If provided, this async function is called with the inputs.",
-        )
-    )
-    evaluate_callback: (
-        Callable[[dict[str, Any]], Awaitable[dict[str, Any]]] | None
-    ) = Field(
-        default=None,
-        description="Optional callback function for evaluate. If provided, this async function is called with the inputs instead of the internal evaluate",
-    )
-    terminate_callback: (
-        Callable[[dict[str, Any], dict[str, Any]], Awaitable[None]] | None
-    ) = Field(
-        default=None,
-        description="Optional callback function for termination. If provided, this async function is called with the inputs and result.",
-    )
-    on_error_callback: (
-        Callable[[Exception, dict[str, Any]], Awaitable[None]] | None
-    ) = Field(
-        default=None,
-        description="Optional callback function for error handling. If provided, this async function is called with the error and inputs.",
-    )
+    def remove_module(self, module_name: str) -> None:
+        """Remove a module from this agent."""
+        if module_name in self.modules:
+            del self.modules[module_name]
+
+    def get_module(self, module_name: str) -> FlockModule | None:
+        """Get a module by name."""
+        return self.modules.get(module_name)
+
+    def get_enabled_modules(self) -> list[FlockModule | None]:
+        """Get a module by name."""
+        return [m for m in self.modules.values() if m.config.enabled]
 
     # Lifecycle hooks
     async def initialize(self, inputs: dict[str, Any]) -> None:
-        """Called at the very start of the agent's execution.
+        with tracer.start_as_current_span("agent.initialize") as span:
+            span.set_attribute("agent.name", self.name)
+            span.set_attribute("inputs", str(inputs))
 
-        Override this method or provide an `initialize_callback` to perform setup tasks such as input validation or resource loading.
-        """
-        if self.initialize_callback is not None:
-            await self.initialize_callback(self, inputs)
-        else:
-            pass
+            try:
+                for module in self.get_enabled_modules():
+                    logger.info(
+                        f"agent.initialize - module {module.name}",
+                        agent=self.name,
+                    )
+                    await module.initialize(self, inputs)
+            except Exception as module_error:
+                logger.error(
+                    "Error during initialize",
+                    agent=self.name,
+                    error=str(module_error),
+                )
+                span.record_exception(module_error)
 
     async def terminate(
         self, inputs: dict[str, Any], result: dict[str, Any]
     ) -> None:
-        """Called at the very end of the agent's execution.
-
-        Override this method or provide a `terminate_callback` to perform cleanup tasks such as releasing resources or logging results.
-        """
-        if self.terminate_callback is not None:
-            await self.terminate_callback(self, inputs, result)
-        else:
-            pass
+        with tracer.start_as_current_span("agent.terminate") as span:
+            span.set_attribute("agent.name", self.name)
+            span.set_attribute("inputs", str(inputs))
+            span.set_attribute("result", str(result))
+            logger.info(
+                f"agent.terminate",
+                agent=self.name,
+            )
+            try:
+                for module in self.get_enabled_modules():
+                    await module.terminate(self, inputs, inputs)
+            except Exception as module_error:
+                logger.error(
+                    "Error during terminate",
+                    agent=self.name,
+                    error=str(module_error),
+                )
+                span.record_exception(module_error)
 
     async def on_error(self, error: Exception, inputs: dict[str, Any]) -> None:
-        """Called if the agent encounters an error during execution.
-
-        Override this method or provide an `on_error_callback` to implement custom error handling or recovery strategies.
-        """
-        if self.on_error_callback is not None:
-            await self.on_error_callback(self, error, inputs)
-        else:
-            pass
+        with tracer.start_as_current_span("agent.on_error") as span:
+            span.set_attribute("agent.name", self.name)
+            span.set_attribute("inputs", str(inputs))
+            try:
+                for module in self.get_enabled_modules():
+                    await module.on_error(self, error, inputs)
+            except Exception as module_error:
+                logger.error(
+                    "Error during on_error",
+                    agent=self.name,
+                    error=str(module_error),
+                )
+                span.record_exception(module_error)
 
     async def evaluate(self, inputs: dict[str, Any]) -> dict[str, Any]:
-        """Process the agent's task using the provided inputs and return the result.
-
-        This asynchronous method is the core execution engine for a FlockAgent. It performs the following steps:
-
-        1. **Extract Descriptions:**
-            Parses the agent's configured input and output strings to extract human-readable descriptions.
-            These strings are expected to use the format "key: type_hint | description". The method removes the
-            type hints and builds dictionaries that map each key to its corresponding description.
-
-        2. **Construct the Prompt:**
-            Based on the extracted descriptions, the method builds a detailed prompt that clearly lists all input
-            fields (with their descriptions) and output fields. This prompt is designed to guide the language model,
-            ensuring that it understands what inputs are provided and what outputs are expected.
-
-        3. **Configure the Language Model:**
-            The method initializes and configures a language model using the dspy library. The agent's model
-            (e.g., "openai/gpt-4o") is used to set up the language model, ensuring that it is ready to process the prompt.
-
-        4. **Execute the Task:**
-            Depending on whether the agent has been configured with additional tools:
-                - **With Tools:** A ReAct task is instantiated. This task interleaves reasoning and tool usage,
-                allowing the agent to leverage external functionalities during execution.
-                - **Without Tools:** A Predict task is used for a straightforward generation based on the prompt.
-
-        5. **Process the Result:**
-            After execution, the method attempts to convert the result to a dictionary. It also ensures that each
-            expected input key is present in the output (by setting a default value from the inputs if necessary).
-
-        6. **Error Handling:**
-            Any exceptions raised during the process are caught, logged (or printed), and then re-raised to allow
-            higher-level error handling. This ensures that errors are not silently ignored and can be properly diagnosed.
-
-        **Arguments:**
-            inputs (dict[str, Any]): A dictionary containing all the resolved input values required by the agent.
-                These inputs are typically obtained from the global context or from the output of a previous agent.
-
-        **Returns:**
-            dict[str, Any]: A dictionary containing the output generated by the agent. This output adheres to the
-                agent's declared output fields and includes any fallback values for missing inputs.
-
-        **Usage Example:**
-
-            Suppose an agent is declared with the following configuration:
-                input = "query: str | The search query, context: dict | Additional context"
-                output = "idea: str | The generated software project idea"
-
-            When invoked with:
-                inputs = {"query": "build an app", "context": {"previous_idea": "messaging app"}}
-
-            The method will:
-                - Parse the descriptions to create:
-                    input_descriptions = {"query": "The search query", "context": "Additional context"}
-                    output_descriptions = {"idea": "The generated software project idea"}
-                - Construct a prompt that lists these inputs and outputs clearly.
-                - Configure the language model and execute the appropriate task (ReAct if tools are provided, otherwise Predict).
-                - Return a dictionary similar to:
-                    {"idea": "A fun app idea based on ...", "query": "build an app", "context": {"previous_idea": "messaging app"}}
-        """
         with tracer.start_as_current_span("agent.evaluate") as span:
             span.set_attribute("agent.name", self.name)
             span.set_attribute("inputs", str(inputs))
-            if self.evaluate_callback is not None:
-                return await self.evaluate_callback(self, inputs)
+
+            for module in self.get_enabled_modules():
+                inputs = await module.pre_evaluate(self, inputs)
+
             try:
-                # Create and configure the signature and language model.
-                self.__dspy_signature = self.create_dspy_signature_class(
-                    self.name,
-                    self.description,
-                    f"{self.input} -> {self.output}",
-                )
-                self._configure_language_model()
-                agent_task = self._select_task(
-                    self.__dspy_signature,
-                    agent_type_override=self.config.agent_type_override,
-                )
-                # Execute the task.
-                result = agent_task(**inputs)
-                result = self._process_result(result, inputs)
+                result = await self.evaluator.evaluate(self, inputs, self.tools)
+
+                for module in self.get_enabled_modules():
+                    result = await module.post_evaluate(self, inputs, result)
+
                 span.set_attribute("result", str(result))
+
                 logger.info("Evaluation successful", agent=self.name)
                 return result
             except Exception as eval_error:
@@ -394,58 +219,14 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
         return asyncio.run(self.run_async(inputs))
 
     async def run_async(self, inputs: dict[str, Any]) -> dict[str, Any]:
-        """Run the agent with the given inputs and return its generated output.
-
-        This method represents the primary execution flow for a FlockAgent and performs the following
-        lifecycle steps in sequence:
-
-        1. **Initialization:**
-            Calls the `initialize(inputs)` hook to perform any necessary pre-run setup, such as input
-            validation, resource allocation, or logging. This ensures that the agent is properly configured
-            before processing begins.
-
-        2. **Evaluation:**
-            Invokes the internal `_evaluate(inputs)` method, which constructs a detailed prompt (incorporating
-            input and output descriptions), configures the underlying language model via dspy, and executes the
-            main task (using a ReAct task if tools are provided, or a Predict task otherwise).
-
-        3. **Termination:**
-            Calls the `terminate(inputs, result)` hook after evaluation, allowing the agent to clean up any
-            resources or perform post-run actions (such as logging the output).
-
-        4. **Output Return:**
-            Returns a dictionary containing the agent's output. This output conforms to the agent's declared
-            output fields and may include any default or fallback values for missing inputs.
-
-        If an error occurs during any of these steps, the `on_error(error, inputs)` hook is invoked to handle
-        the exception (for instance, by logging detailed error information). The error is then re-raised, ensuring
-        that higher-level error management can address the failure.
-
-        **Arguments:**
-            inputs (dict[str, Any]): A dictionary containing the resolved input values required by the agent.
-                These inputs are typically derived from the agent's declared input signature and may include data
-                provided by previous agents or from a global context.
-
-        **Returns:**
-            dict[str, Any]: A dictionary containing the output generated by the agent. The output structure
-            adheres to the agent's declared output fields.
-
-        **Example:**
-            Suppose an agent is defined with:
-                input  = "query: str | The search query, context: dict | Additional context"
-                output = "result: str | The generated idea"
-            When executed with:
-                inputs = {"query": "build a chatbot", "context": {"user": "Alice"}}
-            The method might return:
-                {"result": "A conversational chatbot that uses AI to...", "query": "build a chatbot", "context": {"user": "Alice"}}
-        """
         with tracer.start_as_current_span("agent.run") as span:
             span.set_attribute("agent.name", self.name)
             span.set_attribute("inputs", str(inputs))
             try:
                 await self.initialize(inputs)
+
                 result = await self.evaluate(inputs)
-                self.display_output(result)
+
                 await self.terminate(inputs, result)
                 span.set_attribute("result", str(result))
                 logger.info("Agent run completed", agent=self.name)
@@ -458,60 +239,7 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
                 span.record_exception(run_error)
                 raise
 
-    def display_info(self) -> None:
-        pass
-
-    def display_output(self, result: dict[str, Any]) -> None:
-        """Display the agent's output using the configured output formatter."""
-        ThemedAgentResultFormatter(
-            self.output_config.theme,
-            self.output_config.max_length,
-            self.output_config.render_table,
-            self.output_config.wait_for_input,
-            self.output_config.write_to_file,
-        ).display_result(result, self.name)
-
     async def run_temporal(self, inputs: dict[str, Any]) -> dict[str, Any]:
-        """Execute this agent via a Temporal workflow for enhanced fault tolerance and asynchronous processing.
-
-        This method enables remote execution of the agent within a Temporal environment, leveraging Temporal's
-        capabilities for persistence, retries, and distributed error handling. The workflow encapsulates the agent's
-        logic so that it can run on Temporal workers, providing robustness and scalability in production systems.
-
-        The method performs these steps:
-        1. **Connect to Temporal:**
-            Establishes a connection to the Temporal server using a Temporal client configured with the appropriate
-            namespace (default is "default").
-        2. **Serialization:**
-            Serializes the agent instance (via `to_dict()`) along with the provided inputs. This step converts any
-            callable objects (e.g., lifecycle hooks or tools) into a storable format using cloudpickle.
-        3. **Activity Invocation:**
-            Triggers a designated Temporal activity (e.g., `run_flock_agent_activity`) by passing the serialized agent
-            data and inputs. The Temporal activity is responsible for executing the agent's logic in a fault-tolerant
-            manner.
-        4. **Return Output:**
-            Awaits and returns the resulting output from the Temporal workflow as a dictionary, consistent with the
-            output structure of the local `run()` method.
-
-        If any error occurs during these steps, the error is logged and re-raised to ensure that failure is properly
-        handled by higher-level error management systems.
-
-        **Arguments:**
-            inputs (dict[str, Any]): A dictionary containing the resolved inputs required by the agent, similar to those
-                provided to the local `run()` method.
-
-        **Returns:**
-            dict[str, Any]: A dictionary containing the output produced by the agent after remote execution via Temporal.
-                The output format is consistent with that of the local `run()` method.
-
-        **Example:**
-            Given an agent defined with:
-                input  = "query: str | The search query, context: dict | Additional context"
-                output = "result: str | The generated idea"
-            Calling:
-                result = await agent.run_temporal({"query": "analyze data", "context": {"source": "sales"}})
-            will execute the agent on a Temporal worker and return the output in a structured dictionary format.
-        """
         with tracer.start_as_current_span("agent.run_temporal") as span:
             span.set_attribute("agent.name", self.name)
             span.set_attribute("inputs", str(inputs))
@@ -548,12 +276,6 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
                 raise
 
     def resolve_callables(self, context) -> None:
-        """Resolve any callable fields in the agent instance using the provided context.
-
-        This method resolves any callable fields in the agent instance using the provided context. It iterates over
-        the agent's fields and replaces any callable objects (such as lifecycle hooks or tools) with their corresponding
-        resolved values from the context. This ensures that the agent is fully configured and ready
-        """
         if isinstance(self.input, Callable):
             self.input = self.input(context)
         if isinstance(self.output, Callable):
@@ -562,41 +284,6 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
             self.description = self.description(context)
 
     def to_dict(self) -> dict[str, Any]:
-        """Serialize the FlockAgent instance to a dictionary.
-
-        This method converts the entire agent instance—including its configuration, state, and lifecycle hooks—
-        into a dictionary format. It uses cloudpickle to serialize any callable objects (such as functions or
-        methods), converting them into hexadecimal string representations. This ensures that the agent can be
-        easily persisted, transmitted, or logged as JSON.
-
-        The serialization process is recursive:
-        - If a field is a callable (and not a class), it is serialized using cloudpickle.
-        - Lists and dictionaries are processed recursively to ensure that all nested callables are properly handled.
-
-        **Returns:**
-            dict[str, Any]: A dictionary representing the FlockAgent, which includes all of its configuration data.
-            This dictionary is suitable for storage, debugging, or transmission over the network.
-
-        **Example:**
-            For an agent defined as:
-                name = "idea_agent",
-                model = "openai/gpt-4o",
-                input = "query: str | The search query, context: dict | The full conversation context",
-                output = "idea: str | The generated idea"
-            Calling `agent.to_dict()` might produce:
-                {
-                    "name": "idea_agent",
-                    "model": "openai/gpt-4o",
-                    "input": "query: str | The search query, context: dict | The full conversation context",
-                    "output": "idea: str | The generated idea",
-                    "tools": ["<serialized tool representation>"],
-                    "use_cache": False,
-                    "hand_off": None,
-                    "termination": None,
-                    ...
-                }
-        """
-
         def convert_callable(obj: Any) -> Any:
             if callable(obj) and not isinstance(obj, type):
                 return cloudpickle.dumps(obj).hex()
@@ -607,43 +294,16 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
             return obj
 
         data = self.model_dump()
+        module_data = {}
+        for name, module in self.modules.items():
+            module_data[name] = module.dict()
+
+        data["modules"] = module_data
+
         return convert_callable(data)
 
     @classmethod
     def from_dict(cls: type[T], data: dict[str, Any]) -> T:
-        """Deserialize a FlockAgent instance from a dictionary.
-
-        This class method reconstructs a FlockAgent from its serialized dictionary representation, as produced
-        by the `to_dict()` method. It recursively processes the dictionary to convert any serialized callables
-        (stored as hexadecimal strings via cloudpickle) back into executable callable objects.
-
-        **Arguments:**
-            data (dict[str, Any]): A dictionary representation of a FlockAgent, typically produced by `to_dict()`.
-                The dictionary should contain all configuration fields and state information necessary to fully
-                reconstruct the agent.
-
-        **Returns:**
-            FlockAgent: An instance of FlockAgent reconstructed from the provided dictionary. The deserialized agent
-            will have the same configuration, state, and behavior as the original instance.
-
-        **Example:**
-            Suppose you have the following dictionary:
-                {
-                    "name": "idea_agent",
-                    "model": "openai/gpt-4o",
-                    "input": "query: str | The search query, context: dict | The full conversation context",
-                    "output": "idea: str | The generated idea",
-                    "tools": ["<serialized tool representation>"],
-                    "use_cache": False,
-                    "hand_off": None,
-                    "termination": None,
-                    ...
-                }
-            Then, calling:
-                agent = FlockAgent.from_dict(data)
-            will return a FlockAgent instance with the same properties and behavior as when it was originally serialized.
-        """
-
         def convert_callable(obj: Any) -> Any:
             if isinstance(obj, str) and len(obj) > 2:
                 try:
@@ -656,5 +316,15 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
                 return {k: convert_callable(v) for k, v in obj.items()}
             return obj
 
+        module_data = data.pop("modules", {})
         converted = convert_callable(data)
-        return cls(**converted)
+        agent = cls(**converted)
+
+        for name, module_dict in module_data.items():
+            module_type = module_dict.pop("type", None)
+            if module_type:
+                module_class = globals()[module_type]
+                module = module_class(**module_dict)
+                agent.add_module(module)
+
+        return agent