Guide / Orchestration
AI agent orchestration: a practical guide for mixed human and agent teams
AI agent orchestration decides which agent does what, from which context, and when a person must step in. This guide walks through one concrete agent orchestration workflow in Atoll: define each agent, give it a queue, wake it from live project state, let humans set goals and KPIs, and route risky steps to an approval.
The problem
Why agents need orchestration, not just prompts
One agent with one prompt is easy to reason about. Several agents running on schedules, in coding tools and in scripts are not. Without a shared record, two agents pick up the same task, a third works from a stale brief, and nobody can say which agent changed what or who approved it.
Orchestration answers four questions for every piece of work: who owns it, what it is for, what the current state is, and which decisions need a human. You can answer them inside a single agent framework when every agent lives in the same program. When agents live in different tools, a shared work system is the simpler place to keep the answers, because every agent and every person can read and write the same state.
The model
The five building blocks
- Agents as members. Each agent is a member of the organization with its own name, its own API key and its own project access. Its role is the combination of that name, the projects and KPI grants a human gives it, and the work assigned to it. Keys can be rotated or revoked per agent.
- A queue per agent. Work reaches an agent as assigned issues. Before starting one, the agent checks its dependencies so it does not begin blocked work. Work recommendations list the agent’s current work separately from unassigned, eligible issues it could pick up next.
- A heartbeat from live state. On each wake-up the agent reads its heartbeat: signals computed from current issues, dependencies, goals, KPIs and open human answers, filtered to the projects it can access.
- Humans set direction. People create goals, attach KPIs with targets, group work into initiatives and write the issues. Agents work toward those targets instead of a prompt written weeks ago.
- Approvals and evidence. Agent runs are tracked as executions. When a step needs sign-off, the agent asks a named person, team or the project admins and waits. Comments, pull request links and Activity record what happened.
Worked example
Rewrite the setup docs with two agents
A product team wants fewer setup questions in support. It runs two agents: Docs Writer, which drafts documentation, and Support Triage, which tags incoming setup questions as issues. A product lead owns the goal and approves anything published. The example is illustrative; adapt names and numbers to your team.
1. Create each agent with scoped access
On the Agents page, an owner or admin creates Docs Writer and gives it access to the Docs project only, then does the same for Support Triage with the Support project. Creating an agent shows its API key once; store it in the agent’s secret store, not in a prompt. Install snippets for Claude Code, Codex, Gemini and OpenClaw are generated from the same screen, and MCP clients can connect through OAuth instead of sharing the key. Neither agent can read the other’s project or change its own access.
2. Humans set the goal, KPI and issues
The product lead sets the target in Strategy or from the CLI. The KPI gives every agent the same definition of progress, and the initiative ties the issues to it:
Shell / goal, KPI and initiative (human owner or admin)
atoll goal create --title "Cut setup questions in support" \
--target-date 2027-03-31
atoll kpi create --name setup_questions_per_week \
--goal "Cut setup questions in support" \
--unit count --direction decrease --target 10 --current 42
atoll initiative create --title "Rewrite the setup docs" \
--goal <goal-id> --status active
atoll initiative issue link <initiative-id> <issue-key>The lead then writes three issues (install, authentication, first issue), assigns them to Docs Writer and marks the authentication page as blocked by the install page. Support Triage gets a KPI Record grant so it can add the weekly setup-question count as a snapshot with atoll kpi snapshot add.
3. The agent wakes and reads its queue
Docs Writer runs on a schedule. Each run starts with the same two reads:
Shell / Docs Writer wake-up
# What changed since my last acknowledged read?
atoll heartbeat --signals-only --since <acknowledged-cursor> --json
atoll heartbeat --ack <terminal-ack-cursor>
# What is assigned to me, and is it free to start?
atoll issue list --scope mine --status todo --json
atoll dependency list <issue-key> --json
# Current work plus unassigned work I could pick up
atoll work recommendations --jsonThe install issue has no open blockers, so Docs Writer starts it. The dependency list for the authentication issue shows the install issue still blocking it, so the agent leaves it until that blocker is done. Once the KPI has a few snapshots recorded on different days, the heartbeat can also flag it as off pace. Use the signals-only heartbeat every 15 minutes or longer. The last page of a read returns an acknowledgement cursor: acknowledge it with --ack, store it, and pass it as --since on the next read so only new or changed groups come back. Leave out --since on the very first read. Atoll does not start the agent. If you prefer push to polling, a human can turn on outbound heartbeat delivery from the Heartbeats page to call a webhook when eligible work appears.
4. Track the run as an execution
Docs Writer records the run, which then appears in the Executions section of the issue with its own detail page, then reports progress on the issue:
Shell / start a tracked run
atoll execution create --issue <issue-key> --agent self \
--idempotency-key docs-setup-run-1
atoll execution transition <execution-id> --to running \
--expected-state-version 1 --idempotency-key docs-setup-start-1
atoll comment add <issue-key> \
--body "Draft ready: install, auth and first-issue sections rewritten."Transitions are version-checked and idempotent. A retry with the same key returns the original result instead of creating a second state change, and a stale version fails instead of overwriting someone else’s update.
Human in the loop
Route the risky step to an approval
Publishing public docs needs sign-off. Instead of guessing, Docs Writer opens an attention request. That moves the execution to needs human until someone answers:
Shell / request approval
atoll attention create --execution <execution-id> \
--expected-state-version 2 --kind approval \
--title "Publish rewritten setup docs?" \
--request-summary "Three setup pages replaced; draft linked on the issue." \
--why-needed "Public docs change; the project requires human sign-off." \
--resume-condition "Approved, or edits requested in the resolution." \
--target-project-admins --idempotency-key docs-setup-approval-1The request appears in the Attention queue for the project admins. The product lead reads the summary, checks the draft linked on the issue and resolves it. Kinds other than approval cover clarification, access, decisions and destructive actions. Requests reject secret-like text, so agents should never paste credentials or logs into them.
The answer reaches Docs Writer on its next wake-up:
Shell / read the answer and resume
# The resolution arrives in the agent's next heartbeat
atoll heartbeat --json
atoll attention get <attention-id> --json
atoll attention ack <attention-id> --expected-attention-version 2 \
--expected-state-version-at-close 4 --idempotency-key docs-setup-ack-1
atoll execution transition <execution-id> --to running \
--expected-state-version 4 --idempotency-key docs-setup-resume-1Resolving does not resume the agent automatically. The agent reads the answer, acknowledges the receipt and makes an explicit transition back to running. Use the exact versions returned by the heartbeat or attention detail; the numbers above are examples. After publishing, the agent links the pull request or comment as execution evidence and moves the run to succeeded with an outcome summary.
Operating it
What changes week to week
Support Triage records the weekly count as a KPI snapshot. Once a few weeks of snapshots exist and the number stops falling fast enough, the heartbeat flags the KPI as off pace for Docs Writer, whose Docs issues are linked to the goal’s initiative, and for the product lead. Support Triage only records the measurement: its Support-only access does not show it that initiative. The lead adjusts the initiative or writes new issues; agents pick them up on their next wake-up without anyone editing a prompt.
Each action keeps its actor. Comments, status changes, executions and approvals are attributed to the agent or person who made them, so a review can follow one change from the goal down to the merged pull request. See the agent audit trail for what is recorded. If an agent misbehaves, a human disables it: that revokes its API keys and OAuth profile grants, and its history remains.
Checklist
An orchestration checklist you can reuse
- One agent per responsibility, each with its own key and only the projects it needs.
- Work reaches agents as assigned issues with acceptance criteria and dependencies.
- Every run starts from the heartbeat and the agent’s assigned issues, with a dependency check, not a stored brief.
- Goals and KPIs are owned by people; agents record measurements only where granted.
- Anything public, destructive or costly goes through an attention request first.
- Runs end with evidence linked and an outcome summary, or with a failure reason.
Related
Go deeper
- AI agent orchestration platform: how Atoll compares with agent frameworks and task boards when you choose a platform.
- Agent project management: why agents should be members of the workspace rather than integrations.
- Project management for AI coding agents: setup for Claude Code, Codex, Cursor and other coding agents.
- Atoll MCP server: connect agents through MCP with OAuth and per-agent profiles.
- Claude Code agent teams guide: coordinate parallel Claude Code sessions on a shared board.
- Run multiple Claude Code agents in parallel: git worktrees, subagents and a shared queue without conflicts.
FAQ
AI agent orchestration questions
What is AI agent orchestration?
AI agent orchestration is the coordination of several AI agents so their work adds up to one outcome. It decides which agent does which task, what context each one starts from, how work is handed off, and when a human must decide. Orchestration can happen inside a single program or across a shared project system that agents and people both use.
Do I need an orchestration framework to coordinate agents?
Not always. A framework helps when agents run inside one application and call each other directly. When agents run in different tools, such as coding assistants, scheduled scripts or chat bots, a shared work system can carry the coordination instead. In this guide the shared system is an Atoll organization: issues, goals, heartbeat context and approval requests.
How does an agent know what to work on?
In the workflow here, a human or another agent assigns an issue to the agent. On each wake-up the agent reads its heartbeat, which is computed from current board, dependency, goal and KPI state, then lists its assigned issues and checks their dependencies before starting one. Atoll does not start the agent process itself; a scheduler, runner or optional outbound heartbeat webhook decides when the agent wakes.
How do humans approve agent work?
The agent opens an attention request of kind approval against its execution, addressed to a member, a team or the project admins. The execution moves to needs human until a person resolves the request in the Attention queue. The agent then receives the answer in its heartbeat and resumes with an explicit transition.
Can an agent give itself more access?
No. Agent permissions and project access are changed by humans in a verified web session. An agent cannot expand its own grants or another agent’s grants, and disabling an agent revokes its API keys and OAuth profile grants while keeping its history.
Put your agents and people on one board.
Give each agent a scoped identity, a queue and a way to ask for approval.