haive.agents.supervisor.agent
=============================

.. py:module:: haive.agents.supervisor.agent

.. autoapi-nested-parse::

   Dynamic Supervisor V2 - Main agent implementation.

   This module contains the core DynamicSupervisor class that orchestrates
   runtime agent discovery, creation, and task routing.



Classes
-------

.. autoapisummary::

   haive.agents.supervisor.agent.DynamicSupervisor


Functions
---------

.. autoapisummary::

   haive.agents.supervisor.agent.create_dynamic_supervisor


Module Contents
---------------

.. py:class:: DynamicSupervisor(**data)

   Bases: :py:obj:`haive.agents.react.agent.ReactAgent`


   Advanced supervisor that discovers and creates agents at runtime.

   The DynamicSupervisor extends ReactAgent to provide intelligent task routing
   with the ability to discover, create, and manage specialized agents dynamically
   based on task requirements.

   Key capabilities:
       - Dynamic agent discovery from specifications
       - Runtime agent creation and lifecycle management
       - Intelligent task-to-agent matching
       - Performance tracking and optimization
       - Extensible discovery mechanisms

   .. attribute:: name

      Supervisor identifier

   .. attribute:: engine

      LLM configuration for supervisor reasoning

   .. attribute:: agent_specs

      Initial specifications for creatable agents

   .. attribute:: discovery_config

      Configuration for agent discovery

   .. attribute:: max_agents

      Maximum number of active agents to maintain

   .. attribute:: auto_discover

      Whether to automatically discover new agents

   .. attribute:: include_management_tools

      Whether to include agent management tools

   .. rubric:: Examples

   Basic usage with predefined agent specs::

       supervisor = DynamicSupervisor(
           name="task_router",
           agent_specs=[
               AgentSpec(
                   name="researcher",
                   agent_type="ReactAgent",
                   description="Research and analysis expert",
                   specialties=["research", "analysis"],
                   tools=[web_search_tool]
               ),
               AgentSpec(
                   name="writer",
                   agent_type="SimpleAgent",
                   description="Content creation expert",
                   specialties=["writing", "editing"]
               )
           ]
       )

       result = await supervisor.arun(
           "Research quantum computing and write a summary"
       )

   Initialize the dynamic supervisor.

   :param \*\*data: Configuration parameters


   .. py:method:: arun(input_data)
      :async:


      Run the supervisor asynchronously.

      :param input_data: Task input (string, dict, or messages)

      :returns: Agent execution result



   .. py:method:: get_metrics()

      Get supervisor performance metrics.

      :returns: Dictionary of metrics including agent stats



   .. py:method:: run(input_data)

      Run the supervisor synchronously.

      :param input_data: Task input

      :returns: Agent execution result



   .. py:method:: validate_agent_specs(v)
      :classmethod:


      Validate agent specifications have unique names.



.. py:function:: create_dynamic_supervisor(name = 'dynamic_supervisor', agent_specs = None, discovery_mode = AgentDiscoveryMode.MANUAL, **kwargs)

   Factory function to create a configured dynamic supervisor.

   :param name: Supervisor name
   :param agent_specs: Initial agent specifications
   :param discovery_mode: How to discover new agents
   :param \*\*kwargs: Additional configuration

   :returns: Configured DynamicSupervisor instance

   .. rubric:: Examples

   >>> supervisor = create_dynamic_supervisor(
   ...     name="task_router",
   ...     agent_specs=[math_spec, research_spec],
   ...     discovery_mode="manual",
   ...     max_agents=20
   ... )