Sub-agents now report what they actually did
Sub-agents in the n8n AI builder now send and receive structured briefings with full thread-state awareness, and return diagnostic summaries that let the orchestrator see tool call counts, errors, and blockers — not just final text.
When a sub-agent in the n8n AI builder needed context, four separate code paths built briefings by hand — each with its own format for conversation history, artifacts, and retry context. The protocol forbade any explanatory prose, so agents that hit blockers had no way to tell the orchestrator why. The orchestrator received a bare string and had to guess.
A new shared briefing builder replaces all four constructions with a single buildSubAgentBriefing() call. Sub-agents now receive XML-formatted sections: a task block, conversation context, structured artifacts, additional context, requirements, thread state (what else is running), and iteration history. The machine-readable structure gives clear section boundaries.
The sub-agent protocol no longer bans all prose. When something fails or requires a non-obvious decision, agents can now include two to three sentences of diagnostic context explaining what they tried, what blockers remain, and what assumptions were made. Tasks that complete cleanly omit diagnostics entirely.
A WorkSummaryAccumulator passively observes the stream as tool calls execute, tracking outcomes by tool call ID. When the sub-agent finishes, the delegate tool returns not just the result string but also the tool call count, error count, wall-clock duration, and specific blockers encountered. The orchestrator sees what actually happened — which tools failed, why — enabling smarter retry decisions.
The changes live in the @n8n/instance-ai package across the agent runtime, stream processing, and orchestration tooling layers.
View Original GitHub Description
Summary
Sub-agents (builder, research, data-table, delegate) were receiving context through ad-hoc string concatenation and returning bare { result: string }.
Each spawn site had its own copy-pasted briefing construction, the protocol forbade any diagnostic reasoning, and the orchestrator had no visibility into what the sub-agent actually did. This made retries blind, debugging difficult, and the codebase repetitive.
This PR simplifies the handover in both directions:
Context flowing in: A single shared buildSubAgentBriefing() replaces 4 copy-pasted briefing constructions across delegate, builder, research, and data-table agents. Sub-agents now receive structured context (task, conversation history, artifacts, retry history) plus awareness of what other tasks are running in parallel.
Context flowing back: A lightweight stream observer (WorkSummaryAccumulator) passively tracks tool call outcomes as they flow through the existing stream loop. The delegate tool now returns tool call counts, error counts, duration, and blockers alongside the result — so the orchestrator knows what happened, not just what the sub-agent said.
Diagnostic reasoning: The sub-agent protocol no longer forbids all prose. Sub-agents can now include 2-3 sentences of diagnostic context when something fails or requires a non-obvious decision. The orchestrator learns why something failed, enabling better retries.
- I have seen this code, I have run this code, and I take responsibility for this code.