Agentic Patterns#

This page presents all APIs and classes related to agentic patterns in PyAgentSpec

Swarm class#

class pyagentspec.swarm.Swarm(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, first_agent, relationships, handoff=True)#

Bases: AgenticComponent

Defines a Swarm conversational component.

A Swarm is a multi-agent conversational component in which each agent determines the next agent to be executed, based on a list of pre-defined relationships. Agents in Swarm can be any AgenticComponent.

Examples

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.swarm import Swarm
>>> addition_agent = Agent(name="addition_agent", description="Agent that can do additions", llm_config=llm_config, system_prompt="You can do additions.")
>>> multiplication_agent = Agent(name="multiplication_agent", description="Agent that can do multiplication", llm_config=llm_config, system_prompt="You can do multiplication.")
>>> division_agent = Agent(name="division_agent", description="Agent that can do division", llm_config=llm_config, system_prompt="You can do division.")
>>>
>>> swarm = Swarm(
...     name="swarm",
...     first_agent=addition_agent,
...     relationships=[
...         (addition_agent, multiplication_agent),
...         (addition_agent, division_agent),
...         (multiplication_agent, division_agent),
...     ]
... )
Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • first_agent (AgenticComponent) – The first agent that interacts with the human user (before any potential handoff occurs within the Swarm).

  • relationships (List[Tuple[AgenticComponent, AgenticComponent]]) – Determine the list of allowed interactions in the Swarm. Each element in the list is a tuple (caller_agent, recipient_agent) specifying that the caller_agent can query the recipient_agent.

  • handoff (bool) – Controls whether agents in the Swarm can transfer the user conversation between each other. When False: Agents can only communicate with one another, and the first_agent remains the sole agent directly interacting with the user throughout the conversation. When True: Agents can handoff the conversation — transferring the entire message history between the user and one agent to another agent within the Swarm. This allows different agents to take over the user interaction while maintaining context. Agents can still exchange messages with each other as in handoff=False mode.

ManagerWorkers class#

class pyagentspec.managerworkers.ManagerWorkers(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v25_4_2, inputs=None, outputs=None, group_manager, workers)#

Bases: AgenticComponent

Defines a ManagerWorkers conversational component.

A ManagerWorkers is a multi-agent conversational component in which a group manager assigns tasks to the workers. The group manager and workers can be instantiated from any AgenticComponent type.

Examples

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.managerworkers import ManagerWorkers
>>> manager_agent = Agent(
...     name="manager_agent",
...     description="Agent that manages a group of math agents",
...     llm_config=llm_config,
...     system_prompt="You are the manager of a group of math agents"
... )
>>> multiplication_agent = Agent(
...     name="multiplication_agent",
...     description="Agent that can do multiplication",
...     llm_config=llm_config,
...     system_prompt="You can do multiplication."
... )
>>> division_agent = Agent(
...     name="division_agent",
...     description="Agent that can do division",
...     llm_config=llm_config,
...     system_prompt="You can do division."
... )
>>> group = ManagerWorkers(
...     name="managerworkers",
...     group_manager=manager_agent,
...     workers=[multiplication_agent, division_agent],
... )
Parameters:

  • id (str) – A unique identifier for this Component

  • name (str) – Name of this Component

  • description (str | None) – Optional description of this Component

  • metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

  • min_agentspec_version (AgentSpecVersionEnum) –

  • max_agentspec_version (AgentSpecVersionEnum) –

  • inputs (List[Property] | None) – List of inputs accepted by this component

  • outputs (List[Property] | None) – List of outputs exposed by this component

  • group_manager (AgenticComponent) – An agentic component (e.g. Agent) that is used as the group manager, responsible for coordinating and assigning tasks to the workers.

  • workers (List[AgenticComponent]) – List of agentic components that participate in the group. There should be at least one agentic component in the list.

group_manager: AgenticComponent#

An agentic component (e.g. Agent) that is used as the group manager, responsible for coordinating and assigning tasks to the workers.

workers: List[AgenticComponent]#

List of agentic components that participate in the group. There should be at least one agentic component in the list.