Skip to content

Sub-agents: the framework's task on both backends - #320

Merged
shoom1 merged 15 commits into
developfrom
feature/delegation-hook
Nov 17, 2026
Merged

shoom1 merged 15 commits into
developfrom
feature/delegation-hook

Conversation

@shoom1

@shoom1 shoom1 commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Delegation becomes the framework's on both backends. A delegating agent is offered one tool, task, the same on ADK and Deep Agents: agent_type and a brief (title, objective, deliverable, constraints, known, done_when). The parent reads the run's envelope as JSON.

  • workflow/agents/delegate.py::Delegations.delegate is the one place a sub-agent run starts and ends:
    • it reads the brief against the caller's own sub-agents (a call that cannot start a run is the call's error, with no run and no number);
    • it names the run and reports its AGENT_RUN start and end;
    • it runs the backend's hook BaseWorkflowManager._run_agent(AgentRun) -> RunAnswer in a task of its own, where the run is the active run;
    • it hands back the envelope.
    • A sub-agent starts from the conversation's plan and tasks, and the keys it changed come back.
    • A failure or an overflow ends the run failed with the provider's reason, and one recoverable ERROR.
  • ADK. Every agent is built on its own: no ADK sub_agents, no single_turn, no _SingleTurnAgentTool. A delegating agent has one TaskTool.
    • Each sub-agent type runs on a runner of its own (App(name="<app>--agents"), the main chain configured for a sub-agent; every plugin's per-call state is its own invocation's).
    • Each run gets a child session <conversation>/<instance>, which no conversation list reads.
    • An inheriting run's child session gets the conversation's events copied.
  • Deep Agents. Each type's graph is built on its own, and a run 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.
    • An inheriting run's answer is only what it wrote.
  • Gone: P1's inference of a run from ADK's branch and Deep Agents' namespace (adk/branches.py, runs.run_ended).
  • One rule on both backends: the shared tool-result cap cuts a string holding a JSON object as that object, so a long envelope stays JSON.
  • Logging: ADK's "Event from an unknown agent" warning for an inheriting run's copied events goes to debug.
  • Contract suite: every scenario runs on both backends, with expectations on the envelope:
    • the task message as the first request;
    • completed, partial, refused, failed and overflow;
    • parallel runs each ending at their own end;
    • shared plan and tasks;
    • an inheriting run;
    • two runs of one type with the same call ids;
    • an empty last answer;
    • a long result;
    • a delegation off the event loop.

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.

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.
@shoom1
shoom1 merged commit 525b29a into develop Nov 17, 2026
6 checks passed
@shoom1
shoom1 deleted the feature/delegation-hook branch November 17, 2026 23:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant