/agentic-workflow-guide

Handoffs Guide

Guided sequential workflows with human-in-the-loop control between agents.

Table of Contents

• What are Handoffs? - Purpose and concept
• When to Use - Effective scenarios
• Configuration - YAML properties and examples
• Workflow Examples - Common patterns
• Handoffs vs agent - Comparison and selection
• Best Practices - Tips for effective handoffs
• Troubleshooting - Common issues

VS Code Version: Handoffs are available in VS Code 1.106+ (January 2026)

What are Handoffs?

Handoffs enable guided sequential workflows that transition between agents with suggested next steps. After a chat response completes, handoff buttons appear that let users move to the next agent with relevant context and a pre-filled prompt.

Key Characteristics

Visual Flow

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Plan Agent    │     │ Implementation   │     │  Review Agent   │
│                 │     │     Agent        │     │                 │
│  📋 Generate    │ ──► │  🔨 Execute      │ ──► │  ✅ Verify      │
│     plan        │     │     code changes │     │     quality     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
   [Start Implementation]  [Start Review]          [Done]
        button                button

When to Use

✅ Effective Scenarios

❌ When NOT to Use

Configuration

YAML Syntax

---
name: <agent-name>
description: <description>
tools: [...]
handoffs:
  - label: <button-text>
    agent: <target-agent-name>
    prompt: <pre-filled-prompt>
    send: <true|false>
---

Properties

Complete Example

---
name: Planner
description: Generate implementation plans for features
tools: ['textSearch', 'fetch', 'readFile']
handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: |
      Implement the plan outlined above.
      Follow the step-by-step instructions.
    send: false
  - label: Request Review
    agent: reviewer
    prompt: Review the plan for completeness.
    send: false
---

# Planner Agent

## Role

Generate detailed implementation plans for new features.

## Goals

- Analyze requirements
- Break down into actionable steps
- Define acceptance criteria

## Done Criteria

- [ ] Plan document created
- [ ] Steps are specific and actionable
- [ ] Acceptance criteria defined

## Workflow

1. Analyze the feature request
2. Research existing codebase patterns
3. Create step-by-step implementation plan
4. Define test cases and acceptance criteria

Workflow Examples

Example 1: TDD Workflow

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Test Writer    │ ──► │   Implementer    │ ──► │    Reviewer     │
│                 │     │                  │     │                 │
│ Write failing   │     │ Make tests pass  │     │ Check quality   │
│ tests first     │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘

test-writer.agent.md:

---
name: test-writer
description: Write failing tests first (TDD)
tools: ["readFile", "edit/editFiles", "execute/runInTerminal"]
handoffs:
  - label: Make Tests Pass
    agent: implementer
    prompt: Implement the code to make the failing tests pass.
    send: false
---

implementer.agent.md:

---
name: implementer
description: Implement code to pass tests
tools: ["readFile", "edit/editFiles", "execute/runInTerminal"]
handoffs:
  - label: Request Code Review
    agent: reviewer
    prompt: Review the implementation for quality and best practices.
    send: false
---

Example 2: Research → Document

---
name: researcher
description: Research a topic thoroughly
tools: ["web/fetch", "textSearch", "readFile"]
handoffs:
  - label: Write Document
    agent: writer
    prompt: |
      Based on the research above, write a comprehensive document.
      Include all key findings and recommendations.
    send: false
---

Example 3: Multi-Path Handoffs

Single agent with multiple possible next steps:

---
name: analyzer
description: Analyze issues and suggest next steps
tools: ["readFile", "textSearch", "problems"]
handoffs:
  - label: Fix Issues
    agent: fixer
    prompt: Fix the issues identified above.
    send: false
  - label: Create PR
    agent: pr-creator
    prompt: Create a PR with the analysis summary.
    send: false
  - label: Get More Info
    agent: researcher
    prompt: Research the root cause of these issues.
    send: false
---

Handoffs vs agent

Decision Matrix

Best Practices

1. Clear Prompt Context

❌ Bad:

handoffs:
  - label: Next
    agent: implementer
    prompt: Continue.

✅ Good:

handoffs:
  - label: Start Implementation
    agent: implementer
    prompt: |
      Implement the plan outlined above.
      Follow these steps:
      1. Create the new file structure
      2. Implement core logic
      3. Add tests for each function

2. Descriptive Labels

❌ Bad: label: Next, label: Go

✅ Good: label: Start Implementation, label: Request Code Review

3. Use send: false by Default

Let users review and modify prompts before submitting. Use send: true only for well-tested, predictable workflows.

4. Define Clear Phase Boundaries

Each agent should have distinct responsibility:

• Planner: Creates plan only, no implementation
• Implementer: Executes plan, no review
• Reviewer: Reviews only, no fixing

5. Include Context References

Reference what was done in current phase:

prompt: |
  Review the implementation above.
  Focus on:
  - Adherence to the original plan
  - Code quality and best practices
  - Test coverage

Troubleshooting

Handoff Button Not Appearing

Causes:

1. handoffs not in YAML frontmatter
2. Target agent file doesn't exist
3. VS Code version < 1.106

Solution:

# Check VS Code version
code --version

# Verify target agent exists
ls .github/agents/implementer.agent.md

Wrong Agent Invoked

Cause: Agent name mismatch

Solution: Ensure agent: matches the target agent's filename (without .agent.md):

File: .github/agents/implementer.agent.md
Agent name in handoffs: agent: implementer  ✅

Prompt Too Long

Cause: Large prompt causes UI issues

Solution: Keep prompts concise; reference previous output instead of duplicating:

prompt: |
  Implement based on the plan above.
  See the requirements in the previous response.

References

• Custom Agents in VS Code
• Custom Agents Configuration - GitHub Docs
• agent Guide (legacy: runSubagent) - Alternative for context isolation
• Workflow Patterns Overview - Pattern selection guide

Context-Based Handoff (No agent tool)

Not all agent-to-agent communication uses agent. Some patterns use chat context for data passing.

When to Use Context-Based Handoff

Implementation Pattern

## Router Agent (Decision Maker)

- Makes routing decision
- Outputs RouterDecision JSON to chat context
- Does NOT use agent

## Orchestrator Agent (Executor)

- Receives RouterDecision from chat context (NOT as agent input)
- Uses agent for actual worker delegation
- Logs decision to .logs/ for traceability

RouterDecision JSON Example

{
  "flow": "full_ir",
  "normalized_question": "...",
  "manifest": { "applied": true, "name": "..." },
  "decision_reason": "...",
  "timestamp": "ISO8601"
}

Key Distinction