Repository navigation
Sub-agents: the framework's task on both backends - #320
Merged
Merged
Conversation
Delegations.delegate is the one place a sub-agent run starts and ends: the brief read against the caller's own sub-agents, the run named and its AGENT_RUN start and end recorded and reported, the backend's hook run in a task of its own, the envelope returned. AGENT_RUN and RunRecord carry the brief, who started the run and its mode; BaseWorkflowManager gets _delegations and the _run_agent hook; /agents <id> shows a run's brief. No backend delegates through it yet.
child_app and child_session_id name a sub-agent run's child session (<app>--agents, <conversation>/<instance>, at most 128 characters). The call clocks and the fit guard's request copies are let go as their own run ends (after_run_callback, on_run_error_callback) rather than purged for every other invocation as a run starts, so runs that share a chain keep each other's.
Each agent's graph is built on its own; a delegating agent gets the framework's task tool (build_task_tool) in place of SubAgentMiddleware, and the manager's _run_agent runs the type's graph in the run's own task, apart from its parent's stream, through a processor made for the run. The answer is the run's last text, its outcome the outcome middleware's mark, an overflow a failed run; the plan and tasks it changed come back with its envelope. The namespace inference, the fork and the middlewares' delegation cases go. The contract suite delegates through task and reads the envelope; its ADK crews wait for ADK to do the same.
Each config-built agent is built on its own; a delegating agent gets the framework's TaskTool, and each sub-agent type runs on a runner of its own (App <app>--agents, the main chain configured for a sub-agent) over the manager's session service, each run on a child session <conversation>/<instance>. The manager's _run_agent runs the task message there, stopped with its abort signal first, through a processor made for the run; a model's failure is the provider's reason, an overflow a failed run. The inheriting note ends the task message, not the instruction. ADK's single-turn delegation, the branch runs and the returned-run ending go, and so do the transitional pieces the Deep Agents task left.
The CHANGELOG says ADK and Deep Agents offer one task tool that takes a brief and answers with the run's envelope, and rewrites the bullets that named the differences now gone; CLAUDE.md's structure lines and the delegation, tool-error and identity passages describe Delegations, the task tools, ADK's child sessions and Deep Agents' detached runs; the README's delegation passages follow.
A run's answers were every AI message of its final state, so an inheriting run that wrote no text returned its caller's last reply from the conversation it read. Its answers are now the messages after its task message, found by an id the task message is given: before_agent may insert answers to calls left open in that conversation ahead of it, so its position is no guide. The test fake's hook reads its answers the same way. A contract scenario pins the empty result on both backends; ADK's run processor reads only the run's own events and already did.
…h backends ADK's task tool returns the envelope as JSON text, which the cap cut as plain text: an envelope over tool_result_max_chars reached the parent as broken JSON, read_envelope found none and the CLI showed no delegation. Deep Agents' cap already parsed a ToolMessage's JSON object and cut it as a dict. That rule now lives in the shared cap (json_object): a string that holds a JSON object is cut as that dict and given back as its JSON text, written with ensure_ascii=False as it is measured, and Deep Agents' middleware uses it. Both task tools write the envelope unescaped, since an escaped non-Latin answer is six times as long. Contract scenarios pin a long envelope and an unescaped one on both backends; the CHANGELOG also says an inheriting run's result is only what it wrote.
An inheriting run's child session holds copies of its conversation's events, whose authors (the root among them) its runner's tree does not have; ADK's agent router warned of each as it picked the agent to run, over the prompt, on every inheriting delegation. A narrow filter on that logger logs the warning at debug (adk_inherited_unknown_author), as the other ADK filters do. A delegation test pins that ADK gives the warning by that logger and text, so the filter keeps matching.
The root turn streams with subgraphs=True, and once sub-agents ran apart the processor took every item as the root's, whatever its namespace: an app tool that runs a LangGraph graph under the config it inherits had that graph's model text shown as the root's reply. The processor now reads only the root namespace's items. A real turn with such a tool pins it, and the processor test that pinned the old reading now pins the new.
ContextCachePlugin kept its per-call state until after_run_callback, which ADK skips for a run that raises, so every failed sub-agent run (an invocation of its own) left its entries behind. It now lets go in on_run_error_callback too, of its own invocation's state only, as the call clock and the fit guard do. The plugin had no tests: they pin the one-try rule and both endings.
ADK's _changed compared with !=, while Deep Agents' copies Deep Agents' own task rule (_is_unchanged): a key returned as it was received, or equal to it, is no change, and an ambiguous comparison counts as one. On an array ADK's raised. ADK now copies the same rule, with the same comment. New unit tests pin the rule on both managers, and Deep Agents' _last_text and _own_messages: the builder tests' fake hook only re-implements them.
The nested-failure scenario checks again that the middle agent reads why its leaf failed, the provider's reason in the envelope's error. A stopped turn's scenario checks that the run's tool in flight stopped before the stop returned (contract_block says when it stops). The two runs of one type that number their calls alike now meet at a barrier (contract_echo_together), so both call_0 calls are open together. The call-clock tests check which invocation's clock stays: the other run's answer is still timed after a run lets go of its own, which tells forgetting one's own from keeping only one's own; their comments no longer say parallel delegations share an invocation.
CLAUDE.md's ADK summarizing passage said a sub-agent's overflow answers with text and that parallel delegations share an invocation; a sub-agent's call that still does not fit now ends its run failed (CONTEXT_OVERFLOW, RunFailed), and each run is an invocation of its own that shares only its type's runner and plugins. The call clock, the raw log and the active run's comment said where identity came from before the framework's delegation set it. The README and CHANGELOG said a fresh sub-agent sees the request where it sees its task, kept a dangling version note on the inheriting rule and a circular account of when a run fails; the README's AgentConfig and YAML tables gain brief_required and limits (configuration, validated and kept: no run is stopped by the limits), and the delegation bullet says ADK's sub-agents now get ADK's identity line.
Three scenario docstrings named the plan's review items and a spec section; they now say what the scenario pins.
The test that pins ADK's warning read it through caplog, which a filter installed by an earlier test (test_adk_overflow's notice_hook, or any test that runs the CLI) swallowed: it failed in the full suite and passed alone. It now takes that logger's filters off for its duration.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Delegation becomes the framework's on both backends. A delegating agent is offered one tool,
task, the same on ADK and Deep Agents:agent_typeand a brief (title,objective,deliverable,constraints,known,done_when). The parent reads the run's envelope as JSON.workflow/agents/delegate.py::Delegations.delegateis the one place a sub-agent run starts and ends:AGENT_RUNstart and end;BaseWorkflowManager._run_agent(AgentRun) -> RunAnswerin a task of its own, where the run is the active run;failedwith the provider's reason, and one recoverableERROR.sub_agents, nosingle_turn, no_SingleTurnAgentTool. A delegating agent has oneTaskTool.App(name="<app>--agents"), the main chain configured for a sub-agent; every plugin's per-call state is its own invocation's).<conversation>/<instance>, which no conversation list reads.astreams it in its own task, with LangChain's ambient config cleared, so its chunks never reach the parent's stream.SubAgentMiddleware, the fork and the middlewares' delegation special cases go.adk/branches.py,runs.run_ended).Tests: new tests written first and seen failing; the full offline suite passes in the worktree except
TestChildImportOrigin, which fails the same way on develop under the worktree wrapper.