# How to Implement Subagent Delegation Patterns in Custom Agents for HVE Core

> Learn to implement subagent delegation patterns in HVE core custom agents. Orchestrate specialized subagents for modular, maintainable workflows using runSubagent or task tools.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Subagent delegation patterns enable parent agents to orchestrate specialized subagents by declaring dependencies in front-matter and invoking them via `runSubagent` or `task` tools, creating modular, maintainable workflows.**

Subagent delegation patterns form the architectural backbone of the **microsoft/hve-core** repository, allowing complex AI workflows to be decomposed into focused, reusable components. By implementing subagent delegation patterns, you can build parent orchestrators that coordinate specialized subagents for research, implementation, or validation without monolithic agent definitions.

## Architecture of Subagent Delegation

Understanding the core components is essential before implementing subagent delegation patterns in your custom agents. The architecture separates concerns between orchestration and execution, using declarative front-matter and glob-based path resolution.

### Parent Orchestrator Agents

The **parent agent** (orchestrator) declares its subagent dependencies in the `agents:` front-matter field and controls the overall workflow flow. According to the [RPI Agent definition](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/rpi-agent.agent.md), pure orchestrators set `disable-model-invocation: true` to prevent the parent from invoking its own model when it only coordinates work. The parent defines the protocol for when and how each subagent runs, potentially launching independent subagents in parallel and aggregating their outputs before proceeding to the next phase.

### Subagent Files

**Subagent files** contain focused logic for specific tasks and reside under `<collection>/subagents/`. Each subagent file sets `user-invocable: false` in its front-matter to prevent direct invocation from the UI, ensuring they can only be called by parent agents. As implemented in the [Researcher Subagent](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/subagents/researcher-subagent.agent.md), these files expose only the tools required for their specific task and define clear input/output contracts.

### Invocation Protocol

The parent invokes subagents using the `runSubagent` or `task` tool with a **glob path** like `.github/agents/**/researcher-subagent.agent.md`. This glob pattern ensures the engine can resolve the subagent regardless of directory depth or collection layout changes. The orchestrator supplies required inputs through the `inputs` field, and the subagent returns artifact paths and status indicators for the parent to consume.

## When to Use Subagent Delegation Patterns

Implement subagent delegation patterns when your workflow exhibits specific characteristics that benefit from modular separation.

- **Distinct tool sets** – When a step requires specialized tools (e.g., web search, file grep) that the parent does not need, encapsulate the logic in a subagent to maintain least-privilege tool access.
- **Structured output requirements** – When a step produces file-based artifacts (research logs, validation reports) that subsequent phases consume, subagents isolate that responsibility and output generation.
- **Cross-flow reusability** – When logic such as convention discovery or phase implementation recurs across multiple parent agents (RPI Agent, PR reviewer, design-thinking coach), subagents prevent duplication.

Conversely, keep simple, single-line actions inline to avoid unnecessary overhead. Delegation adds coordination complexity, so use it for substantial, self-contained subtasks.

## Step-by-Step Implementation Guide

Follow these steps to implement subagent delegation patterns in your HVE Core custom agents.

### 1. Create the Subagent File

Place the subagent under `<collection>/subagents/` with restricted permissions and focused tool grants.

```yaml
---
name: Researcher Subagent
description: "Research subagent using search, read, fetch-web, and GitHub tools"
user-invocable: false
---

# Researcher Subagent

## Inputs

- `scope` – topic to investigate.
- `output` – file path where the research log will be stored.

## Protocol

1. Use `search` to find relevant docs.
2. `read` key instruction files.
3. `fetch_web` for external references.
4. Write findings to `{{output}}`.

## Response

Return the path to the research document and a status flag.

```

### 2. Declare Dependencies in Parent Front-Matter

Add the `agents` list and disable model invocation if the parent only orchestrates.

```yaml
---
name: Simple Orchestrator
description: "Coordinates research and implementation subagents"
disable-model-invocation: true
agents:
  - Researcher Subagent
  - Phase Implementor
---

```

### 3. Reference Subagents with Glob Paths

Use glob patterns in the parent body to ensure path resolution remains stable across directory restructuring.

```markdown
Run the researcher subagent at `.github/agents/**/researcher-subagent.agent.md`.

```

### 4. Invoke with runSubagent

Call the subagent with explicit inputs and output destinations.

