Orchestration Overview

Orchestration is how a workflow coordinates more than one unit of work: several agents collaborating on a task, a state machine that loops until a quality bar is met, or a deterministic branch that routes each request down a different path. Dynamiq gives you several patterns at different points on the deterministic ↔ autonomous spectrum, and most production issues in multi-agent workflows trace back to picking the wrong one. This page is the decision guide; the sibling pages are the tutorials.

The options at a glance

Start with one agent

Before reaching for an orchestrator, ask whether a single Agent node with the right tools can do the job. The ReAct loop already handles dynamic planning — the agent decides which tool to call next based on what it has learned so far — and you can attach other agents as sub-agents to delegate specialized work without any orchestrator at all (see Sub-agents and delegation).

Move to an orchestrator when you need things a single loop can't give you:

• An explicit process — "draft, then review, then either revise or publish" — that you want enforced rather than hoped for.
• Loops with exit criteria — regenerate until validation passes, with a hard iteration cap.
• Shared state — multiple steps reading and writing a common context object instead of one ever-growing message history.
• Different models per step — a cheap model for routing, a strong one for drafting.

How orchestrators are structured

Every orchestrator node is a small hierarchy you configure in one place:

• The orchestrator itself — takes a single input string and produces a final content string (the Graph Orchestrator also returns its context object).
• An Agent Manager — a dedicated managing agent paired with the orchestrator type: the Graph Agent Orchestrator uses a Graph Agent Manager, the Linear Orchestrator a Linear Agent Manager, and the Adaptive Orchestrator an Adaptive Agent Manager. The manager is the LLM brain the orchestrator consults for planning, routing, and generating agent inputs.
• The manager LLM — the model the Agent Manager runs on. You attach it on the orchestrator's card on the canvas or from the manager's configuration panel.
• The workers — the agents (Linear/Adaptive) or states with tasks (Graph) that do the actual work.

This split matters for cost and reliability tuning: the manager LLM is called frequently for small structured decisions, so a fast model is usually the right choice there, while the worker agents carry the heavyweight reasoning.

Decision guide

Choose a single Agent when the task is one coherent objective, the steps are not known in advance, and tool access is enough. It is the simplest option to build, test, and debug.

Choose the Graph Agent Orchestrator when you can draw the process as boxes and arrows. You define states (each running agents or Python functions), connect them with edges, and add conditional edges where the path depends on results. It is deterministic where you want determinism, and LLM-driven only where you explicitly route with the manager. This is the recommended orchestrator for new builds and the closest analogue to graph frameworks like LangGraph.

Choose Choice + Map when no agent-level coordination is needed at all — you are routing or iterating plain workflow data. They are operators, not agents: a Choice evaluates JSONPath conditions against upstream outputs; a Map runs one configured node per list item. They combine freely with agent nodes and orchestrators on the same canvas.

Keep Linear/Adaptive only in existing workflows. If a legacy workflow misbehaves, the Linear & Adaptive page documents their exact behavior and how to migrate each pattern to the Graph Orchestrator.

Common mistakes to avoid

• Using an orchestrator where an edge would do. If step B always follows step A and neither needs agent coordination, connect two nodes with an edge — orchestrators add manager LLM calls (latency and cost) to transitions.
• Using a Choice node to route between agents that share state. Choice routes workflow data; it cannot carry a conversation or a context object between agents. That is the Graph Orchestrator's job.
• Letting the manager route everything. In the Graph Orchestrator, a multi-way transition without a conditional edge is decided by the manager LLM. Write conditional edges for decisions that have objective criteria, and save manager routing for genuinely judgment-based hops.