Routers

Decide which agent in a pool should act.

A router decides which Agent in the Pool should run next. It examines the shared State or user input and chooses the agent best suited for the next step.

Think of a router as the director of a movie set. Each agent is an actor with a specific role, and the router decides who steps into the scene at the right moment.

In Peargent, you can choose from three routing strategies:

• Round-Robin Router - agents take turns in order

• LLM-Based Routing Agent - an LLM decides which agent acts next

• Custom Function-Based Router - you define the routing logic yourself

With a Custom Function-Based Router, you get complete control over how agents are selected. You can route in a fixed order, choose based on the iteration count, or make smart decisions using the shared state. For example: Sequential routing, Conditional routing, and State-based intelligent routing. Refer Advance Features.

Round Robin Router (default)

The Round Robin Router is the simplest and default routing strategy in Peargent. It cycles through agents in the exact order they are listed, giving each agent one turn before repeating, until the pool reaches the max_iter limit.

This router requires no configuration and no LLM calls, making it predictable, fast, and cost-free.

from peargent import create_pool

pool = create_pool(
    agents=[researcher, analyst, writer],
    # No router required — round robin is automatic
    max_iter=3
)

result = pool.run("Write about Quantum Physics")
# Executes: researcher → analyst → writer

Best for: Simple sequential workflows, demos, testing, and predictable pipelines.

LLM Based Routing Agent

The LLM-Based Routing Agent uses a large language model to intelligently decide which agent should act next. Instead of following a fixed order or manual rules, the router examines the conversation history, agent abilities, and workflow context to choose the most appropriate agent at each step.

This makes it ideal for dynamic, context-aware, and non-linear multi-agent workflows.

from peargent import create_routing_agent, create_pool
from peargent.models import openai

router = create_routing_agent(
    name="SmartRouter",
    model=openai("gpt-5"),
    persona="You intelligently choose the next agent based on the task.",
    agents=["Researcher", "Analyst", "Writer"]
) # chooses an agent or 'STOP' to end the pool

pool = create_pool(
    agents=[researcher, analyst, writer],
    router=router,
    max_iter=5
)

result = pool.run("Research and write about quantum computing")

Custom Function-Based Router

Custom routers give you full control over how agents are selected.
You define a Python function that inspects the shared state, the call_count, and the last_result to decide which agent goes next.

This is ideal for rule-based, deterministic, or cost-efficient workflows.

from peargent import RouterResult

def custom_router(state, call_count, last_result):
    # Your routing logic here
    for agent_name, agent_obj in state.agents.items(): # agent details are available here
        print(f"Agent: {agent_name}")
        print(f"  Description: {agent_obj.description}")
        print(f"  Tools: {list(agent_obj.tools.keys())}")
        print(f"  Model: {agent_obj.model}")
        print(f"  Persona: {agent_obj.persona}")

    # Return the name of the next agent, or None to stop
    return RouterResult("AgentName")

Custom routers unlock entirely new routing patterns, from rule-based flows to dynamic state-aware logic.
To explore more advanced patterns and real-world examples, see Advanced Features.