Understanding agents, invocation, handoffs, and subagents

Understand what custom agents are, how they override the model’s identity, techniques for invocation and handoff workflows, and how subagent delegation enables scalable multi-agent orchestrations.

Understanding agents, invocation, handoffs, and subagents

Custom agents are the most powerful customization mechanism in GitHub Copilot’s stack. While prompt files provide reusable commands and instruction files set persistent rules, agents do something fundamentally different — they change who the model is. When you switch to a custom agent, you’re not just giving the model new instructions. You’re replacing its identity, restricting its tools, and defining how it should approach every subsequent interaction.

This article explains agents conceptually: what they are, why they exist as a separate mechanism, how invocation and handoff patterns work, and how subagent delegation enables complex multi-step workflows. For the practical how-to of writing agent files, see How to structure content for Copilot agent files. For designing orchestration prompts that coordinate agents, see How to design orchestrator prompts.

Table of contents

• 🎯 What agents are — and what they’re not
• 🏗️ How agents override the identity layer
• 📋 .agent.md vs AGENTS.md: two different worlds
• 🔗 Invocation techniques
• 🤝 Handoffs: multi-agent workflows
• 🔀 Subagent delegation
• 🎭 The orchestrator pattern
• ⚠️ Boundaries and limitations
• 🎯 Conclusion
• 📚 References

---

🎯 What agents are — and what they’re not

A custom agent is a specialized AI persona stored as an .agent.md file. Each agent defines:

• A specific role or expertise — security reviewer, planner, implementer, documentation writer
• Restricted tool access — what the agent can and can’t do
• Specialized instructions — how the agent should approach tasks
• Optional model preference — which LLM to use for this agent
• Optional handoffs — transitions to other agents

Agents vs. other customization types

The key distinction is persistence and identity:

Mechanism	What it does	Persistence	Identity change
Prompt files	Injects a task into the user prompt	One request only	No — the model stays “itself”
Instruction files	Injects rules into the system prompt	Every matching request	No — adds rules without changing identity
Agents	Overrides the system prompt’s identity layer	Every request until switched	Yes — the model becomes the agent

When you invoke a prompt file, the model is still “GitHub Copilot, a helpful AI programming assistant” — it just has an extra task to complete. When you switch to a custom agent, the model becomes that agent. It adopts the agent’s persona, follows its workflow, and restricts itself to the agent’s declared tools.

Why agents exist

Agents exist because some tasks require more than new instructions — they require a different mindset:

• A planning agent should think before acting, research thoroughly, and produce a structured plan. It shouldn’t impulsively edit files.
• An implementation agent should focus on execution — editing files, running tests, fixing errors. It shouldn’t spend time philosophizing about architecture.
• A security review agent should be skeptical, thorough, and restrictive. It should look for vulnerabilities, not help write features.

Instruction files can suggest these behaviors, but they can’t enforce them. An instruction that says “don’t edit files” is guidance the model might ignore under pressure. An agent that only has codebase and problems tools literally can’t edit files — the capability isn’t available.

---

🏗️ How agents override the identity layer

Recall the prompt assembly architecture: the system prompt is built in six layers, with the agent definition at layer 6 (the final layer). When a custom agent is active, its body content replaces the default identity:

Without custom agent:                 With custom agent:
┌─────────────────────────┐          ┌──────────────────────────┐
│ Layer 1: Core identity  │          │ Layer 1: Core identity   │
│ Layer 2: Model rules    │          │ Layer 2: Model rules     │
│ Layer 3: Tool schema    │          │ Layer 3: Tool schema     │
│ Layer 4: Output format  │          │ Layer 4: Output format   │
│ Layer 5: Instructions   │          │ Layer 5: Instructions    │
│ Layer 6: (empty)        │          │ Layer 6: AGENT PERSONA   │
└─────────────────────────┘          │   "You are a security    │
                                     │    auditor. Analyze..."  │
                                     └──────────────────────────┘

The agent body acts as a full behavioral override. It doesn’t just add information — it tells the model who it is and how it should operate. This is why well-designed agents feel like working with a specialist rather than a general-purpose assistant.

