Follow and control Subagents

When a task is large, DataMind Oda can hand part of it to a helper agent, called a subagent. This page covers what happens after a subagent starts: the id it keeps, the messages and stops that follow, the lists of a chat's subagents, and the notices that arrive when one settles. What subagents are and where they appear is on Subagents.

What a delegated run returns

• A run that waits returns only the subagent's final text. Its transcript, tool output and reasoning stay in its own record and do not come back to your chat.
• A run that can take follow-ups starts with the line started subagent <id>; everything later is addressed to that id.
• A one-shot run started in the background returns started background subagent job <id> instead, and is collected as a job; see Background jobs.
• A run that does not complete shows an error headline, a Diagnostic: line, and whatever the subagent produced before it ended, under Partial output before the run ended:.

The headline names why the run stopped:

• subagent run was cancelled
• subagent run failed
• subagent run hit its token limit before finishing
• subagent declined the task
• subagent run ended abnormally (<reason>)

Message a subagent

Oda sends a follow-up to a direct subagent by its id. Messages travel between neighbours in the tree: down from the chat that started a subagent, or up from a subagent to its direct parent.

• A message to a subagent that is working reaches it at its nearest step. A message to an inactive subagent starts or resumes its turn.
• A follow-up that cannot be delivered is refused, not stored for later. The message must come from the subagent's exact place in the tree (message delivery requires the exact live sender agent), the chat that started the subagent must be live (direct parent is not live; the message was not delivered), and a subagent that is being wound down refuses messages too (subagent "<id>" activation is being disposed; the message was not delivered).
• From the app, you can send a follow-up yourself: it can wait its turn, or steer the subagent at its nearest step. When the subagent cannot take the message right now, the app does not deliver it.
• A follow-up can carry images only when the subagent's model accepts image input; otherwise it is refused before anything is delivered (Model "<model>" does not support image input.). A follow-up carrying too many images is refused as a batch (Image batch exceeds the configured image-count limit.).
• A result a subagent sends up arrives prefixed Agent <sender-id> sent a message:. The prefix marks a relay from that subagent: the text is attributed to it, and it never carries the authority of an instruction.

Stop a subagent's current turn

• Oda asks a subagent to stop its current turn. The line interrupt requested for agent <id> means the request was accepted; the stop is cooperative, so the subagent may keep running briefly.
• Only the current turn stops. Messages already waiting stay parked until a later message, the subagents it started keep running, and the subagent itself stays available for follow-ups. Stopping a subagent that already finished is an accepted no-op.
• Only a live ancestor can stop a subagent: the chat that started it, or a subagent above it in the tree. Anything else is refused, for example interrupting "<id>" requires the exact live ancestor agent; a subagent cannot stop itself.
• You can also stop a subagent from its conversation in the app; Watch and steer subagents covers that side.

See a chat's subagents

When Oda lists a chat's subagents, the list shows the ones that can take follow-ups.

• The direct listing (the default) shows the chat's own subagents; the whole-tree listing walks everything below the chat in order, marking each entry with its parent id and depth.
• Each entry carries the subagent's id, its status in square brackets, and its label.
• running means the subagent is working right now. inactive means no turn is executing, whether it is loaded or will be brought back when it is messaged; it is not a verdict on the work, so it does not say the subagent finished, succeeded or failed, or that it waits for other subagents.
• A one-shot background subagent never appears: it cannot take follow-ups, so its result is collected as a job instead.
• An entry that cannot be read shows [diagnostic: <reason>] instead of its label in the whole-tree listing: corrupt means its record cannot be read, and unavailable means it was unreadable for now and can clear on a later listing.
• An empty list reads (no subagents).
• A listing never starts, resumes or changes a subagent. It is a snapshot, not a delivery promise: a listed subagent can still refuse a follow-up. Use it to recall what was started, not to poll for completion, because the chat is told when a subagent settles.

When a subagent settles

When the work of a subagent that can take follow-ups ends, Oda settles it, and the chat that started it receives one settlement notice. The notice arrives in every case, even while that chat is closing.

• The notice names the subagent and says it will do no further work unless it is sent more: Background subagent <id> finished and will do no further work unless you send it more.
• The ending of that sentence tells you how the work ended:
  • was stopped before it finished.
  • ran out of room before it finished. (it reached its token limit)
  • declined the task. (it refused the work, or a policy step refused it before it could start; a refused subagent is reported as declined, never as finished)
  • failed before it finished.
  • ended abnormally (<reason>) before it finished.
