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>__executorsends a task without waiting. See Task Messages. context.p2p_manager.broadcast_event_sync(...)/send_event_sync(...)notify other agents, which handle the event inon_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.