```yaml
- name: Conduct conventions discovery
  runSubagent:
    agent: researcher-subagent
    path: .github/agents/**/researcher-subagent.agent.md
    inputs:
      scope: "workspace conventions"
      output: ".copilot-tracking/research/{{date}}/conventions.md"

```

### 5. Collect and Consume Output

After the subagent finishes, the parent reads the generated artifact using the `read` tool and incorporates findings into subsequent phases.

```yaml
- name: Load research findings
  read:
    path: ".copilot-tracking/research/{{date}}/conventions.md"

```

### 6. Parallelize Independent Subagents

When subagents have no inter-dependencies, launch them simultaneously to reduce total execution time. The parent waits for all completions before aggregating results and proceeding to the next phase.

## Common Subagent Delegation Patterns

The HVE Core ecosystem relies on several canonical patterns implemented in the [RPI Agent](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/rpi-agent.agent.md) and supporting subagents.

| Pattern | Parent Agent | Subagent(s) | Goal |
|---------|--------------|-------------|------|
| **Research delegation** | RPI Agent, PR reviewer | `researcher-subagent` | Gather codebase conventions, external documentation, or user-provided topics. |
| **Phase execution** | RPI Agent (Phase 3) | `phase-implementor` | Execute concrete implementation steps defined in the planning phase. |
| **Validation** | RPI Agent (Phase 4) | `plan-validator`, `implementation-validator` | Verify implementation matches the plan and quality standards. |
| **Prompt updating** | Prompt-builder agent | `prompt-updater`, `prompt-tester` | Refresh generated prompt files after code changes. |

All patterns follow the same declarative flow: **declare** dependencies in front-matter, **invoke** via `runSubagent`, **read** output artifacts, and **decide** the next step.

## Best Practices for Subagent Delegation

Follow these guidelines to maintain clean, maintainable subagent hierarchies.

- **Prevent nested delegation** – Never allow a subagent to call another subagent; only the parent coordinates delegation to avoid circular dependencies and complexity.
- **Maintain single responsibility** – Split subagents that handle both research and validation into separate, focused units.
- **Version control together** – Store subagents under the same `.github/agents/` tree as their parents to ensure version consistency across the collection.
- **Document contracts explicitly** – Define inputs, outputs, and response formats in the subagent's Markdown body to help parent authors understand what files to read and what parameters to supply.

## Summary

- **Subagent delegation patterns** in HVE Core use parent agents to declare dependencies via the `agents:` front-matter field and invoke subagents using `runSubagent` with glob paths.
- **Subagents** must set `user-invocable: false` and live under `<collection>/subagents/` to prevent direct UI access while allowing parent orchestration.
- **Parent orchestrators** should set `disable-model-invocation: true` when they only coordinate work, preventing unnecessary model calls.
- **Glob paths** like `.github/agents/**/researcher-subagent.agent.md` ensure subagent resolution remains robust against directory restructuring.
- **Parallel execution** of independent subagents reduces workflow latency, while the parent aggregates outputs before proceeding.

## Frequently Asked Questions

### What is the difference between `runSubagent` and `task` for invoking subagents?

Both `runSubagent` and `task` tools initiate subagent execution, but `runSubagent` is the primary mechanism for structured delegation with explicit input/output contracts. According to the RPI Agent source, `runSubagent` accepts an `agent` name, `path` (glob), and `inputs` object, making it ideal for declarative workflows where the parent expects specific artifact outputs.

### Can subagents invoke other subagents in HVE Core?

No, subagents should never invoke other subagents. Only the parent agent coordinates delegation to prevent circular dependencies and maintain clear separation of concerns. As documented in the [agents customization guide](https://github.com/microsoft/hve-core/blob/main/docs/customization/agents.md), the parent maintains sole responsibility for workflow orchestration while subagents remain leaf nodes focused on single responsibilities.

### How do I pass data between a parent agent and its subagent?

Pass data through the `inputs` field in the `runSubagent` configuration, where the parent supplies parameters like file paths or search scopes. The subagent then writes results to the specified output location (typically under `.copilot-tracking/`), and the parent uses the `read` tool to consume these artifacts in subsequent phases.

### Why must subagent paths use glob patterns instead of relative paths?

Glob patterns like `.github/agents/**/researcher-subagent.agent.md` allow the HVE Core engine to resolve subagents regardless of directory depth or collection layout changes. This abstraction ensures that refactoring the directory structure under `.github/agents/` does not break existing parent agent invocations, providing stability across repository versions and submodule inclusions.