haive.agents.dynamic_supervisor.models¶

Data models for dynamic supervisor agent.

This module contains Pydantic models used by the dynamic supervisor for agent metadata, routing information, and configuration.

Classes:: AgentInfo: Metadata container for agents (v1 with exclusion) AgentInfoV2: Experimental version with full serialization AgentRequest: Model for agent addition requests RoutingDecision: Model for routing decisions

Example

Creating agent metadata:

info = AgentInfo(
    agent=search_agent,
    name="search",
    description="Web search specialist",
    active=True
)

Classes¶

`AgentInfo`	Information about an agent including instance and metadata.
`AgentInfoV2`	Experimental version with full agent serialization.
`AgentRequest`	Model for requesting a new agent be added.
`RoutingDecision`	Model for supervisor routing decisions.

Module Contents¶

class haive.agents.dynamic_supervisor.models.AgentInfo(/, **data)¶

Bases: pydantic.BaseModel

Information about an agent including instance and metadata.

This model stores agent metadata and the agent instance itself. The agent field is excluded from serialization to avoid msgpack serialization issues with complex objects.

Parameters:: data (Any)

agent¶: The actual agent instance (excluded from serialization)

name¶: Unique identifier for the agent

description¶: Human-readable description of capabilities

active¶: Whether the agent is currently active

capabilities¶: List of capability keywords for discovery

metadata¶: Additional metadata (versions, config, etc.)

Example

Creating agent info:

info = AgentInfo(
    agent=math_agent,
    name="math",
    description="Mathematics and calculation expert",
    capabilities=["math", "calculation", "statistics"]
)

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.

activate()¶

Activate the agent.

Return type:: None

deactivate()¶

Deactivate the agent.

Return type:: None

extract_agent_info()¶

Extract name and description from agent if not provided.

Returns:: Self with extracted information
Return type:: AgentInfo

get_agent()¶

Get the agent instance.

Returns:: The agent instance
Return type:: Any

is_active()¶

Check if agent is active.

Returns:: True if active, False otherwise
Return type:: bool

matches_capability(required)¶

Check if agent has a required capability.

Parameters:: required (str) – Capability keyword to check
Returns:: True if agent has the capability
Return type:: bool

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class haive.agents.dynamic_supervisor.models.AgentInfoV2(/, **data)¶

Bases: pydantic.BaseModel

Experimental version with full agent serialization.

This version attempts to serialize the agent object. Requires custom serialization logic or agents that support model_dump().

Warning

Experimental - may not work with all agent types.

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)

serialize_agent(agent)¶

Attempt to serialize agent to dict.

Parameters:: agent (Any) – Agent instance
Returns:: Serialized representation
Return type:: dict[str, Any]

model_config¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class haive.agents.dynamic_supervisor.models.AgentRequest(/, **data)¶

Bases: pydantic.BaseModel

Model for requesting a new agent be added.

Used when the supervisor identifies a missing capability and needs to request a new agent from an agent builder or registry.

Parameters:: data (Any)

capability¶: The required capability (e.g., “translation”, “code_analysis”)

task_context¶: Context about what task needs this capability

suggested_name¶: Suggested name for the new agent

requirements¶: Specific requirements or constraints

Example

Requesting a new agent:

request = AgentRequest(
    capability="translation",
    task_context="Need to translate search results to French",
    suggested_name="translator",
    requirements=["Support French", "Maintain formatting"]
)

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.

class haive.agents.dynamic_supervisor.models.RoutingDecision(/, **data)¶

Bases: pydantic.BaseModel

Model for supervisor routing decisions.

Represents a decision made by the supervisor about which agent to route to or what action to take.

Parameters:: data (Any)

agent_name¶: Name of agent to route to (or “END”)

task¶: Task to give to the agent

reasoning¶: Explanation of the routing decision

confidence¶: Confidence level in the decision (0-1)

alternatives¶: Other agents that could handle this

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.