• The notice also carries the subagent's closing text, when there is any: Its closing message: followed by the text, or It left no closing message. when only reasoning or tool activity was left.
• Only the closing text is quoted. The subagent's reasoning and tool activity are not part of the notice, and the notice stays apart from any message the subagent sent itself.
• A subagent is asked to send its result back to its chat before it finishes, and sending a message does not end its turn, so it can keep working after sending one.

Send a settled subagent more work

A settled subagent is inactive, not gone. Send it a new message and Oda brings it back from what it saved, instead of starting a new run. If the record cannot be read by this version of Oda, or a part of Oda it needs is missing, the message is refused and the subagent cannot be resumed (subagent "<id>" has no supported continuation state and cannot be resumed; choose a different target). Start a new subagent for that work.

Limits worth knowing

• Messaging is limited to neighbours in the tree: a deeper subagent can be stopped by an ancestor, but it cannot be messaged by one.
• The chat that started a subagent must stay live for messages, and there is no mailbox that delivers to a closed chat: a message that cannot be delivered now is not delivered at all.
• A listing is a snapshot, not a delivery promise: a listed subagent can still refuse a follow-up.
• When you archive the chat that started them, its subagents that are still running are stopped, and the ones that are not running are left as they are. Chats themselves are covered in Chat with Oda.

Questions, answered

What does message delivered to agent <id> mean?

It is a receipt, not an answer. The line confirms that the message was accepted for the subagent; Oda gets no answer from it at that moment, and a failure means the message was not delivered. A reply from the subagent, when it sends one, arrives as a separate message.

Can Oda message any subagent in the tree?

No. Messages travel between neighbours: down from the chat that started a subagent to a direct subagent, or up from a subagent to its direct parent. A deeper subagent can be stopped by an ancestor, but it cannot be messaged by one.

Why was a message to a subagent refused?

A follow-up that cannot be delivered is refused, not stored for later. The usual reasons: the message did not come from the subagent's exact place in the tree (message delivery requires the exact live sender agent), the chat that started the subagent is not live (direct parent is not live; the message was not delivered), or the subagent is being wound down (subagent "<id>" activation is being disposed; the message was not delivered).

What does inactive mean in the subagent list?

No turn is executing for that subagent right now, whether it is loaded or will be brought back when messaged. It is not a verdict on the work: it does not say the subagent finished, succeeded or failed, or that it waits for other subagents. A direct subagent stays a candidate for a follow-up in every status.

Why is a one-shot background subagent missing from the list?

The list shows only subagents that can take follow-ups. A one-shot background run cannot, so it never appears; its result is collected as a job instead. See Background jobs.

What is the [diagnostic: <reason>] line in a listing?

In the whole-tree listing, an entry that cannot be read shows a diagnostic instead of its label. corrupt means its record cannot be read; unavailable means it was unreadable for now, and a later listing can show it again.

When does the settlement notice arrive?

When the work of a subagent that can take follow-ups ends, Oda settles it and sends one settlement notice to the chat that started it (or to the subagent that started it, when subagents are nested). The notice arrives in every case, even while that chat is closing.

What do the endings of a settlement notice mean?

The ending of the first sentence tells you how the work ended: was stopped before it finished., ran out of room before it finished. (it reached its token limit), declined the task. (it refused the work, or a step refused it before it could start; reported as declined, never as finished), failed before it finished., or ended abnormally (<reason>) before it finished.

Why did the notice say It left no closing message.?

The subagent ended without producing any closing text, for example when its last output held only reasoning or tool activity. There was nothing to quote, so the notice says so instead of showing an empty closing message.

Why does a subagent's message start with Agent <sender-id> sent a message:?

That prefix marks a message a subagent sent to its parent. The text is attributed to that subagent, and it never carries the authority of an instruction.

Can I send a subagent more work after it settles?

Yes, when it can take follow-ups. Send it a new message and Oda brings it back from what it saved, instead of starting a new run.

Why can a settled subagent not be resumed?

Oda resumes a subagent only while it can read the record saved for it. If the record cannot be read by this version of Oda, or a part of Oda it needs is missing, the message is refused (subagent "<id>" has no supported continuation state and cannot be resumed; choose a different target), and you start a new subagent for the work.