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: fern/assistants/call-recording.mdx
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -265,6 +265,8 @@ Control where each artifact type is stored:
265
265
266
266
### Dynamic Artifact Control
267
267
268
+
When handing off between assistants in a Squad, you may choose to change the local context for each assistant via the `contextEngineeringPlan`. By default, only the final context will be used in the artifact and analysis (Structured outputs and success evaluation). To include the full message history across all assistants in the call, set [`artifactPlan.fullMessageHistoryEnabled`](/api-reference/squads/create#request.body.membersOverrides.artifactPlan.fullMessageHistoryEnabled) to true.
269
+
268
270
In squads with multiple assistants, artifact generation (recording, logging, transcripts) can be controlled per assistant. When assistants are swapped or transferred during a call:
269
271
270
272
-**Recording**: Pauses when `recordingEnabled: false` assistant is active, resumes when `recordingEnabled: true` assistant takes over
@@ -4,55 +4,179 @@ subtitle: Use Squads to handle complex workflows and tasks.
4
4
slug: squads
5
5
---
6
6
7
-
Sometimes, complex workflows are easier to manage with multiple assistants.
8
-
You can think of each assistant in a Squad as a leg of a conversation tree.
9
-
For example, you might have one assistant for lead qualification, which transfers to another for booking an appointment if they’re qualified.
7
+
Squads let you break complex workflows into multiple specialized assistants that hand off to each other during a conversation. Each assistant in a Squad handles a specific part of your workflow; for example, one assistant for lead qualification that transfers to another for appointment booking.
10
8
11
-
Prior to Squads you would put all functionality in one assistant, but Squads were added to break up the complexity of larger prompts into smaller specialized assistants with specific tools and fewer goals.
12
-
Squads enable calls to transfer assistants mid-conversation, while maintaining full conversation context.
9
+
**Why use Squads?** Large, all-in-one assistants with lengthy prompts and extensive context lead to:
10
+
-**Higher hallucination rates** - Models lose focus with too many and potentially conflicting instructions
11
+
-**Increased costs** - Longer prompts consume more tokens per request
12
+
-**Greater latency** - Processing large contexts takes more time and will increase the latency of your assistant.
13
+
14
+
Squads solve this by splitting complex prompts into focused assistants with specific tools and clear goals, while maintaining full conversation context across handoffs.
13
15
14
16
<Info>
15
17
View all configurable properties in the [API Reference](/api-reference/squads/create-squad).
16
18
</Info>
17
19
18
20
## Usage
19
21
20
-
To use Squads, you can create a `squad` when starting a call and specify `members` as a list of assistants and destinations.
21
-
The first member is the assistant that will start the call, and assistants can be either persistent or transient.
22
+
To use Squads, you can create a `squad` when starting a call and specify `members` as a list of assistants and destinations. Assistants can be either persistent or transient.
23
+
24
+
<Info>
25
+
The first member is the assistant that will start the call.
26
+
</Info>
27
+
28
+
We recommend using [Handoff Tools](/tools/handoff) to specify which destinations the current assistant can handoff too, and when to handoff to each assistant. Each assistant within the squad can use its saved handoff tools as well as handoff tools from Assistant Overrides (see below).
22
29
23
-
Each assistant should be assigned the relevant assistant transfer destinations.
24
-
Transfers are specified by assistant name and are used when the model recognizes a specific trigger.
"message": "Please hold on while I transfer you to our appointment booking assistant.",
36
-
"description": "Transfer the user to the appointment booking assistant after they say their name."
37
-
}],
38
37
},
39
38
{
40
39
"assistant": {
41
40
"name": "Appointment Booking",
42
-
...
41
+
"model": {
42
+
"provider": "openai",
43
+
"model": "gpt-4o",
44
+
"toolIds": ["handoff-tool-id"],
45
+
"tools": [
46
+
{
47
+
"type": "handoff",
48
+
"destinations": [
49
+
{
50
+
"type": "assistant",
51
+
"assistantId": "assistant-123",
52
+
"description": "Call this tool when the customer wants to talk about pricing"
53
+
}
54
+
]
55
+
}
56
+
]
57
+
},
43
58
},
44
59
}
45
60
]
46
61
}
47
62
}
48
63
```
49
64
65
+
## Overrides
66
+
67
+
### Assistant Overrides
68
+
To override the configuration of a saved assistant without modifying the underlying assistant, use the `assistantsOverrides` to alter individual assistants. For example, if you have assistants in a squad with different voices, you can use `assistantOverrides` to make sure all of the assistants are using the same voice without changing the assistant (in case it's being used in another squad).
69
+
70
+
```json
71
+
{
72
+
"squad": {
73
+
"members": [
74
+
{
75
+
"assistant": {
76
+
"name": "Appointment Booking",
77
+
"voice": {
78
+
"provider": "vapi",
79
+
"voiceId": "Elliot",
80
+
},
81
+
},
82
+
},
83
+
{
84
+
"assistantId": "saved-assistant-id",
85
+
"assistantOverrides": {
86
+
"voice": {
87
+
"provider": "vapi",
88
+
"voiceId": "Elliot",
89
+
},
90
+
}
91
+
},
92
+
]
93
+
}
94
+
}
95
+
```
96
+
97
+
You may also define inline tools via assistant overrides through the `model` object (using `tools:append`), so that the assistant will only handoff if it is a part of this squad.
98
+
```json
99
+
{
100
+
"squad": {
101
+
"members": [
102
+
{
103
+
"assistant": {
104
+
"name": "Appointment Booking",
105
+
"voice": {
106
+
"provider": "vapi",
107
+
"voiceId": "Elliot",
108
+
},
109
+
},
110
+
},
111
+
{
112
+
"assistantId": "saved-assistant-id",
113
+
"assistantOverrides": {
114
+
"model": {
115
+
"provider": "openai",
116
+
"model": "gpt-4o",
117
+
"tools:append": [
118
+
{
119
+
"type": "handoff",
120
+
"destinations": [
121
+
{
122
+
"type": "assistant",
123
+
"assistantId": "assistant-123",
124
+
"description": "Call this tool when the customer wants to talk about pricing"
125
+
}
126
+
]
127
+
}
128
+
]
129
+
},
130
+
}
131
+
},
132
+
]
133
+
}
134
+
}
135
+
```
136
+
137
+
138
+
### Member Overrides
139
+
To override the configuration of _all_ assistants in a squad without modifying the underlying assistants, use the `memberOverrides`.
140
+
<Info>
141
+
Note: This is `squadOverrides` for the [`assistant-request`](api-reference/webhooks/server-message#response.body.messageResponse.AssistantRequest.squadOverrides) webhook response.
142
+
</Info>
143
+
144
+
```json
145
+
{
146
+
"squad": {
147
+
"members": [
148
+
{
149
+
"assistant": {
150
+
"name": "Appointment Booking",
151
+
"voice": {
152
+
"provider": "vapi",
153
+
"voiceId": "Elliot",
154
+
},
155
+
},
156
+
},
157
+
{
158
+
"assistantId": "saved-assistant-id",
159
+
},
160
+
],
161
+
"memberOverrides": {
162
+
"voice": {
163
+
"provider": "vapi",
164
+
"voiceId": "Elliot",
165
+
},
166
+
}
167
+
}
168
+
}
169
+
```
50
170
51
171
## Best Practices
52
172
53
-
The following are some best practices for using Squads to reduce errors:
173
+
**Keep assistants focused** - Each assistant should have a single, well-defined responsibility with 1-3 goals maximum. Assign only the tools needed for that specific task.
174
+
175
+
**Minimize squad size** - Try to reduce the number of squad members. Only split into separate assistants when there's a clear functional boundary (lead qualification → sales → booking).
176
+
177
+
**Define clear handoff conditions** - Write specific handoff descriptions that state exact trigger conditions and what information to collect before transferring. Make sure to specify this in the assistant's prompt and/or tool description.
178
+
179
+
**Engineer context carefully** - Use [context engineering](/tools/handoff#context-engineering) to control what conversation history is passed between assistants. As the context grows throughout the call, you may want to limit message history to reduce tokens, improve performance, and prevent context poisoning. Utilize [variable extraction](/tools/handoff#variable-extraction) to save information and generate summaries during a handoff to pass to other assistants.
180
+
54
181
55
-
- Group assistants by closely related tasks
56
-
- Create as few assistants as possible to reduce complexity
57
-
- Make sure descriptions for transfers are clear and concise
Copy file name to clipboardExpand all lines: fern/tools/handoff.mdx
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -510,6 +510,7 @@ Override the default function definition for more control. You can overwrite the
510
510
3.**Model Optimization**: Use multiple tools for OpenAI, single tool for Anthropic
511
511
4.**Variable Extraction**: Extract key data before handoff to maintain context
512
512
5.**Testing**: Test handoff scenarios thoroughly, including edge cases
513
+
6.**Monitoring and Analysis**: Enable [`artifactPlan.fullMessageHistoryEnabled`](api-reference/assistants/create#response.body.artifactPlan.fullMessageHistoryEnabled) to capture the complete message history across all handoffs in your artifacts. See [squad artifact behavior](/assistants/call-recording#squad-and-transfer-behavior) for details.
0 commit comments