agents.supervisor.core.supervisor_agent

SupervisorAgent - Basic supervisor with intelligent routing.

This module provides the SupervisorAgent class, which acts as an orchestrator for multiple specialized agents. It uses LLM-based reasoning to analyze tasks and route them to the most appropriate agent.

Current Status: This is the basic supervisor implementation. For dynamic agent management capabilities, use DynamicSupervisor. For simple routing without ReactAgent overhead, use SimpleSupervisor.

The SupervisorAgent extends ReactAgent to leverage its looping behavior for continuous routing decisions across multi-turn conversations.

Key Features:

• LLM-based routing: Intelligent task analysis and agent selection

• Agent registration: Register specialized agents with descriptions

• Tool aggregation: Automatically collects tools from registered agents

• Conversation tracking: Maintains context across interactions

• Custom routing: Override route_to_agent() for custom logic

• ReactAgent base: Inherits looping and tool execution capabilities

Architecture:

1. User sends query to supervisor

2. Supervisor analyzes query and conversation history

3. LLM makes routing decision based on agent capabilities

4. Query forwarded to selected agent

5. Agent response returned through supervisor

6. Loop continues for multi-turn conversations

Examples

Basic supervisor setup:

>>> from haive.agents.supervisor import SupervisorAgent
>>> from haive.agents.simple import SimpleAgent
>>> from haive.core.engine.aug_llm import AugLLMConfig
>>>
>>> # Create specialized agents
>>> writer = SimpleAgent(
...     name="writer",
...     engine=AugLLMConfig(),
...     system_message="You are an expert writer"
... )
>>>
>>> researcher = SimpleAgent(
...     name="researcher",
...     engine=AugLLMConfig(),
...     system_message="You are a research specialist"
... )
>>>
>>> # Create supervisor
>>> supervisor = SupervisorAgent(
...     name="project_manager",
...     engine=AugLLMConfig(temperature=0.3),
...     registered_agents={
...         "writer": writer,
...         "researcher": researcher
...     }
... )
>>>
>>> # Supervisor automatically routes to appropriate agent
>>> result = await supervisor.arun("Research AI trends and write a summary")

Custom routing logic:

>>> class PrioritySupervisor(SupervisorAgent):
...     def route_to_agent(self, query: str) -> str:
...         # Custom routing for priority tasks
...         if "urgent" in query.lower():
...             return "priority_handler"
...         # Fall back to LLM routing
...         return super().route_to_agent(query)

See also

• haive.agents.supervisor.DynamicSupervisor: For runtime agent management

• haive.agents.supervisor.SimpleSupervisor: For lightweight routing

• haive.agents.react.agent.ReactAgent: Base class providing loop behavior

Classes

SupervisorAgent	Supervisor agent that routes between multiple specialized agents.
SupervisorState	State for supervisor operations.

Module Contents

class agents.supervisor.core.supervisor_agent.SupervisorAgent(/, **data)

Bases: haive.agents.react.agent.ReactAgent

Supervisor agent that routes between multiple specialized agents.

Extends ReactAgent to leverage its looping behavior for continuous routing decisions based on conversation context.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)

build_graph()

Build supervisor graph with agent routing.

Return type:

haive.core.graph.state_graph.base_graph2.BaseGraph

classmethod create_with_agents(agents, name='supervisor', engine=None, **kwargs)

Create supervisor with pre-registered agents.

Parameters:

• agents (list[tuple[str, haive.agents.base.Agent, str]]) – List of (name, agent, description) tuples

• name (str) – Supervisor name

• engine (haive.core.engine.aug_llm.AugLLMConfig | None) – Custom engine config

• **kwargs – Additional arguments

Returns:

Configured SupervisorAgent

Return type:

SupervisorAgent

Examples

supervisor = SupervisorAgent.create_with_agents([

(“writer”, writer_agent, “Creative writing tasks”), (“coder”, coder_agent, “Programming tasks”), (“analyst”, analyst_agent, “Data analysis”)

])

classmethod ensure_supervisor_engine(v)

Ensure supervisor has a low-temperature engine for routing.

register_agent(name, agent, description)

Register an agent with the supervisor.

Parameters:

• name (str) – Unique name for the agent

• agent (haive.agents.base.Agent) – The agent instance

• description (str) – Description of capabilities

Return type:

None

setup_agent()

Setup supervisor with routing configuration.

Return type:

None

unregister_agent(name)

Remove an agent from supervision.

Parameters:

name (str)

Return type:

None

class agents.supervisor.core.supervisor_agent.SupervisorState(/, **data)

Bases: pydantic.BaseModel

State for supervisor operations.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

data (Any)