Skip to content

Agentic Patterns

Agentic patterns are reusable ways of organising one or more agents to solve a problem: splitting work into sub-tasks, routing work to the right agent, delegating, having agents debate, judge or vote, and letting them discuss their way to a shared answer. This chapter maps each pattern to the building blocks that implement it on AgentGr.id, then covers the two basic interaction styles, synchronous and asynchronous, that every multi-agent pattern is built from.

Pattern Overview

Pattern What it does Building blocks
Fan-out / sub-tasks Split one task into several parts, processed independently on_preprocess returning several AgentTasks; Task Delegation to other agents
Routing Send each task to the agent best suited to it Dynamic Workflows (router agent), SelectionEngine over the Association Registry
Delegation Hand a sub-task to another agent and collect the result context.delegator, context.direct, Task Delegation
Pipeline A fixed sequence of specialist agents Static Workflows
Planner–executor An LLM plans the steps, then the steps run AgentWorkflowEngine, Behavior Controller
Judging / verification One agent, or a person, checks another's output Verification System, Human-in-the-Loop
Voting Several agents decide together Social Choice & Voting
Debate / discussion Agents exchange arguments over several rounds before deciding P2P events and request/reply on a shared mesh, ending in a vote or a judge
Market recruitment Find an agent you don't already know for a job Task Exchange & Bidding
Sub-agent spawning Create dedicated agents on demand, then remove them context.spawner
Self-refinement Iterate until the output meets an expectation self_refine
Skill use Load the right know-how or procedure for the task Agentic Skills

Synchronous Patterns

In a synchronous interaction the calling agent waits for the other agent's result before it continues. Use it when the next step needs the answer.

Delegate API: context.delegator.submit_and_wait

def on_data(self, task):
    reply = self.context.delegator.submit_and_wait(
        subject_id="legal-reviewer",
        session_id=str(uuid.uuid4()),
        task_id=task.task_id,
        task_data={"text": task.job_data["contract"]},
    )
    return AgentResult(task_id=task.task_id, job_output={"review": reply})

The call goes through the Delegate API (AGENT_DELEGATE_URL) to the target agent's executor, so the target's admission and load-balancing policies apply. It raises AgentDelegatorError if the call fails.

P2P Request/Reply: send_and_wait_sync

reply = self.context.p2p_manager.send_and_wait_sync(
    task.task_id, subject_id="translator", task_data={"text": text, "lang": "fr"})

Agents on the same NATS mesh can call each other without the Delegate API. See Chat and P2P Communication.

Trade-offs: synchronous calls are simple and keep the logic in one place, but the caller holds a worker while it waits, and a slow callee slows the caller.


Asynchronous Patterns

In an asynchronous interaction the calling agent does not wait: it hands the work on, and the result goes somewhere else. Use it for long tasks, for fan-out, and for chains where the final result should go straight to the original requester.

Direct Hand-off: context.direct.submit

def on_data(self, task):
    # pass the task on; the next agent replies straight to whoever sent the original task
    self.context.direct.submit(
        to="report-writer",
        session_id=str(uuid.uuid4()),
        task=task,
        job_data={"findings": self.analyse(task.job_data)},
    )
    return AgentResult(task_id=task.task_id, job_output={"status": "handed_off"})

direct.submit looks up the target's executor in the runtime subjects service and posts the task with the current task's output_ptr, so the target's result is routed to the original requester.

Fire-and-Forget and Events

  • P2P publish to <subject_id>__executor sends a task without waiting. See Task Messages.
  • context.p2p_manager.broadcast_event_sync(...) / send_event_sync(...) notify other agents, which handle the event in on_event. See Agents Streaming.
  • Results of queued tasks can be pushed to any Redis list through output_ptr. See Output Routing.

Trade-offs: asynchronous patterns scale better and tolerate slow agents, but the flow is spread across agents. Correlate with task_id or session_id, and add verification or time-outs where results must not be lost (see Persistence & Recovery).


Choosing a Pattern

Situation Pattern
The next step needs the answer now Synchronous delegation
The work is long, or the result belongs to someone else Direct hand-off (asynchronous)
Many independent parts Fan-out with asynchronous delegation, then aggregate
The order is fixed Static workflow
The next step depends on results Dynamic workflow with a router agent
Quality matters more than speed Add a judge (verification) or a vote
You don't know which agent can do it Discovery through the Association Registry, or the task exchange

Sub-Agents

An agent can get help in three ways:

Source When How
Existing agents A suitable agent is already running Discover it with the Association Registry, then delegate
The market You need a specialist you don't know Post the job to a task exchange
Its own sub-agents The work needs a dedicated agent: a different persona, model, tools or resources, isolation, or extra parallel capacity Spawn one with context.spawner (below)

Spawning Sub-Agents

context.spawner creates a new agent from agent code. It registers a subject, deploys it through a deployer, and returns once the agent is running:

import uuid

def on_data(self, task):
    sub = self.context.spawner.spawn(
        name="clause-reviewer",
        image="registry.example.org/agents/reviewer:latest",
        persona={"role": "Clause reviewer", "goal": "Review one contract clause for risk"},
        description="Reviews a single clause",
        tags=["legal"],
        instances=3,                                   # parallel capacity for fan-out
    )
    try:
        reviews = [
            self.context.delegator.submit_and_wait(
                subject_id=sub.subject_id, session_id=str(uuid.uuid4()),
                task_id=f"{task.task_id}-{i}", task_data={"clause": clause})
            for i, clause in enumerate(task.job_data["clauses"])
        ]
    finally:
        self.context.spawner.remove(sub)               # stops workloads and deletes the subject
    return AgentResult(task_id=task.task_id, job_output={"reviews": reviews})

To create a copy of the current agent (same image) with different settings, use spawn_clone. Any specification section can be overridden, and nested fields are merged:

sub = self.context.spawner.spawn_clone(
    name="planner-junior",
    persona={"goal": "Only plan the data-collection phase"},
    runtime={"resources": {"memory_mb": 4096}},
)
spawn(...) argument Default Description
name, image — Agent name and container image (required)
persona, description, tags, integrations, resources empty / 1 CPU, 2 GiB Specification sections of the new agent. "spawned" is always added to the tags
instances 1 Number of instances
deployer_id SPAWN_DEPLOYER_ID Deployer, and therefore cluster, to run on
meshes Parent's MESH_LIST NATS meshes the sub-agent joins
subject_id <name>-<random> Explicit subject ID
spec_overrides — Any other specification fields, deep-merged
wait_timeout 120 s How long to wait for the runtime subject

spawn returns a SpawnedAgent with subject_id, deployer_id, executor_url, runtime and parent_subject_id. list_spawned() lists the sub-agents created by this instance, and remove_all() removes them, for example on shutdown. If deployment fails, the subject that was just created is deleted again, and SpawnError is raised.

Variable Description
SPAWN_DEPLOYER_ID Default deployer for sub-agents. Set it in the parent's runtime.resources.env
SUBJECT_DB_URL, AGENT_DELEGATE_URL, MESH_LIST Already set on every instance; reused for the sub-agent

Sub-agents are ordinary agents: they get their own executor, admission policies, scaling and observability, and can spawn sub-agents of their own.