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_2, max_agentspec_version=AgentSpecVersionEnum.v26_1_0, inputs=None, outputs=None, first_agent, relationships, handoff=HandoffMode.OPTIONAL)#

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 | HandoffMode) – Specifies how agents are allowed to delegate work. See HandoffMode for full details. HandoffMode.NEVER: Agents can only use send_message. The first_agent is the only agent that can interact with the user; HandoffMode.OPTIONAL: Agents may either send messages or fully hand off the conversation. This provides the most flexibility and often results in natural delegation; HandoffMode.ALWAYS: Agents cannot send messages to other agents. Any delegation must be performed through handoff_conversation; A key benefit of using Handoff is the reduced response latency: While talking to other agents increases the “distance” between the human user and the current agent, transferring a conversation to another agent keeps this distance unchanged (i.e. the agent interacting with the user is different but the user is still the same). However, transferring the full conversation might increase the token usage.

class pyagentspec.swarm.HandoffMode(value)#

Bases: str, Enum

Controls how agents in a Swarm may delegate work to one another.

This setting determines whether an agent is equipped with:

  • send_message — a tool for asking another agent to perform a sub-task and reply back.

  • handoff_conversation — a tool for transferring the full user–agent conversation to another agent.

Depending on the selected mode, agents have different capabilities for delegation and collaboration.

ALWAYS = 'always'#

Agents receive only the handoff_conversation tool.

Message-passing is disabled:

  • Agents must hand off the user conversation when delegating work.

  • They cannot simply send a message and receive a response.

This mode enforces a strict chain-of-ownership: whenever an agent involves another agent, it must transfer the full dialogue context. The next agent can either respond directly to the user or continue handing off the conversation to another agent.

NEVER = 'never'#

Agent is not equipped with the handoff_conversation tool.

Delegation is limited to message-passing:

  • Agents can use send_message to request a sub-task from another agent.

  • Agents cannot transfer the user conversation to another agent.

As a consequence, the first_agent always remains the primary point of contact with the user.

OPTIONAL = 'optional'#

Agents receive both handoff_conversation and send_message tool.

This gives agents full flexibility:

  • They may pass a message to another agent and wait for a reply.

  • Or they may fully hand off the user conversation to another agent.

Use this mode when you want agents to intelligently choose the most natural delegation strategy.

ManagerWorkers class#

class pyagentspec.managerworkers.ManagerWorkers(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_2, max_agentspec_version=AgentSpecVersionEnum.v26_1_0, 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.