agentscope-ai / agentscope-ai/QwenPaw

[Feature]: Hierarchical Subagent with Context Inheritance

Abierto
#4,044 1 comentario 1 reacción 0 asignados Ver en GitHub
enhancement
Lenguaje dominante
TypeScript
Estrellas
35k
Forks
3.1k
Merge medio
1 d 13 h
PR fusionados (30 d)
228

Descripción

## Summary
Introduce a **hierarchical subagent** architecture where a parent agent can spawn child agents that dynamically inherit the parent's context, identity, and preferences at runtime — complementing the existing peer-to-peer multi-agent collaboration.

## Component(s) Affected
- [x] Core / Backend (app, agents, config, providers, utils, local_models)
- [ ] Console (frontend web UI)
- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
- [ ] Skills
- [ ] CLI
- [x] Documentation (website)
- [ ] Tests
- [ ] CI/CD
- [ ] Scripts / Deploy

## Problem / Motivation
Currently QwenPaw supports multi-agent collaboration via `chat_with_agent` and `submit_to_agent`, which works well for **peer-to-peer** communication between agents. However, when a user splits a long-running default agent into multiple specialized agents (e.g., `ai_research`, `coding`, `creation`, `business`), each agent operates in complete isolation.

This leads to several concrete pain points:

1. **Identity & Preference Duplication** — Every agent needs its own `AGENTS.md` with duplicated sections (MemPalace rules, token optimization guidelines, sibling agent references). Only `PROFILE.md` (shared identity) can be reasonably symlinked across workspaces.

2. **Context Loss on Agent Handoff** — When a parent agent delegates a subtask to another agent via `chat_with_agent`, the child agent starts with a fresh context. Previous conversation history, user preferences discovered during the session, and task state are lost.

3. **No Nested Delegation** — There is no way to spawn a temporary subagent for a specific subtask (e.g., "research this paper for me" from within a coding session) that inherits the current session's context.

These limitations force users to resort to fragile workarounds (file symlinks, manual config sync) that don't solve the fundamental problem: **child agents cannot dynamically inherit parent context at runtime**.

## Proposed Solution
Introduce a **hierarchical subagent** model alongside the existing peer-to-peer collaboration.

### Subagent Lifecycle

```
Parent Agent Session
├── System Prompt (inherited)
├── Session Context (inherited, optionally filtered)
└── Subagent Spawn
├── Inherits parent identity (PROFILE.md)
├── Inherits parent preferences & rules (selective AGENTS.md sections)
├── Receives task-specific context injection
└── Returns result + summary back to parent
```

### Conceptual API

```python
# Parent agent spawns a subagent for a specific task
subagent = await spawn_subagent(
agent_id="coding", # which agent definition to use
inherit=["profile", "memory", "session_context"], # what to inherit
context_filter="relevant", # "all", "relevant", or "none"
ephemeral=True, # auto-destroy after task completion
)

result = await subagent.run("Refactor this function")
```

### Context Inheritance Levels

| Level | Description |
|-------|-------------|
| `identity` | PROFILE.md (shared identity) |
| `rules` | Global sections from AGENTS.md (MemPalace, token optimization) |
| `memory` | Parent agent's MEMORY.md / memory search access |
| `session` | Current conversation history (full or summarized) |
| `task` | Explicit task description and parameters |

### Workspace Implications

With subagent support, specialized agents (`ai_research`, `coding`, etc.) could become **agent definitions** (templates) that are instantiated as subagents rather than standalone persistent workspaces. The workspace structure could evolve to:

```
workspaces/
├── default/ # Root agent (orchestrator)
│ ├── PROFILE.md # Shared via inheritance
│ ├── AGENTS.md # Orchestrator-specific
│ └── MEMORY.md # Global long-term memory
├── skills/ # Global skills (shared)
└── subagents/ # Ephemeral subagent sessions (auto-cleanup)
└── {session_id}/
```

This is **distinct** from the existing multi-agent collaboration model (`chat_with_agent` / `submit_to_agent`) which focuses on peer communication. Subagent support is about **nested, context-aware delegation** within a single user session.

## Alternatives Considered
- **File symlinks** (current workaround): Works for static config files like `PROFILE.md`, but cannot handle runtime session context.
- **Copy-paste AGENTS.md sections**: High maintenance, easy to drift out of sync across agents.
- **Centralized config file**: Doesn't solve session context inheritance or nested delegation.
- **Enhanced `chat_with_agent` with context passing**: Could work for some cases, but doesn't provide the clean lifecycle model (spawn → inherit → run → return → destroy) that subagents would offer.

## Additional Context
Related issues that touch on adjacent problems:
- #153, #508 — Multi-agent collaboration (peer-to-peer)
- #1990 — Copaw subagent scheduling question
- #1785 — Cron task requesting subagent with different model
- #4031 — Multi-agent collaboration context loss

## Willing to Contribute
- [ ] I am willing to open a PR for this feature (after discussion).

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.