You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: instructions/agents.instructions.md
+170Lines changed: 170 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,6 +76,176 @@ infer: true
76
76
- Only supported for organization/enterprise level agents
77
77
- See "MCP Server Configuration" section below
78
78
79
+
#### **handoffs** (OPTIONAL, VS Code only)
80
+
- Enable guided sequential workflows that transition between agents with suggested next steps
81
+
- List of handoff configurations, each specifying a target agent and optional prompt
82
+
- After a chat response completes, handoff buttons appear allowing users to move to the next agent
83
+
- Only supported in VS Code (version 1.106+)
84
+
- See "Handoffs Configuration" section below for details
85
+
86
+
## Handoffs Configuration
87
+
88
+
Handoffs enable you to create guided sequential workflows that transition seamlessly between custom agents. This is useful for orchestrating multi-step development workflows where users can review and approve each step before moving to the next one.
89
+
90
+
### Common Handoff Patterns
91
+
92
+
-**Planning → Implementation**: Generate a plan in a planning agent, then hand off to an implementation agent to start coding
93
+
-**Implementation → Review**: Complete implementation, then switch to a code review agent to check for quality and security issues
94
+
-**Write Failing Tests → Write Passing Tests**: Generate failing tests, then hand off to implement the code that makes those tests pass
95
+
-**Research → Documentation**: Research a topic, then transition to a documentation agent to write guides
96
+
97
+
### Handoff Frontmatter Structure
98
+
99
+
Define handoffs in the agent file's YAML frontmatter using the `handoffs` field:
100
+
101
+
```yaml
102
+
---
103
+
description: 'Brief description of the agent'
104
+
name: 'Agent Name'
105
+
tools: ['search', 'read']
106
+
handoffs:
107
+
- label: Start Implementation
108
+
agent: implementation
109
+
prompt: 'Now implement the plan outlined above.'
110
+
send: false
111
+
- label: Code Review
112
+
agent: code-review
113
+
prompt: 'Please review the implementation for quality and security issues.'
114
+
send: false
115
+
---
116
+
```
117
+
118
+
### Handoff Properties
119
+
120
+
Each handoff in the list must include the following properties:
121
+
122
+
| Property | Type | Required | Description |
123
+
|----------|------|----------|-------------|
124
+
|`label`| string | Yes | The display text shown on the handoff button in the chat interface |
125
+
|`agent`| string | Yes | The target agent identifier to switch to (name or filename without `.agent.md`) |
126
+
|`prompt`| string | No | The prompt text to pre-fill in the target agent's chat input |
127
+
|`send`| boolean | No | If `true`, automatically submits the prompt to the target agent (default: `false`) |
128
+
129
+
### Handoff Behavior
130
+
131
+
-**Button Display**: Handoff buttons appear as interactive suggestions after a chat response completes
132
+
-**Context Preservation**: When users select a handoff button, they switch to the target agent with conversation context maintained
133
+
-**Pre-filled Prompt**: If a `prompt` is specified, it appears pre-filled in the target agent's chat input
134
+
-**Manual vs Auto**: When `send: false`, users must review and manually send the pre-filled prompt; when `send: true`, the prompt is automatically submitted
135
+
136
+
### Handoff Configuration Guidelines
137
+
138
+
#### When to Use Handoffs
139
+
140
+
-**Multi-step workflows**: Breaking down complex tasks across specialized agents
141
+
-**Quality gates**: Ensuring review steps between implementation phases
142
+
-**Guided processes**: Directing users through a structured development process
143
+
-**Skill transitions**: Moving from planning/design to implementation/testing specialists
144
+
145
+
#### Best Practices
146
+
147
+
-**Clear Labels**: Use action-oriented labels that clearly indicate the next step
148
+
- ✅ Good: "Start Implementation", "Review for Security", "Write Tests"
149
+
- ❌ Avoid: "Next", "Go to agent", "Do something"
150
+
151
+
-**Relevant Prompts**: Provide context-aware prompts that reference the completed work
152
+
- ✅ Good: `'Now implement the plan outlined above.'`
153
+
- ❌ Avoid: Generic prompts without context
154
+
155
+
-**Selective Use**: Don't create handoffs to every possible agent; focus on logical workflow transitions
156
+
- Limit to 2-3 most relevant next steps per agent
157
+
- Only add handoffs for agents that naturally follow in the workflow
158
+
159
+
-**Agent Dependencies**: Ensure target agents exist before creating handoffs
160
+
- Handoffs to non-existent agents will be silently ignored
161
+
- Test handoffs to verify they work as expected
162
+
163
+
-**Prompt Content**: Keep prompts concise and actionable
164
+
- Refer to work from the current agent without duplicating content
165
+
- Provide any necessary context the target agent might need
166
+
167
+
### Example: Complete Workflow
168
+
169
+
Here's an example of three agents with handoffs creating a complete workflow:
170
+
171
+
**Planning Agent** (`planner.agent.md`):
172
+
```yaml
173
+
---
174
+
description: 'Generate an implementation plan for new features or refactoring'
0 commit comments