feat: Support subagents in Agent class to manage context and scale complex tasks

[GSword]

Is your feature request related to a problem? Please describe.
The current Agent class (from agentscope.agent) does not natively support subagents. In real-world scenarios, a main agent often needs to delegate heavy reading and filtering of large volumes of data to specialized subagents. Without this capability, all the raw data and intermediate results must be processed within the main agent's context, which quickly pollutes the context window, increases token costs, and degrades performance.

Describe the solution you'd like
I propose adding a native subagent mechanism similar to the DeepAgents framework. For example, we could have a factory function or a constructor that accepts a list of subagent definitions, like:

from agentscope.agent import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    subagents=subagents,  # list of Agent instances or configurations
)

The main agent should be able to:

1. Delegate tasks to specific subagents with clear instructions.
2. Receive filtered/summarized results from subagents.
3. Manage context by only keeping high-level reasoning and final outputs, while subagents handle the heavy data processing in their own isolated contexts.
4. This would greatly improve scalability for tasks like document analysis, retrieval-augmented generation, and multi-step research workflows.

[DavdGao]

@GSword We have considered to support subagents in sdk-level. However, the issue is that how to expose the hitl events from the sub agents within a unified streaming reply_stream interface, and how to receive the respond event in the reply_stream interface of the parent agent and router the hitl event to its subagents.

[RICARDO51167]

Could a "permission inheritance + unified routing" approach be adopted: 1. When a child proxy is created, it inherits the permissions already obtained by the parent proxy, but can further tighten permissions through its own configuration. 2. When the child proxy encounters permissions that the parent proxy has not yet obtained, it generates a HITL event with request_id, agent_path, and reply_id. 3. A deterministic combined runtime/manager bubbles this event up to the parent proxy's reply_stream 4. The user still submits the confirmation result to the parent proxy, and the manager routes back to the atomic proxy based on the request_id and resumes execution.

[DavdGao]

@RICARDO51167 Yes, that does seem to be the direction we need to take — though it also means breaking some of the existing event bubbling logic. Specifically:

1. We need a way to surface HITL events from within ToolChunk or ToolResponse. One option is to add a yield return type to ToolBase.call (e.g., directly yielding a RequireUserConfirmationEvent); another is to introduce a new status flag and data field on ToolChunk or ToolResponse, so that the outer layer — i.e., the agent's acting function — can capture and forward the event upstream.
2. When the user approves or rejects, the tool needs an additional entry point, since ToolBase.call currently has no mechanism to receive a UserConfirmResultEvent.

That said, I think we need to settle on the overall design pattern first. A few open questions:

1. From the parent agent's perspective, it makes sense to hide the intermediate steps of a subagent (e.g., internal reasoning, tool calls, tool results). But should the caller of the parent agent's reply_stream be able to see those events? In principle, they should at least be yielded — whether to display them is up to the caller. If we don't yield them at all, there's no visibility into the subagent's execution.
2. This leads to an architectural concern: if ToolBase.call needs to yield all AgentEvents in addition to ToolChunk and ToolResponse, the overall architecture starts to feel quite awkward.

---

There is, however, a more disruptive alternative worth considering: inject all events produced by parent_agent._reply into an asyncio.Queue, mount any running subagent's reply task onto a parent agent attribute (e.g., self._subagent_task), and route all yielded events through this shared queue. In other words, use a single unified Queue to collect events from all agents, while the parent agent's reply runs as a background async task (i.e., not the current task). I'm not sure yet.

[RICARDO51167]

Thank you for your detailed explanation. Regarding your questions:

1. I believe the caller of the parent proxy's reply_stream should be able to observe events generated by the child proxy. However, "caller observability" should be distinguished from "visibility within the parent proxy model context." HITL, failure, cancellation, and completion events should always be visible; other intermediate events can be controlled through visibility options. The parent model itself should generally only receive the final result from the child proxy.

2. I also agree that allowing ToolBase.call to generate arbitrary AgentEvents feels inappropriate. It couples the tool protocol with the complete proxy execution protocol, requiring each tool middleware and adapter to understand both domains.

3. I'm unsure if the tool really needs a new entry point for UserConfirmResultEvent. If the runtime tracks the child proxy that generated the HITL request, the confirmation information can be routed directly to that child proxy's reply_stream. The parent proxy's delegate tool simply needs to wait for the child proxy's final result.

Therefore, the shared queue scheme seems promising to me, requiring only a slight adjustment: the parent agent's response can have a small, per-run monitor containing the registry for the sub-agent's operation, instead of mounting a single self._subagent_task.

The logical relationships remain unchanged:

└── Create and delegate to sub-agent

The runtime scheduling relationship is as follows:

Run Monitor

├── Parent Agent Reply Task

└── Sub-Agent Reply Task

The parent agent still decides when and why to create the sub-agent. The monitor does not make delegation decisions; it is only responsible for starting the sub-agent, collecting events, routing HITL results, and returning the sub-agent's final results to the waiting parent agent tool invocation.

The possible flow is as follows:

1. The caller invokes the normal parent agent Agent.reply_stream.

2. The parent agent invokes the sub-agent creation/delegation tool.

3. The tool requests the currently running manager to create and run a subroutine, then waits for the subroutine's result handle.

4. Both parent._reply and child._reply publish their events to the manager's queue.

5. The common parent reply_stream clears this queue and delivers the event to the caller.

6. Subroutine events carry source information, such as agent_path, but always remain outside the parent model context.

