How to Build an AI Agent Team: Roles, Handoffs, and Review

Start with one workflow, not a roster of agents

Choose one piece of work that already happens often enough to recognize its stages. A technical content release, a bug fix, a customer-research brief, or a documentation update can work. “Make our product better” cannot: it has no stable outcome, decision boundary, or way to tell when someone is done.

OpenAI’s practical guide to building agents makes the same basic point from a system-design perspective: use an agent where a workflow needs contextual judgment, difficult-to-maintain rules, or work with unstructured information. A deterministic solution may be the better choice when the process is already clear and predictable.

Write the workflow in one sentence before assigning anyone to it:

Turn a requested guide topic into a publicly available, technically verified article without making unsupported product claims.

That sentence gives the team a shared outcome. Then identify the stage changes inside it:

Not every workflow needs five owners. The point is to find places where the input, output, authority, or evidence changes. Those are the natural boundaries for roles and handoffs.

1. Research establishes what is true and what must not be claimed.
2. Writing turns the evidence into a draft for the intended reader.
3. Editorial review accepts, rejects, or changes the claims and framing.
4. Implementation makes the approved page crawlable and tests it.
5. Release verification confirms the public artifact matches the approved work.

OpenAI: a practical guide to building agents

Build the smallest team that can own the workflow

More agents are not automatically more capable. Each additional role creates another routing decision, another context transfer, and another place for responsibility to become vague. Start with a few distinct responsibilities; split a role only after the work repeatedly shows a real boundary.

Here is a practical first team for a multi-stage workflow.

These are roles, not a prescription for five separate models. A human may coordinate and review. One agent may research and draft a small task. An existing agent can connect to Commonly through MCP, a local CLI wrapper, or a custom HTTP integration; Commonly does not run that agent for you.

The role boundary matters more than the label. If two agents can both silently approve a public claim, no one is reliably accountable. If a builder must decide whether a source is trustworthy, but the team said research owns evidence, that is an escalation—not an invitation to guess.

Give every role a compact contract

A role description like “help with research” is too broad to be useful. Instead, give each owner a contract that a teammate can inspect before work begins.

This contract is also a prompt-design aid. OpenAI describes model, tools, and instructions/guardrails as the core parts of an agent. A clear role gives those instructions an operational shape: it tells the agent what outcome it is pursuing, what action is permitted, and when it must stop.

Do not put credentials, private runtime tokens, or sensitive configuration into a shared role brief. Those belong in the access controls and runtime configuration that enforce them. A role contract describes authority; it does not create it.

Make work visible in one shared place

A team cannot coordinate from private sessions alone. The next owner needs a record of what the previous owner found, decided, and checked—not a summary reconstructed from memory.

In Commonly, a pod can hold the complementary parts of that record:

Commonly’s documented task flow is pending → claimed → blocked → done, with an assignee and activity timeline. That does not make the process automatically correct. It gives the team a visible lifecycle so the next person can see whether work is waiting, owned, blocked on a dependency, or genuinely complete.

Use shared memory selectively. MEMORY.md is a good place for stable project context, TASK-NNN.md for task-specific research, and ARCHITECTURE.md for durable design choices. The task board should remain the source of current task state; a memory file should not become a second, stale task tracker.

Design the handoff before the team needs it

An agent team becomes coherent when a handoff has a standard shape. The receiver should be able to answer five questions without rereading every message:

A handoff packet can be short:

This is not a substitute for a pull request, code review, or production controls. It is the coordination record that tells the receiving owner what those systems need to verify. For a deeper distinction between delegating a bounded answer, transferring ownership, and escalating a decision, read AI Agent Handoffs.

1. What outcome is this work trying to produce?
2. What is already true, and where is the evidence?
3. Who owns the next stage?
4. What constraints or decisions must remain true?
5. How will the team know the next stage is complete—or blocked?

Handoff: research → implementation\n\n- Outcome: publish a crawler-readable guide at the approved route.\n- Current state: copy is approved; no static page has been generated yet.\n- Evidence: attached research memo, approved draft, and product-doc links.\n- Constraints: retain the trailing-slash canonical; make no unsupported product claims.\n- New owner: implementation agent.\n- Completion check: initial HTML, title, canonical, sitemap, and a real unknown-route 404 pass.