Tool restriction as capability control

The agent’s tools: field in YAML frontmatter controls what runtime tools become available. This is capability control, not just guidance:

Agent role	Typical tools	What this prevents
Planning/research agent	codebase, problems, changes	Can’t edit files, can’t run commands
Implementation agent	codebase, editor, filesystem, terminal	Full access (appropriate for implementation)
Review agent	codebase, problems, usages	Can’t modify code, can only analyze
Documentation agent	codebase, editor	Can read and write, but can’t execute

---

📋 .agent.md vs AGENTS.md: two different worlds

A common source of confusion is the difference between .agent.md files and AGENTS.md files. Despite similar names, they serve fundamentally different purposes:

Aspect	.agent.md files	AGENTS.md files
Purpose	Define VS Code chat personas	Provide instructions to the GitHub Copilot Coding Agent
Location	.github/agents/*.agent.md	Anywhere in repository (commonly root or per-folder)
Platform	VS Code only (v1.106+)	GitHub.com, VS Code, Visual Studio
Execution	Interactive — runs locally in IDE	Asynchronous — runs on GitHub, creates PRs
Tool control	✅ Full control via tools field	❌ No tool configuration
Handoffs	✅ Workflow transitions between agents	❌ Not supported
Model selection	✅ Via model field	❌ Platform-determined

When to use which

• .agent.md — for interactive development workflows in VS Code: planning, reviewing, implementing, documenting
• AGENTS.md — for the GitHub Copilot Coding Agent that works on issues asynchronously and creates pull requests
• Alternative filenames: CLAUDE.md, GEMINI.md work as model-specific alternatives to AGENTS.md

---

🔗 Invocation techniques

Agents can be invoked through three distinct mechanisms, each suited to different situations.

Direct selection (user-initiated)

The simplest invocation: the user selects an agent from the agent picker in Copilot Chat. This switches the active persona for all subsequent messages until the user switches again.

When to use: When the user intentionally wants to work with a specialist — “I need to plan this feature” (select the planner agent).

The agents property (subagent routing)

An agent’s YAML can declare which other agents it’s allowed to invoke as subagents:

---
name: orchestrator
agents:
  - researcher
  - implementer
  - reviewer
tools: ['agent', 'codebase', 'editor']
---

The agents property accepts:

• An array of agent names — only these agents are available as subagents
• * — all agents are available
• [] (empty array) — no subagent access

When to use: When building orchestrator agents that delegate to specialist agents. The agents property lets you control which specialists are available, preventing uncontrolled delegation chains.

The runSubagent tool (programmatic delegation)

The model itself can decide to spawn a subagent at runtime using the runSubagent tool. This is the mechanism behind the agents property — when an agent has tools: ['agent'], the model gains access to runSubagent and can invoke it when it determines delegation would help.

When to use: You don’t call runSubagent directly. It’s available to the model when you include agent in the agent’s tools list. The model decides when delegation is beneficial based on its instructions and the current task.

---

🤝 Handoffs: multi-agent workflows

Handoffs enable orchestrating sequential workflows between agents. Unlike subagent delegation (where one agent spawns another in an isolated context), handoffs transfer control — the conversation moves from one agent to another, with the user reviewing and approving each transition.

How handoffs work

A handoff is declared in the agent’s YAML frontmatter:

---
name: architect
description: Plans implementation approach
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: "Implement the plan outlined above."
    send: false  # false = user reviews before sending
---

When the architect agent completes its task, the user sees a “Start Implementation” button. Selecting it starts a new conversation with the implementer agent, pre-filled with the handoff prompt.

Handoff properties

Property	Description	Required
label	Button text shown to the user	Yes
agent	Target agent name	Yes
prompt	Message to pre-fill for the target agent	No
send	Auto-send (true) or let user review (false)	No (default: true)

Handoffs vs. subagents

The choice between handoffs and subagents depends on workflow visibility and control:

Aspect	Handoffs	Subagents
Control flow	Sequential — user approves each step	Delegated — main agent manages internally
User visibility	High — button prompts at each transition	Low — collapsed tool call
Context	New conversation (fresh context)	Isolated child context
Use case	Multi-phase workflows (plan → implement → review)	Focused subtasks within a single workflow
Communication	Explicit user transitions	Internal agent-to-agent
Orchestration	User-driven	Agent-driven

Common handoff patterns

1. Linear pipeline (plan → implement → review):

Architect → [Start Implementation] → Implementer → [Review Code] → Reviewer

2. Branching decision:

Triage Agent → [Quick Fix] → Fixer Agent
             → [Deep Analysis] → Analyst Agent
             → [Escalate] → Senior Reviewer Agent

3. Iterative loop:

Implementer → [Run Tests] → Tester → [Fix Issues] → Implementer

---

🔀 Subagent delegation

A subagent is an independent AI agent that performs focused work in its own isolated context window and returns a summary to the main agent. The main agent stays in control, receiving condensed results without the noise of the subagent’s intermediate processing.

Why isolation matters

Each subagent gets a fresh context window. It doesn’t inherit the main agent’s conversation history, tool call results, or accumulated context. This isolation provides three benefits:

1. Focus. The subagent works on exactly one task without being distracted by other context.
2. Scalability. The main agent’s context window stays lean — it gets a summary, not the full transcript.
3. Parallelism. Independent subtasks can run concurrently in separate context windows.

How subagent execution works

Main Agent (orchestrator)
  │
  ├─ Sends task prompt ──→ Subagent A
  │                         ├─ Gets its own context window
  │                         ├─ Runs tools autonomously
  │                         └─ Returns summary ──→ Main Agent
  │
  ├─ Sends task prompt ──→ Subagent B (can run in parallel)
  │                         ├─ Gets its own context window
  │                         ├─ Runs tools autonomously
  │                         └─ Returns summary ──→ Main Agent
  │
  └─ Incorporates results → Continues with next step

Key characteristics

Aspect	Behavior
Context isolation	Each subagent starts with a clean context window — no inherited conversation history
Synchronous execution	The main agent waits for subagent results before continuing
Parallel support	VS Code can spawn multiple subagents concurrently when tasks are independent
Tool inheritance	By default, subagents inherit the main session’s model and tools
Custom agent override	When using a custom agent as subagent, its tools, model, and instructions override defaults
Result format	Only the subagent’s final result returns — not intermediate tool calls

Subagents vs. new sessions

Subagents maintain a relationship with the parent agent — they do focused work and report back. Creating a new chat session creates an entirely separate conversation with no connection:

Aspect	Subagent	New session
Relationship	Child — reports results back	Independent — no connection
Context	Isolated but linked via task prompt	Completely separate
Coordination	Main agent synthesizes results	Manual user coordination
Use case	Delegating part of a larger task	Starting unrelated work

Controlling subagent visibility

Two agent properties control subagent behavior:

user-invokable: false — Hides the agent from the agent picker. Use this for agents that should only be invoked as subagents, never directly by users:

---
name: code-analyzer
user-invokable: false
tools: ['codebase', 'problems']
---

disable-model-invocation: true — Prevents the model from automatically invoking this agent as a subagent. The agent is only invoked when explicitly named in an agents array or by user selection:

---
name: dangerous-migrator
disable-model-invocation: true
tools: ['editor', 'terminal']
---

---

🎭 The orchestrator pattern

The orchestrator pattern combines agents, handoffs, and subagents into a coordinated system where a central coordinator decomposes complex tasks and delegates to specialists.

Conceptual architecture

┌─────────────────────────────────────────────┐
│            ORCHESTRATOR AGENT               │
│  ├── Receives user request                  │
│  ├── Decomposes into subtasks               │
│  ├── Delegates to specialists               │
│  ├── Synthesizes results                    │
│  └── Reports summary to user                │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐     │
│  │ Research │ │ Implement│ │ Review   │     │
│  │ Agent    │ │ Agent    │ │ Agent    │     │
│  └──────────┘ └──────────┘ └──────────┘     │
│                                             │
│  Each specialist:                           │
│  • Has its own context window               │
│  • Uses only its declared tools             │
│  • Returns a focused summary                │
└─────────────────────────────────────────────┘

Why orchestrators work

The orchestrator pattern mirrors how effective human teams work: a project manager decomposes a task, assigns specialists, and synthesizes their results. The AI equivalent provides:

• Separation of concerns — each agent focuses on what it does best
• Context management — the orchestrator’s context stays lean because subagent details are summarized
• Tool safety — research agents can’t accidentally edit files; implementation agents have clear write permissions
• Scalability — adding a new capability means adding a new specialist, not rewriting the orchestrator

When to use orchestration

Scenario	Orchestration worthwhile?
Simple code edit	No — use a single agent or inline chat
Feature implementation with research	Maybe — depends on complexity
Multi-step refactoring across files	Yes — separate analysis from implementation
Full project setup with testing	Yes — planning, scaffolding, testing are distinct concerns
Security audit with remediation	Yes — review and fix are different expertises

For practical guidance on designing orchestrator prompts, see How to design orchestrator prompts. For subagent implementation details, see How to design subagent orchestrations.

---

⚠️ Boundaries and limitations

Current limitations

• VS Code only. Custom agents (.agent.md) work in VS Code 1.106+. Visual Studio doesn’t support them for chat.
• Experimental subagent support. The agents property and custom agent subagent invocation are experimental and may change.
• No cross-agent memory. Agents don’t share state between sessions. Each session starts fresh.
• Handoff context loss. Handoffs start new conversations — the target agent doesn’t automatically get the full context of the previous agent’s work.

Best practices

• Design agents with the principle of least privilege. Give each agent only the tools it needs for its role.
• Use user-invokable: false for specialist subagents that shouldn’t appear in the agent picker.
• Keep agent instructions focused. A 200-line agent body is harder for the model to follow than a 50-line one.
• Test handoff workflows end-to-end. Verify that each transition provides enough context for the next agent to continue.

---

🎯 Conclusion

Agents are GitHub Copilot’s most powerful customization mechanism because they change the model’s identity, not just its instructions. The ecosystem provides three invocation patterns (direct selection, the agents property, and runSubagent), two workflow patterns (handoffs for user-controlled transitions, subagents for agent-controlled delegation), and the orchestrator pattern for coordinating complex multi-step tasks.

Key takeaways

• Agents override the identity layer of the system prompt — they change who the model is
• Tool restriction in agents provides true capability control, not just guidance
• .agent.md is for VS Code chat personas; AGENTS.md is for the async GitHub Coding Agent
• Handoffs transfer control with user approval — ideal for multi-phase workflows
• Subagents delegate with context isolation — ideal for focused subtasks within a larger workflow
• The orchestrator pattern combines these mechanisms for scalable, multi-agent systems

Next steps

• How to structure content for Copilot agent files — practical guide to writing .agent.md files
• How to design orchestrator prompts — designing the coordinator in orchestration patterns
• How to design subagent orchestrations — implementing delegation with runSubagent
• Understanding skills, hooks, and lifecycle automation — complementary mechanisms that extend agent capabilities

---

📚 References

VS Code Copilot Customization Overview [📘 Official] Microsoft’s comprehensive guide covering custom agents, their file format, tool configuration, and handoff workflows. The authoritative source for .agent.md specification.

VS Code Agent Mode Documentation [📘 Official] Documentation for Agent mode in VS Code — autonomous file editing, plan mode integration, and multi-step workflows.

How to write a great AGENTS.md [📗 Verified Community] Official GitHub blog post analyzing 2,500+ agent files. Covers the six core areas: commands, testing, project structure, code style, git workflow, and boundaries.

VS Code v1.106 Release Notes [📘 Official] November 2024 release that stabilized custom agents, introduced handoff workflows, and added the target field.

VS Code v1.107 Release Notes [📘 Official] December 2024 release introducing Agent HQ, background agents, work tree isolation, and enhanced agent session management.

---