haive.agents.supervisor.tools
=============================

.. py:module:: haive.agents.supervisor.tools

.. autoapi-nested-parse::

   Tools and utilities for Dynamic Supervisor V2.

   This module provides tools for agent creation, discovery, matching, and
   workflow coordination.



Classes
-------

.. autoapisummary::

   haive.agents.supervisor.tools.AgentManagementTools


Functions
---------

.. autoapisummary::

   haive.agents.supervisor.tools.create_agent_from_spec
   haive.agents.supervisor.tools.create_handoff_tool
   haive.agents.supervisor.tools.discover_agents
   haive.agents.supervisor.tools.find_matching_agent_specs


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

.. py:class:: AgentManagementTools

   Collection of tools for managing agents in the supervisor.

   These tools can be provided to the supervisor to enable dynamic
   agent management capabilities.


   .. py:method:: create_agent_stats_tool(state_accessor)
      :staticmethod:


      Create a tool for viewing agent statistics.

      :param state_accessor: Function to access current state

      :returns: Tool for viewing agent stats



   .. py:method:: create_list_agents_tool(state_accessor)
      :staticmethod:


      Create a tool for listing available agents.

      :param state_accessor: Function to access current state

      :returns: Tool for listing agents



.. py:function:: create_agent_from_spec(spec)

   Create an agent instance from a specification.

   This function instantiates the appropriate agent type based on the spec,
   configuring it with the provided settings and tools.

   :param spec: Agent specification containing type, config, and tools

   :returns: Instantiated agent instance

   :raises ValueError: If agent_type is not supported

   .. rubric:: Examples

   >>> spec = AgentSpec(
   ...     name="calculator",
   ...     agent_type="ReactAgent",
   ...     config={"temperature": 0.1}
   ... )
   >>> agent = create_agent_from_spec(spec)


.. py:function:: create_handoff_tool(agent_name, description)

   Create a tool for handing off tasks to a specific agent.

   :param agent_name: Name of the agent to hand off to
   :param description: Description of what the agent does

   :returns: Tool that can be used to route tasks to the agent

   .. rubric:: Examples

   >>> tool = create_handoff_tool("math_expert", "Handles math problems")
   >>> result = tool.invoke({"task": "Calculate 2+2"})


.. py:function:: discover_agents(task, discovery_config, existing_agents = None)

   Discover new agents based on task requirements.

   This function implements various discovery strategies to find or create
   agent specifications that can handle the given task.

   :param task: Task description requiring agents
   :param discovery_config: Configuration for discovery process
   :param existing_agents: Set of already discovered agent names to avoid duplicates

   :returns: List of discovered agent specifications

   .. note::

      Currently implements MANUAL mode. Other modes (COMPONENT_DISCOVERY,
      RAG_DISCOVERY, MCP_DISCOVERY) are planned for future releases.


.. py:function:: find_matching_agent_specs(task, available_specs, threshold = 0.3, max_results = 5)

   Find agent specifications that match a given task.

   Uses specialty matching and keyword analysis to find the most suitable
   agent specifications for a task.

   :param task: Task description to match against
   :param available_specs: List of available agent specifications
   :param threshold: Minimum match score (0-1) to include a spec
   :param max_results: Maximum number of results to return

   :returns: List of matching specs, sorted by relevance

   .. rubric:: Examples

   >>> specs = [math_spec, research_spec, writing_spec]
   >>> matches = find_matching_agent_specs(
   ...     "Calculate the compound interest",
   ...     specs
   ... )
   >>> assert matches[0].name == "math_expert"