agents.supervisor.models¶

Data models for Dynamic Supervisor V2.

This module contains all the Pydantic models and enums used by the dynamic supervisor for agent specifications, capabilities, and configuration.

Classes¶

`AgentCapability`	Rich metadata describing an agent's capabilities.
`AgentDiscoveryMode`	Agent discovery modes for the dynamic supervisor.
`AgentSpec`	Specification for creating an agent dynamically.
`DiscoveryConfig`	Configuration for agent discovery mechanisms.

Module Contents¶

class agents.supervisor.models.AgentCapability(/, **data)¶

Bases: pydantic.BaseModel

Rich metadata describing an agent’s capabilities.

This model captures comprehensive information about what an agent can do, enabling intelligent task-to-agent matching.

Parameters:: data (Any)

name¶: Unique identifier for the agent

agent_type¶: Type of agent (e.g., SimpleAgentV3, ReactAgent)

description¶: Human-readable description of agent’s purpose

specialties¶: List of task domains the agent excels at

tools¶: Names of tools available to this agent

active¶: Whether the agent is currently active

performance_score¶: Historical performance metric (0-1)

usage_count¶: Number of times this agent has been used

last_used¶: Timestamp of last usage (ISO format)

metadata¶: Additional custom metadata

Examples

>>> capability = AgentCapability(
...     name="research_expert",
...     agent_type="ReactAgent",
...     description="Expert at research and information gathering",
...     specialties=["research", "analysis", "web search"],
...     tools=["web_search", "document_reader"]
... )

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.

matches_task(task, threshold=0.3)¶

Calculate match score between this agent’s capabilities and a task.

Parameters:

task (str) – The task description to match against
threshold (float) – Minimum score to consider a match (0-1)

Returns:

Match score between 0 and 1

Return type:

float

classmethod validate_specialties(v)¶

Ensure specialties are lowercase for consistent matching.

Parameters:: v (list[str])
Return type:: list[str]

class agents.supervisor.models.AgentDiscoveryMode¶

Bases: str, enum.Enum

Agent discovery modes for the dynamic supervisor.

MANUAL¶: Use manually provided agent specifications

COMPONENT_DISCOVERY¶: Discover agents from installed components

RAG_DISCOVERY¶: Use RAG to find relevant agent implementations

MCP_DISCOVERY¶: Discover agents via Model Context Protocol

HYBRID¶: Combine multiple discovery methods

Initialize self. See help(type(self)) for accurate signature.

class agents.supervisor.models.AgentSpec(/, **data)¶

Bases: pydantic.BaseModel

Specification for creating an agent dynamically.

This model defines everything needed to instantiate a new agent at runtime, including its type, configuration, and capabilities.

Parameters:: data (Any)

name¶: Unique identifier for the agent

agent_type¶: Type of agent to create (e.g., “SimpleAgentV3”, “ReactAgent”)

description¶: Human-readable description

specialties¶: Task domains this agent should handle

tools¶: Tool names or instances to provide to the agent

config¶: Configuration dictionary for agent initialization

priority¶: Priority level for agent selection (higher = preferred)

enabled¶: Whether this spec can be used to create agents

Examples

>>> spec = AgentSpec(
...     name="code_reviewer",
...     agent_type="ReactAgent",
...     description="Expert code reviewer and analyzer",
...     specialties=["code review", "analysis", "best practices"],
...     tools=["file_reader", "code_analyzer"],
...     config={
...         "temperature": 0.2,
...         "system_message": "You are an expert code reviewer."
...     }
... )

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.

to_capability()¶

Convert this spec to an AgentCapability.

Return type:: AgentCapability

classmethod validate_specialties(v)¶

Ensure specialties are lowercase for consistent matching.

Parameters:: v (list[str])
Return type:: list[str]

class agents.supervisor.models.DiscoveryConfig(/, **data)¶

Bases: pydantic.BaseModel

Configuration for agent discovery mechanisms.

Parameters:: data (Any)

mode¶: Discovery mode to use

component_paths¶: Paths to search for component discovery

rag_collection¶: Collection name for RAG discovery

mcp_endpoints¶: MCP server endpoints for discovery

cache_discoveries¶: Whether to cache discovered agents

discovery_timeout¶: Timeout for discovery operations (seconds)

max_discoveries_per_request¶: Maximum agents to discover per request

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.