Put a human at meaningful decision boundaries

Human review does not mean stopping an agent after every small operation. It means naming the moments where a person must decide because the action is consequential, evidence is ambiguous, or the team needs an accountable acceptance decision.

Common examples include:

The human should receive a decision packet, not an unbounded transcript. Include the recommended action, relevant evidence, alternatives or uncertainty, blast radius, and the exact decision requested. This makes review a meaningful handoff rather than a ceremonial checkbox.

Commonly can record the task, thread, and decision around that boundary. It does not replace the systems that enforce authorization, branch protection, secret handling, tool approvals, or deployment gates. Keep those controls where they can actually deny an unsafe action.

For a worked review pattern, see Human-in-the-Loop Review for AI Agent Teams.

• A claim will appear in public marketing or documentation.
• A source conflicts with an existing policy or product record.
• A code change affects authentication, data, money, production infrastructure, or another irreversible surface.
• An agent needs access or authority outside its defined role.
• The task changes from the scope the requester approved.

A worked example: build a small publishing team

Suppose a developer-relations team wants to publish a technical guide. The outcome is not “have agents write content.” It is: publish a useful guide that a builder can verify, a search crawler can read, and an editor can stand behind.

1. The accountable human sets the outcome

The human creates a task with the target reader, the primary question, the product boundary, and the approval point: “Do not publish until the editor accepts every product claim.” They do not need to decide every heading or test command, but they own the decision to make the guide public.

2. A research owner produces evidence, not prose

The research agent or teammate collects first-party product documentation and a small number of reliable category sources. It records supported claims, unknowns, and links. If a source is not clear enough to support a statement, the brief says so.

This produces an input a writer can use. It does not produce permission to make the claim anyway.

3. A writer turns the evidence into a draft

The writer receives the source brief, reader, and route intent. They create an article with a clear answer, an example, internal links to relevant published pages, and explicit boundaries where the product is not the enforcement layer.

The handoff to editorial review names the draft version and asks a specific question: “Are the product claims and recommended workflow accurate enough to implement?”

4. A reviewer makes the editorial decision

The reviewer checks the sources, claims, links, and reader value. They either approve the draft, request bounded changes, or escalate a product question. Approval is a record: it tells the implementation owner what copy is accepted, not merely that a conversation felt positive.

5. An implementation owner makes and verifies the page

The implementation agent adds the static page and its metadata, then runs the checks that belong to the repository and deployment: initial HTML, canonical URL, sitemap coverage, internal links, and unknown-route behavior. It links the pull request and verification result back to the task.

6. The team records the result and learns from it

When the guide is live, the task becomes done only after the public URL and checks are recorded. A durable editorial rule—such as “use only verified product claims”—belongs in shared memory if it will shape future work. The team can then repeat the workflow without pretending every new request is a blank slate.

This example uses several agents, but it can begin with a human, one research-and-writing agent, and one reviewer. Add a separate implementation agent only when that technical handoff is frequent enough to benefit from it.

Starting with a swarm

Assigning many general agents to the same request creates duplicate research, conflicting drafts, and more coordination than the original work needed. Start with one agent or a small, explicitly divided team. Add specialization when the role contract or tool boundary becomes difficult to manage in one place.

Giving multiple owners the same final decision

Two people can collaborate on research. Two agents can propose solutions. But if no one knows who accepts the outcome, both may assume the other person has checked the risky part. Name an accountable owner and an escalation route.

Moving the work but not the evidence

“Research is done” is not a handoff. Attach the memo, link the source, record the current state, and call out uncertainty. The next owner should be able to verify an important statement rather than trust a paraphrase.

Treating a task board as a permission system

A claimed task makes ownership visible; it does not grant the agent credentials or authority to deploy, spend money, modify access controls, or reveal a secret. Keep enforcement in the systems designed for it, and treat missing authority as a blocker or escalation.

Reviewing after the irreversible action

If a human must approve an external message, production change, or public claim, put the review before that action. A retrospective review can improve the next run; it cannot undo an action the team should have paused.

Frequently asked questions