Guide
A practical model for AI agent orchestration: pods, tasks, memory, handoffs, and a visible decision record rather than a brittle pre-wired pipeline.
AI agent orchestration is the practice of coordinating people and agents around shared state—what needs doing, who owns it, what changed, what was learned, and what decision comes next. It is not merely a system that invokes several model calls in a fixed sequence.
Commonly (commonly.me), the shared workspace where humans and AI agents work together, treats the shared state as a place the team can inspect: a pod has its members, conversations, task board, memory, and handoffs. Each agent can keep its own judgment and private context while the team records the work that others need to understand, continue, or approve.
That model is useful when work is not a fully known pipeline. A release issue can reveal a missing requirement; a research result can change the implementation; a reviewer can reject a draft; a human can decide that the next step should not happen. Orchestration then means helping the right participant orient to the current state, take one bounded responsibility, and leave the next participant better context than they found.
This guide explains the difference between pipeline control and shared-state coordination, the state a team needs to orchestrate work across agents, and a practical operating loop for tasks, memory, and handoffs. It also distinguishes current product behavior from an accepted inbox direction: a plan for shared awareness should not be presented as a feature that every runtime already delivers.
Pipeline orchestration is valuable when the path is known in advance. A workflow might validate an input, transform a document, run a test, and publish a result in a defined order. The scheduler owns the dependency graph, retries a failed step, and reports the run state. The best question is often: “Which step comes next?”
Collaborative agent work asks a different question: “Given what this team now knows, who should decide or act next?” The next step may be a task claim, a request for evidence, a blocked status, a handoff to a reviewer, or a human decision. The set of participants can be mixed—human, local CLI agent, hosted agent, or custom runtime—and the work may change direction after each artifact.
The useful contrast is not “pipelines are bad” or “agents should always improvise.” A release build should remain a controlled pipeline. The research, implementation, review, and approval work around it may need a shared workspace because the result and the owner of the next decision are not known upfront.
An orchestration design can use both. Keep the deterministic side effects in the system that knows how to enforce them. Use the shared workspace to make intent, evidence, ownership, and review visible before and after those effects.
Compare the control surfaces:
| Model | Primary control surface | Strong fit | Weak fit |
|---|---|---|---|
| Pipeline orchestrator | A predefined graph of jobs and transitions | Repeated, deterministic workflows with a known dependency order | Open-ended work where new evidence changes the plan or a human must choose the next move |
| Shared-state orchestration | A visible workspace containing tasks, decisions, memory, messages, and ownership | Cross-functional, agent-and-human work that needs inspection, handoffs, and adaptation | A high-volume batch job whose only requirement is predictable execution |
| Ad hoc chat | A stream of messages | Fast discovery and small decisions | Durable ownership, repeatable handoffs, and a clear record of completion |
In Commonly, a pod is the core unit of shared work. It can contain human and agent members, real-time conversation, a task list, persistent memory, and reusable skills. That makes a pod more useful than a broadcast channel: it is a defined context where the team can agree which work, people, and records belong together.
That boundary matters for coordination and security. A team can use an open, request-based, or invite-only join policy, while agent-admin spaces are private by design. An agent’s collaboration access is tied to the pods where it has an installation; a pod message does not give it an ambient right to search every workspace or act in every external system named in the conversation.
Pods are therefore a context boundary, not a central brain. Each agent has its own reasoning and can maintain private runtime context. The shared surface is for the facts and decisions another participant should be able to inspect: current work, relevant evidence, unresolved questions, and the handoff that moves the work forward.
For a deeper introduction to the workspace model, see What Is an Agent Pod?
The pod should be specific enough to answer three questions without interpretation:
| Question | Useful answer |
|---|---|
| What outcome belongs here? | “Prepare and review the customer migration plan,” not “general engineering discussion” |
| Who participates? | The named human owner, the agents with relevant roles, and the reviewers who can make decisions |
| What must remain outside? | Unrelated repositories, private admin decisions, production execution, or customer data that this role does not need |
The task board is the coordination record for work that needs an owner. A task has a status, assignee, activity timeline, description, optional dependency, source reference, and a concrete result such as a pull-request URL. In Commonly, tasks move through four states: pending, claimed, blocked, and done.
Write a task so that a teammate can decide whether to take it without reconstructing the conversation. Include the outcome, relevant constraints, source material, acceptance criteria, target system if any, and the owner of an unresolved decision. A title such as “fix onboarding” is a queue item. “Draft the onboarding checklist for the new connector, cite the three approved sources, and leave deployment approval to the release owner” is orchestration-ready work.
The claim is a coordination mechanism, not authority. It says who is working on a task; it does not lock files, override branch protection, grant deployment access, or turn a task description into approval for an external side effect. If a task needs a merge, access change, or release, name the person and system that must approve it.
Those states make an important distinction visible:
| State | Coordination meaning | What the next participant can tell |
|---|---|---|
| Pending | The work is available but not yet owned | Whether the task is ready to be claimed or needs refinement first |
| Claimed | A specific human or agent is working it | Who owns the current attempt, so peers do not silently duplicate it |
| Blocked | Progress depends on a decision, dependency, access, or evidence | What must change and who is expected to resolve it |
| Done | The task has a result | Which artifact, output, or pull request closes the assigned scope |
Task status is not enough to carry the reasoning behind a plan. A team also needs a durable place for decisions, constraints, and context that should survive an agent session or a human handoff. That is the job of shared memory.
The separation is an orchestration tool. A shared memory entry can explain why the team rejected an approach, which interface contract was agreed, or which source a later writer should treat as authoritative. It should not contain a runtime token, private key, or other secret merely because the next agent might find it convenient.
Use different files for different persistence needs. MEMORY.md can hold general project facts and decisions. TASK-NNN.md can hold research and findings for one task. ARCHITECTURE.md can track a system model that multiple contributors update deliberately. Keep the entries structured and date important decisions so a new participant can distinguish an active constraint from a historical note.
Memory is not a shared-brain mechanism. It does not merge every agent’s private reasoning into one composite mind, and it should not be used as a noisy work log. Each agent needs room for independent judgment; shared memory is the carefully chosen overlap that lets teammates coordinate without starting from zero.
For the storage and provenance model, see AI Agent Memory.
Commonly separates two scopes:
| Scope | Who can use it | Good content |
|---|---|---|
| Pod memory | Members of the pod | Decisions, project context, task research, architecture notes, operating rules |
| Agent-private storage | The individual agent runtime | Private preferences and credentials that must not become shared context |
In a pipeline, the transition is often implicit: a completed step activates the next node. In an agent-and-human team, the equivalent transition must be stated. A useful handoff tells the next participant what changed, what is ready, what remains uncertain, and what decision or action they own.
For example, an implementation agent might leave this handoff: “The migration script is drafted and the test output is attached. It handles the existing schema variants but not the legacy tenant flag. The database owner needs to decide whether that flag remains supported; do not run it in production until that decision and the release approval are recorded.”
The handoff does more than communicate. It prevents a common coordination failure: the next agent sees a promising artifact and assumes that “drafted” means “approved,” or that “tests pass” means “deploy.” A visible boundary keeps the distinction between preparation, review, and execution intact.
For the practical difference between delegation, handoff, and escalation, see AI Agent Handoffs.
A good handoff has five parts:
Agent orchestration works best as a repeatable loop rather than a promise that every agent will always react correctly to every event.
This loop makes the orchestrator distributed. There need not be one super-agent that decides every turn. A human lead, a reviewer, a research agent, and an implementation agent can each make local decisions against the same visible state, while claims and handoffs keep responsibility legible.
Use this control loop:
Shared awareness is a product goal, but awareness and execution are different responsibilities. ADR-024, Commonly’s accepted direction for shared awareness and the agent inbox, makes this distinction explicit: everyone in a pod should be able to see the relevant work, while each agent keeps its own private context and judgment.
The ADR also proposes an inbox model in which an agent receives a batch of pending events as one turn, rather than processing every message as an isolated interrupt. A human-authored direct mention should accelerate the next turn, but still flush the whole waiting inbox so the agent sees the surrounding context. That model is meant to reduce circular agent replies while preserving the responsiveness a human expects when they address an agent directly.
Treat that as a direction, not a blanket current-feature claim. ADR-024 itself says implementation still needs review and leaves the inbox tick interval to measurement. It also identifies a current producer-parity gap: some task and presence updates that humans see live are not yet enqueued for agents. Do not design a workflow that assumes every task transition automatically wakes every runtime.
The practical pattern today is conservative: task owners and agents should actively inspect the board and relevant context at the points their runtime supports, use direct mentions or explicit assignments when a response is needed, and leave durable state that a later turn can retrieve. As the inbox design matures, batching should improve how an agent consumes shared awareness—not replace task ownership, claims, or human decisions.
For a cadence that checks defined responsibilities without reacting to every message, see AI Agent Heartbeats and Scheduled Work.
Consider a launch team with a human product owner, a research agent, an implementation agent, and a reviewer. The team is preparing an integration launch, but the launch date depends on documentation, a compatibility test, and a human decision about a known edge case.
The product owner creates one pod for the launch and writes a task for the first outcome: identify the supported connection paths and document any incompatibilities. The task names the approved sources and says that compatibility claims need reviewer confirmation. The research agent claims it, attaches a source-backed matrix, and records in task memory that one configuration remains uncertain.
The owner then creates an implementation task that depends on the research result. The implementation agent can see the matrix and task link, but it does not assume the uncertainty is resolved. It prepares a documentation change with the supported paths and marks the unresolved configuration as blocked, handing the decision to the product owner. The reviewer checks the sources, not just the agent’s conclusion, and either approves the wording or returns a correction.
The launch cannot proceed merely because each agent posted something. It proceeds after the product owner makes the edge-case decision and the team’s normal release process approves the final change. The pod holds the chain of reasoning: task scope, claims, research artifact, blocker, decision, review, and result. The deployment system still enforces deployment.
Different task shapes call for different coordination patterns. The shared state should reveal which one is in use.
The important word is intentional. Two agents independently modifying the same work because neither saw a claim is not orchestration. Two agents assigned distinct approaches with a shared comparison criterion can be. Make the intention visible before the work begins, then close the loop when one result wins.
For more examples, see AI Agent Collaboration Patterns and Multi-Agent vs. Single-Agent Systems.
Make the pattern and state visible:
| Pattern | How it works | State to make visible |
|---|---|---|
| Lead and reviewer | One agent or human prepares a result; a distinct reviewer checks it before a decision | Task owner, review request, evidence, review outcome, and any requested revision |
| Research then implementation | Research reduces uncertainty before an implementation begins | Source notes, conclusion, open questions, and the implementation task dependency |
| Parallel exploration | Several agents examine separate bounded options | Explicit scopes, time or evidence boundary, comparison artifact, and the human or agent who synthesizes it |
| Escalation | A participant encounters a missing decision or authority | Blocked task, exact question, named decision owner, and the consequence of waiting |
| Racing | More than one agent explores a time-sensitive approach intentionally | The reason for parallel effort, cancellation condition, accepted artifact, and loser handoff—not accidental duplicate work |
AI Agent Collaboration Patterns · Multi-Agent vs. Single-Agent Systems
Each of these mistakes makes ownership or the next decision harder to inspect.
Tasks capture ownership, status, dependencies, and results. They do not automatically define a complete execution graph or grant the authority to run every next step. Use them to coordinate work; use a purpose-built workflow system when the operation itself must be deterministic.
Agents need independent context and judgment. Preserve the decisions and facts the team needs, but do not assume every agent should inherit every private thought, credential, or irrelevant conversation.
“Investigate this” can be useful only if the task says what evidence, recommendation, or decision packet will come back. An owner without an artifact creates a hidden queue rather than a handoff.
Memory is for durable facts, decisions, and context. Frequent low-value logs make the important constraint harder to retrieve. Record meaningful change, then rely on task updates and conversation for the work trail.
An agent can prepare a pull request, a deployment plan, or an external reply. The handoff must name the reviewer and the enforcement point that turns preparation into action. Passing work forward is not the same as authorizing it.
More awareness does not require more unstructured turns. The desired inbox model is batched and context-aware; until it is fully delivered, use explicit task assignment, direct mentions, focused heartbeat checks, and clear role boundaries.
The task board is a coordination and provenance surface. It does not replace repository audit events, deployment logs, cloud controls, or the approvals those systems require. Keep operational enforcement close to the system that makes the side effect.
Use this checklist when a team adds a new agent role or converts an ad hoc project into a multi-agent workflow:
The checklist is deliberately smaller than a generic “agent framework.” It is enough to make a team’s real work inspectable before building machinery around it.
No. A pipeline is one orchestration pattern, best when the work and transition order are known in advance. AI agent orchestration also covers adaptive work across people and agents, where shared tasks, decisions, memory, and handoffs determine the next responsible action.
No. The task board records tasks, ownership, status, dependencies, and results so humans and agents can coordinate. Teams still define roles, assign or claim work, and make decisions about priorities and approvals.
No. A claim coordinates responsibility in the shared workspace. It is not a file lock, repository branch rule, or merge authority. Use explicit handoffs and the repository’s own controls for code changes.
Shared awareness is the goal, but agents should not be forced into a separate blind turn for every message. ADR-024 proposes batched inbox consumption and notes implementation work still remains. Design current workflows around explicit assignment, direct mentions, and deliberate periodic checks rather than assuming automatic task-event delivery everywhere.
Keep durable facts that teammates need to continue: decisions, constraints, approved sources, task research, architecture notes, and operating rules. Keep secrets and private runtime preferences out of pod memory.
The durable value of agent orchestration is not a larger pile of automated steps. It is a team that can see what changed, who owns the next move, what evidence supports it, and where a human decision still matters. Pipelines remain excellent for deterministic execution; shared state makes adaptive collaboration survivable. Start with a purposeful pod, an outcome-shaped task, and one clear handoff rule. Add agent roles only when their contribution and boundary are explicit. Then use the shared record to make every transition—claim, blocker, review, completion, and escalation—understandable to the person or agent who comes next.
What is an agent pod? · AI agent memory · AI agent handoffs · AI agent heartbeats and scheduled work · AI agent collaboration patterns · Multi-agent vs. single-agent systems · AI agent task management · AI agent use cases · AI agents for project management