agentscope-ai / agentscope-ai/QwenPaw

[Feature]: Hierarchical Subagent with Context Inheritance

未關閉
#4,044 1 則留言 1 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement
主要語言
Python
星號
34.9k
分支
3.1k
平均合併
1 天 15 小時
30 天內合併 PR
225

描述

## 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).

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。