Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

AI Agent Orchestration patterns

How several AI agents divide one job: sequential, concurrent, maker-checker, handoff, group chat and planner-led shapes, what passes between the agents, what ends the run, and what each extra hop costs.

One agent or four

A team is moving a monorepo of 1,200 Java modules from JUnit 4 to JUnit 5. One design gives a single agent three tools (edit a file, compile, run the module's tests) and lets it loop until the module is green. The other splits the work among four agents, a planner, a migrator, a test fixer and a reviewer, each passing its result to the next. On a trial of 50 modules, the four-agent version spent about three times the tokens, took twice as long per module, and finished about as many.

AI Agent Orchestration patterns describe how several agents divide one job: in a fixed sequence, in parallel, through maker-checker review, by handoff, in a moderated group chat, or under a planner that adapts as it goes. These nodes describe workflow shape; the concrete agents and tools still carry the detailed responsibilities. Every extra agent is another context to fill, another place to stall and another hop where information can get lost, so the question is what the least coordination is that does the job. Running the single agent over all 1,200 modules side by side does not count: those runs never talk to each other, so a queue and a pool of workers can carry them, Queue-Based Load Leveling, with the workers' call rate capped under the provider's rate limit.

Use these as pattern-level markers; connect the participating agents or services for concrete flow.

Stages in a fixed order

On large modules the single prompt was too much: change the imports, turn @Before into @BeforeEach, replace @RunWith runners, move each assertion's message argument from first position to last, update the build file. On long files the agent skipped steps. Sequential orchestration splits the job into stages that always run in the same order, each an agent with a narrow prompt: the build file, then annotations and imports, then assertions. Each stage passes on the working diff and the latest compiler output, not its whole conversation.

The run ends after the last stage, or earlier when a stage's check on its own change fails; the full compile and test run comes after the assertions stage, since until then the old assertion calls may not compile against the new imports. The shape is easy to trace and to cost, one hop per stage, but each stage sees only its own job: an early mistake travels downstream, and no stage can ask an earlier one to redo its part.

A second model reads the diff

Then a module went green with a test that no longer checked anything: a failing test had been made to pass by deleting its assertion. The compiler and the tests were satisfied, because the change was made to satisfy them.

In a maker-checker loop, one agent produces the change and another reviews it against a rubric: no assertion removed, no test disabled, each rewritten assertion checking what the old one did. A rejection goes back to the maker with the reasons, and the loop ends when the checker approves or after three rounds, when the module leaves the run as unfinished.

The checker is still a model, so it earns its place on what code cannot judge, such as whether a rewritten assertion tests the same thing, while rules that must hold, and a person approving an action, belong to Agent guardrails: checking tool calls & human approval.

Three questions at once

Before touching a shared test-support module used by 300 others, the team wants to know what migrating it will break. Three questions are independent: which JUnit 4 rules it exports, which modules use each, and what went wrong in the modules already migrated. Concurrent orchestration gives each question to its own agent, runs them at the same time, and merges the answers into one plan.

The wait is the slowest agent's plus the merge, but the tokens are the sum, and the merge is real work: when two answers disagree, the aggregator, a model or code, has to decide, or the contradiction reaches whoever reads the plan. The shape fits only when no agent needs another's output; if the third question depended on the first, it would be a sequence again. Collecting parallel answers is the same problem Scatter-Gather describes for services.

Modules nobody planned for

About one module in twenty used a custom JUnit 4 runner. JUnit 5 replaces runners with extensions, and writing one, or keeping the module on the Vintage engine that runs JUnit 4 tests on the new platform, is a different job from rewriting annotations. In handoff orchestration, the agent that meets such a module passes the task, and control, to a specialist with its own prompt and tools, which owns the module from then on. One agent works at a time, and the route is decided during the run by whichever agent holds the task.

The risk is a task that bounces: the specialist sends the module back because it also has ordinary tests, and the migrator hands it over again. A handoff limit per task, after which it goes to a person, stops that. Each handoff must also carry what the next agent needs (the module, the runner's source, what was tried), because the specialist sees only what the handoff passes to it.

When nobody knows the steps yet

The last 40 modules ran their tests through the test support of a Spring version older than 5.0, which predates JUnit 5, so their tests could move only after a Spring upgrade, with breakages nobody could list in advance. Two shapes are made for that, and they are usually the most expensive.

Group chat orchestration puts several agents in one shared conversation, here a build agent, a test agent and a reviewer, with a manager that picks who speaks next and ends the chat when they agree or after a turn limit. It suits deliberation, such as choosing the order of upgrades, and every turn adds to a thread every participant reads again, so the cost climbs with each round. Magentic orchestration, named after Microsoft's Magentic-One system, gives a manager agent the goal and lets it write a plan, assign steps to specialists, check progress and rewrite the plan when progress stalls. It handles tasks whose steps appear along the way, and it is the hardest shape to predict, audit and bound: without a budget and a stall limit, it can keep re-planning. The other 1,160 modules needed neither: a sequence, a checker and a handoff are easier to reason about, and a manager there would have added cost, latency and governance work for nothing.

What every shape has to answer

What 1,160 modules needed

Each module goes through three fixed stages; the checker returns a rejected diff, three rounds at most, and a custom runner goes to a specialist. Progress is saved per approved module.

Whatever the shape, three questions decide whether it holds up:

  • What passes between agents. A compact, structured handover (the diff, the error, what was tried) costs fewer tokens than a whole transcript and leaves less to misread, but what it leaves out is gone for the next agent.
  • What ends the run. The last stage, every branch returned, the checker's approval or round limit, the handoff limit, the turn limit, the budget. A shape with no stated end runs until something outside it, a timeout or the bill, stops it.
  • Where the run's state lives. A migration of 1,200 modules runs for hours and will meet a deploy or a crash; resuming from the last finished step is Durable workflows: orchestration that survives restarts.

Every agent's model calls travel the same path as any other, with rate limits and token budgets per tenant: Serving LLMs: gateways, fallback & token budgets. Handoffs are first-class in the OpenAI Agents SDK; an A2A Server lets other agents delegate tasks to one across process boundaries; AutoGen ships a group-chat team (and Magentic-One for planner-led flows); a tool step is often a Web Search Tool or Browser Automation behind an MCP Server. Each framework runs inside a service: on a Grid it names the box, it does not replace the deploy boundary.

Your call on the AI Agent Platform Grid

The AI Agent Platform Challenge asks for an agent that plans steps and calls tools until a long task is done, with tools behind an MCP server, approval before high-risk actions, and run state that survives restarts. Give it the migration and, before placing a second AI Agent node, answer on the Grid: which step does one agent with tools get wrong often enough to pay for another hop, a maker-checker pair with its round limit on the edge, or a specialist behind the A2A Server? If you cannot name the step, the right number of agents is one.

Practice this