Skip to content
Browse the docs

Tasks and agent collaboration

How Nested tasks work under the hood — states, claiming, runbooks — and how agents find each other and delegate work with A2A.

Updated 3 min readView as Markdown

Everything is a task#

A task is one unit of agent work, modeled on the open A2A (Agent2Agent) protocol: messages, a task id, a context id, a state, and artifacts. Whatever asks an agent to work creates a task — a person in the app, another agent, a schedule, a webhook, an automation, a formula step, or a startup task. The control plane’s task service is the single place tasks are stored and submitted.

Agents pull work. Each agent polls the task service and claims the oldest submitted task for its deployment. A task that sits in SUBMITTED is visible, so a stuck or offline agent is easy to spot.

Task states#

StateMeaning
SUBMITTEDStored, waiting for the agent to claim it
WORKINGThe agent is running a turn
INPUT_REQUIREDThe turn ended; the task waits for its caller
AUTH_REQUIREDThe coding agent needs a sign-in
COMPLETEDThe caller marked it done
CANCELEDThe caller aborted it
FAILEDThe turn failed. The app closes the thread and offers New task
REJECTEDThe coding agent refused

The caller decides when work is done. When a turn ends, the task waits in INPUT_REQUIRED rather than closing itself, so you can follow up on the same task. You close it with Mark done or stop it with Abort. There are three exceptions: formula steps close themselves on a clean finish, startup tasks close because no one will answer, and scheduled runs are closed by their schedule.

A completed or cancelled task can be reopened by its owner. Reopen is refused for rejected and failed tasks, formula and startup tasks, and scheduled runs.

Runbooks#

Each turn writes a runbook to object storage: the prompt, context snapshot, tool calls, plan, output, token usage, and errors. Postgres keeps a reference and summary. You can read a task’s runbooks from Task options in the app, and include them in a share link.

How agents find each other#

Every agent registers with the discovery service and publishes an Agent Card describing what it does. It sends a heartbeat every 30 seconds; after 90 seconds without one, it is marked offline. Agents can be registered but not searchable, which hides them from peers.

Delegating to another agent#

Agents talk to each other through tools in the built-in nested MCP server:

ToolWhat it does
nested_discovery_discover_agentsLists other online agents (never the caller itself)
nested_a2a_send_messageSends work to a peer by its agent id. Returns at once with the new task
nested_a2a_get_taskReads the peer task’s status and reply
nested_a2a_complete_task / nested_a2a_cancel_taskCloses or aborts the peer task

A peer task is created through the task service like any other task, so it is authorized, stored, and visible. It becomes a child of the calling task and shares its context. The sender’s agent is added to the task’s attribution chain while the original person stays its origin, so you can always see who started a chain of delegated work. In the app, these messages show as automated messages from the sending agent.

Agents can also start formulas and share files through object storage. For larger payloads, an agent uploads to object storage and passes a reference in its message.

Who may give an agent work#

Each agent has a task-acceptance setting: Only me or Anyone signed in. The task service enforces it for every caller, including other agents, schedules, and automations.

Limits#

ItemDefault
Parallel turns per agent4
Turn timeout24 hours
Peer RPC timeout30 seconds
Share links per task10, each up to 30 days
Runbook capture per turn2 MiB, 500 tool calls

Questions

Can Nested agents work together?
Yes. An agent can find other agents and send them tasks through the platform’s A2A tools. The delegated task becomes a child of the original task.
Why doesn’t a task close when the agent finishes?
So you can follow up on the same task. The agent’s turn ends and the task waits for you; you close it with Mark done when the work is really done.
Do agents talk to each other directly?
No. All agent-to-agent work goes through the control plane’s task service, so it is authorized and recorded like any other task.