7. If a subroutine generates a HITL event, the manager logs an opaque request_id.

8. When a caller submits a result through the same parent Agent API, the manager routes it directly to the appropriate subroutine.

9. After the subroutine completes, its final result resolves the handle the delegate tool is waiting for, and the parent program continues to run normally.

This avoids modifying ToolBase.call to generate all types of AgentEvent, and also avoids adding a generic acknowledge-recovery protocol to all tools. The queue will be an internal event multiplexer, not part of the tool protocol.

I prefer a registry similar to SubagentRun rather than a single _subagent_task because even if the first version only supports one subtask, the registry can naturally hold parent_run_id, status, pending HITL requests, and cancellation status, and can later support concurrent or nested subtasks.

For a minimal in-memory implementation, I think changes can be kept within reasonable limits: a per-run hypervisor, a subagent creation/delegation method, source metadata for sub-events, and routing in a public reply_stream. Persistent recovery across process restarts will be a separate and more complex issue.

Looking forward to further discussion.

[RICARDO51167]

One additional reference: Codex’s subagent design follows a similar separation. A subagent is an independently managed agent thread, while tools such as spawn, wait, and interrupt are only control-plane entry points.

This suggests that AgentScope could treat SubagentRun as the real execution entity:

SubagentRun(run_id, parent_run_id, status, pending_hitl, result)

The parent still decides when to create a child; the supervisor only manages execution, event routing, and lifecycle. Child events can carry their run_id and remain observable to the caller without entering the parent model’s context.

For HITL, the runtime can route:

request_id → child_run_id

and return the final child result to the corresponding parent tool call. This avoids adding arbitrary AgentEvents or a generic resume() mechanism to ToolBase.

So the main principle I would borrow is:

The control plane belongs to the Agent runtime, not the Tool protocol.

Reference: https://developers.openai.com/codex/subagents

[jimy-r]

One design point that decides whether subagents actually save context, from running this pattern daily. The saving comes from the subagent's transcript being a separate context. That holds only if what it returns is small. A subagent that reads 40 files and returns a 3,000-token report has moved the cost, not removed it, because the parent re-sends that report on every later step of its own turn. Cost per token is size times the number of steps remaining after it arrives, so a long return early in a parent turn is the most expensive shape there is.

So the API for a subagent needs a return budget as a first-class parameter. The subagent writes the full detail to a file or a store, and returns a short summary plus the path. The parent reads the detail only at the step that needs it, if at all.

On HITL routing, the same boundary helps. An approval request from inside a subagent should surface to the human through the parent with the summary, not the transcript, for the same reason.

I maintain a reference architecture that documents this exact pattern: https://github.com/jimy-r/agent-workspace-architecture/blob/main/PATTERNS.md#18-position-is-price--a-token-costs-more-the-earlier-you-add-it

[capitaharlock]

jimy-r’s point about the 3,000-token report is the crux here. If the subagent dumps a big transcript back, you have not bought anything, you just moved where the tokens get burned.

The missing primitive is an artifact store. Subagent writes its full output to a shared store, returns a handle plus a one-paragraph summary, parent dereferences the handle only when it actually needs the detail. That turns the return boundary into reference-passing instead of value-passing, and the savings stop depending on prompt discipline.

The return contract has to be declared when you define the subagent, though. Shape of the artifact, token budget for the summary, what gets persisted. If the framework enforces that contract structurally, it works even when the subagent misbehaves or the task drifts. Relying on the model to keep its summary tight is exactly how you end up with parents re-reading 3,000-token reports every step.

We hit the same wall building something adjacent, and the enforced contract is what made it stick. Without it, the abstraction leaks and you are back to prompt engineering the size of the return value.

[jimy-r]

Agreed that the contract has to be structural, and one harness already exposes it. Claude Code has a per-subagent return cap (taskOutputMaxChars). I run it at 6,000 characters, roughly the 1,500-token band, and the dispatch prompt tells the worker to write detail to a file and return the path plus a summary inside that cap. The cap is what makes the discipline hold when the worker drifts, which is your point. The handle is a file path rather than a store id. That is enough on one machine and would want the artifact store you describe the moment two workers share a result.

One number worth adding to the contract is where the return lands in the parent turn. A budget caps size, but the same return costs more the earlier it arrives, because every later step re-reads it. So the parent should defer the dereference to the step that needs it rather than read the handle on receipt.

[DavdGao]

@GSword @RICARDO51167 We've merged SDK-level subagent support through TeamPipeline in #2764.

The leader can delegate tasks to member agents running in their own contexts and receive their final replies as tool results, addressing @GSword's context-isolation use case. Following the separation @RICARDO51167 suggested, the pipeline handles orchestration and HITL routing without extending the tool protocol to carry arbitrary agent events. Callers can observe both leader and member events through a unified reply_stream().

To keep the interface and usage consistent with regular tool calls, delegation is currently blocking from the leader's perspective: it waits for the assigned members to finish before continuing. Different members can still run concurrently within the same round.

Thanks for the ideas here! Please give TeamPipeline a try and share any further suggestions or missing use cases in this discussion.

[lemonaide152]

Your ask to support subagents on the Agent class so a main agent can manage context and scale complex tasks is exactly the handoff lane I care about.

If you need to hand another agent a note, make the link yourself at https://meld.mergeinc.workers.dev. Say what it's for. They have 36 hours to answer. Each reply keeps that same link open for another 24 hours. It's free.