Skip to content

Publish GPT-Live reasoner skills and squad migration guides #1276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dev-seth-vapi merged 1 commit into from
Oct 1, 2026
Merged

Publish GPT-Live reasoner skills and squad migration guides #1276

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions fern/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,8 @@ navigation:
path: gpt-live/design.mdx
- page: Build with tools
path: gpt-live/tools.mdx
- page: Reasoner skills
path: gpt-live/skills.mdx
- page: Migrate to GPT-Live
path: gpt-live/migrate.mdx
- page: Test and improve
Expand Down
29 changes: 24 additions & 5 deletions fern/gpt-live/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
title: GPT-Live settings and compatibility
subtitle: Supported features, fields, voices, hooks, call connections, and live controls
description: Reference for GPT-Live in Vapi. Feature compatibility, speaker and reasoner fields, personality packs, voices with previews, greetings, idle-message hooks, call connections, and live call control.
description: Reference for GPT-Live in Vapi. Feature compatibility, speaker and reasoner fields, reasoner skills, personality packs, voices with previews, greetings, idle-message hooks, call connections, and live call control.
slug: gpt-live/configuration
---

This page is the reference for GPT-Live's settings and supported features. For how to use them in a conversation, start with [Design conversations](/gpt-live/design).

**Jump to:** [Compatibility](#compatibility) · [Model settings](#model-settings) · [Personality](#personality-and-language) · [Voices](#voices) · [Greetings](#greetings-and-duration) · [Idle messages](#idle-messages) · [Calls](#connect-a-call) · [Live control](#live-call-control)
**Jump to:** [Compatibility](#compatibility) · [Model settings](#model-settings) · [Skills](#reasoner-skills) · [Personality](#personality-and-language) · [Voices](#voices) · [Greetings](#greetings-and-duration) · [Idle messages](#idle-messages) · [Calls](#connect-a-call) · [Live control](#live-call-control)

## Compatibility

Expand Down Expand Up @@ -56,6 +56,7 @@ Give tools unique names. Classic tool messages, such as request-start messages,
| Feature | Support |
| --- | --- |
| Squads and assistant handoffs | Not supported. See [Migrate to GPT-Live](/gpt-live/migrate#from-a-squad) |
| Reasoner skills | Supported. See [Reasoner skills](/gpt-live/skills) |
| Knowledge bases | Not available to the reasoner. Use a retrieval tool |
| Exact or prerecorded speech | Not supported. All speech, including greetings and idle check-ins, is generated |
| Audio URL greetings, generated first-message mode | Not supported |
Expand Down Expand Up @@ -95,17 +96,35 @@ These fields belong to the assistant object. See [Create Assistant](/api-referen
| `model.reasoner.model` | `gpt-5.6-sol`, `gpt-5.6-terra`, or `gpt-5.6-luna`. Defaults to `gpt-5.6-terra` |
| `model.reasoner.reasoningEffort` | `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Defaults to `low`. Higher effort can increase response time |
| `model.reasoner.instructions` | Reasoner prompt. Omit to use Vapi's default |
| `model.tools` | Inline tool definitions available to the reasoner |
| `model.toolIds` | IDs of saved tools |
| `model.reasoner.skills` | Array of skills. See [Reasoner skills](#reasoner-skills) |
| `model.tools` | Inline base tool definitions, available whether or not a skill is loaded |
| `model.toolIds` | IDs of saved base tools |
| `voice.provider` | `openai` |
| `voice.voiceId` | One of the [22 supported voices](#voices) |

## Prompt defaults and overrides

- Explicit speaker instructions take precedence over `model.systemPrompt` and system messages in `model.messages`. If you omit the speaker instructions, Vapi uses that classic configuration.
- Omitting reasoner instructions uses Vapi's default reasoner prompt. Custom instructions replace that prompt entirely. Vapi doesn't append behavioral instructions to a custom prompt.
- Omitting reasoner instructions uses Vapi's default reasoner prompt. Custom instructions replace that prompt entirely. When skills are configured, Vapi adds skill-loading guidance and the content of loaded skills.
- An explicit empty string stays empty. Updating one prompt doesn't update the other.
- Personality packs append guidance to the speaker prompt.
- The speaker also receives the names and descriptions of any reasoner skills.

## Reasoner skills

Set `model.reasoner.skills` to an array of skills. See [Reasoner skills](/gpt-live/skills) for how to design them.

| Field | Behavior | Limit |
| --- | --- | --- |
| `name` | Unique within the assistant. Start with a lowercase letter; use lowercase letters, digits, hyphens, or underscores. The speaker and reasoner both see it | 64 characters |
| `description` | Tells the reasoner, and the speaker, when the skill applies | 1,024 characters |
| `content` | The full procedure. Only the reasoner sees it, once the skill is loaded | 32,000 characters |
| `tools` | Optional inline tool definitions, available only while the skill is loaded | 20 tools |
| `toolIds` | Optional IDs of saved tools, available only while the skill is loaded | 20 tools |

An assistant can have up to 20 skills.

Skills are stored with the assistant. Tools in `model.tools` and `model.toolIds` stay available whether or not a skill is loaded. Each delegation starts from the catalog and loads the skills it needs, and the reasoner can unload a skill when it finishes that work or changes tasks. A saved tool ID that doesn't exist can stop calls from starting.

## Personality and language

Expand Down
8 changes: 5 additions & 3 deletions fern/gpt-live/design.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ The speaker and reasoner see different things. You need this to predict how the
| --- | --- | --- |
| Live audio | Hears the caller and speaks continuously | Doesn't hear audio. Works from the conversation transcript |
| Conversation | Is part of it | Receives the transcript available when the request starts |
| Instructions | Speaker prompt, plus any personality packs | Reasoner prompt. The speaker prompt isn't copied over |
| Instructions | Speaker prompt, plus any personality packs | Reasoner prompt and any loaded skills. The speaker prompt isn't copied over |
| Tools | None. It asks the reasoner | Your tools. It can use its earlier work and tool results from the call |

Two consequences shape the rest of this page.
Expand Down Expand Up @@ -290,11 +290,13 @@ A detour can help the caller make the next decision:

If the answer is already known, as with an appointment's length in the [example prompt](#example-split-a-scheduling-prompt), the speaker can give it directly. If it needs a lookup, delegate it. Either way, return to the unfinished task with the caller's earlier details intact.

When an assistant covers several kinds of work, such as scheduling and service questions, [reasoner skills](/gpt-live/skills) let you keep each procedure and its tools separate behind the same conversation.

### Start with one assistant

GPT-Live keeps one voice for the whole call. Start with a clear task and the tools it needs. Put its procedure in the reasoner prompt and its delegation triggers in the speaker prompt. Expand the assistant's responsibilities after it handles that task well.
GPT-Live keeps one voice for the whole call. Needs that used to lead to a squad of assistants, like separate intake, scheduling, and information roles, can often be covered by one assistant with clear delegation triggers and a few skills. The caller hears one continuous conversation instead of handoffs.

Existing squads and assistant handoffs aren't supported with GPT-Live. See [Migrate to GPT-Live](/gpt-live/migrate) for moving a single assistant and the limits for squads.
Existing squads and assistant handoffs aren't supported with GPT-Live. See [Migrate to GPT-Live](/gpt-live/migrate#from-a-squad) for how to map a squad's responsibilities onto one assistant.

## Names, numbers, and dates

Expand Down
116 changes: 109 additions & 7 deletions fern/gpt-live/migrate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
---
title: Migrate to GPT-Live
subtitle: Move an existing assistant, compare it with the original, and keep a way back
description: Migrate a Vapi assistant to GPT-Live. Check fit, convert a copy, split prompts between the speaker and reasoner, compare results, and roll back safely.
subtitle: Move an existing assistant or squad, compare it with the original, and keep a way back
description: Migrate a Vapi assistant or squad to GPT-Live. Check fit, convert a copy, split prompts between the speaker and reasoner, map squad members to reasoner skills, compare results, and roll back safely.
slug: gpt-live/migrate
---

Move a copy of your assistant first, compare it with the original, and switch traffic after it meets the same goals. This guide covers a single assistant. If you use a squad, see [From a squad](#from-a-squad) for the current limits.
This page has two complete paths. Follow [From a single assistant](#from-a-single-assistant) if you're moving one assistant, or [From a squad](#from-a-squad) if you're combining a squad into one GPT-Live assistant. Each path repeats what it needs, so you can follow one without reading the other.

Both start from the same preparation.

## Before you start

Expand All @@ -14,7 +16,7 @@ Move a copy of your assistant first, compare it with the original, and switch tr
Some features don't carry over. If your assistant depends on one of these, plan how to replace it before you begin:

- **Voices** must be one of the [OpenAI voices GPT-Live supports](/gpt-live/configuration#voices). Other voice providers and custom or cloned voices aren't available.
- **Squads and assistant handoffs** aren't supported. There is no direct squad conversion; see [the current limits](#from-a-squad).
- **Squads and assistant handoffs** aren't supported. A squad becomes one assistant, as described [below](#from-a-squad).
- **Model and voice fallbacks** must be removed. GPT-Live can't be a fallback model either.
- **Exact or prerecorded speech** isn't available. GPT-Live generates all of its speech, including the greeting.
- **Keypad input** from callers isn't supported.
Expand All @@ -29,7 +31,7 @@ Pick a handful of calls that represent what the assistant has to get right: a st

### Keep the original running

Leave your phone numbers on the original assistant until the GPT-Live version has passed the same calls. Work on a copy, test it on its own, and switch traffic when you're ready.
Leave your phone numbers on the original assistant or squad until the GPT-Live version has passed the same calls. Work on a copy, test it on its own, and switch traffic when you're ready.

## From a single assistant

Expand Down Expand Up @@ -145,6 +147,8 @@ Three things changed besides the split:
- **Waiting is designed.** In the classic flow, the assistant read times out after a lookup and then asked for the name. The speaker now asks for the name while the lookup runs.
- **Results are for speaking.** The reasoner returns short facts that the speaker can use directly.

If the reasoner prompt grows to cover several distinct procedures, group them into [reasoner skills](/gpt-live/skills).

### 4. Map the settings

| Classic setting | With GPT-Live |
Expand Down Expand Up @@ -207,6 +211,104 @@ If you need to take a converted assistant back to Classic, select **Revert to Cl

## From a squad

GPT-Live doesn't support squads or assistant handoffs. **Switch to GPT Live** converts one assistant; it doesn't convert a squad or preserve its routing and handoff behavior.
A squad splits a conversation across assistants and hands the caller between them. GPT-Live keeps one voice for the whole call, and its reasoner can switch between procedures without a handoff. Migrating a squad means mapping what each member was responsible for onto one assistant. **Switch to GPT Live** converts a single assistant. It doesn't convert a squad, so this path is done by hand.

### How the pieces map

Take a squad with a front-desk assistant that greets callers and routes them, a scheduling assistant, and a service-information assistant:

| In the squad | In one GPT-Live assistant |
| --- | --- |
| Front-desk greeting, intake, and routing | Shared speaker behavior, assistant-wide reasoner rules, and delegation triggers |
| Scheduling assistant | A `schedule-appointment` skill with its procedure and booking tools |
| Service-information assistant | An `answer-service-questions` skill with its guidance and retrieval tool |
| Handoff conditions | Skill descriptions and the speaker's delegation triggers |
| Values passed between assistants | What the caller said is in the shared conversation. Values an earlier assistant or tool produced come from your services |
| Protected actions | Checks in your services: prerequisites, confirmation, duplicate handling |
| Transfer to a person | A `transferCall` tool, kept as a base tool |

### 1. Map each member's responsibility

For each assistant in the squad, write down what it's responsible for and why it was separate. Common reasons are a long procedure, a different set of tools, or a different tone.

Then decide where each responsibility goes:

- A procedure with its own rules and tools becomes a **skill**.
- Rules every part of the call follows, like "never report an action a tool didn't confirm", go in the **reasoner prompt**.
- Conversation guidance, like tone and pacing, goes in the **speaker prompt**.

You don't need one skill per old assistant. A front-desk assistant that only greeted and routed usually doesn't need a skill at all: its job becomes the speaker's greeting and delegation triggers. Two specialists with closely related work may be clearer as one skill.

### 2. Keep one voice and shared conversation rules

Write one speaker prompt for the whole call. Take the greeting and tone from the assistant callers heard first, and add anything the specialists did differently that callers relied on, such as a slower pace for explaining policies.

Remove handoff announcements like "Let me transfer you to our scheduling team." The caller stays with the same assistant, so they aren't needed. One of the goals of the migration is that the caller no longer repeats details at each handoff. Check that on real calls: it depends on your prompts and on the reasoner using the earlier conversation.

A handoff was also a point where the conversation paused. Now the speaker can keep going while the reasoner works. When the caller moves from a question to booking, the speaker can start the lookup and ask for the name in the same breath:

> **Caller:** Thanks. Can I book a consultation downtown on Friday?
>
> **Assistant:** Sure, I'll check Friday downtown. Who should I put it under?

Give the speaker the same waiting guidance as a single assistant: ask what the next step needs, answer what it already knows, and acknowledge a blocked wait once instead of filling it. See [Redesign the waits](#5-redesign-the-waits) above.

### 3. Build the skills

Each specialist's procedure becomes a skill's `content`, and its tools become the skill's tools. A minimal version for the scheduling and service-information specialists:

```json title="model.reasoner (excerpt)"
{
"instructions": "Work from the latest request in the conversation transcript. Load the skill that fits the request. Return short, plain facts the assistant can say. Never report an action a tool did not confirm. Call endCall when the caller asks to end the call.",
"skills": [
{
"name": "schedule-appointment",
"description": "Check open times, book a time, or cancel or move a booking made on this call.",
"content": "Call lookupAvailability when you have the service, location, and date. A caller choosing a time isn't agreement to book. Call bookAppointment only for a time from the latest lookup, and only when the transcript shows the assistant read back the day, time, location, and name and the caller then clearly said yes. Otherwise, return those details for the assistant to read back and confirm. To move a booking, look up the new time and confirm it with the caller first, then cancel the existing booking with cancelAppointment and book the new time. If the new booking fails after the cancellation, say so.",
"toolIds": ["LOOKUP_TOOL_ID", "BOOK_TOOL_ID", "CANCEL_TOOL_ID"]
},
{
"name": "answer-service-questions",
"description": "Answer questions about services, how long they take, what to bring, locations, hours, and the change policy.",
"content": "Use getServiceInfo and answer only from its result. If the caller was in the middle of booking, say so in your result so the assistant can return to it."
}
]
}
```

The `toolIds` are the IDs of the saved tools the scheduling assistant used. Tools that several skills need, or that must always be available, go in the assistant's base tools instead. Here `getServiceInfo`, `endCall`, and any transfer to a person are base tools. See [Reasoner skills](/gpt-live/skills#example-scheduling-and-service-questions) for the full procedure and tool placement.

### 4. Turn handoff conditions into descriptions and triggers

In the squad, handoff conditions decided which assistant took over. Now they do two jobs:

- **Skill descriptions** tell the reasoner which procedure a request needs. Write them in terms of the caller's request, and make sure two skills don't claim the same requests.
- **Delegation triggers** in the speaker prompt tell the speaker when to send work to the reasoner at all.

A condition like "hand off to scheduling when the caller wants to book, move, or cancel" becomes the scheduling skill's description and a line in the speaker's triggers.

The speaker also sees skill names and descriptions, so keep them short and suitable for the caller to hear about.

### 5. Plan for what doesn't carry over

- **Different voices or models per member.** One assistant has one voice and one reasoner model. Skills don't change either.
- **Separate context per member.** In one assistant, the whole call's conversation is shared, and skills don't isolate it. If a member was separate to keep information apart, enforce that in your services or keep that flow outside this assistant.
- **Handoff tools.** Remove them, since handoffs aren't supported.
- **Values passed at handoff.** Inventory each one before removing it. Details the caller said are in the shared conversation. Values an earlier assistant or tool produced, such as an account ID or a lookup result, may not be. Make those available from your services, for example through a tool the reasoner can call, and keep authoritative state there.
- **Member-specific hooks or settings.** Combine them into the one assistant's configuration, and check each against [Settings and compatibility](/gpt-live/configuration#compatibility).

### 6. Test the switches between procedures

The old handoff boundaries are the places to test most carefully, because that's where the combined assistant switches between procedures. Test:

- **A switch** from scheduling to a service question and back, without repeating details.
- **A return** to an unfinished booking after the detour.
- **A correction** during a lookup.
- **An already-completed action.** After a booking, return to the topic and check the assistant doesn't book again.
- **A failure** from a tool, and the recovery.

For each, check the call's messages for the skill loads and tool calls, your service's state for the outcome, and the recording for how it sounded. The reasoner uses the conversation and earlier results to continue, which works well when results are clear about status. Skills don't track workflow state for you, so your services must still reject duplicates and out-of-order actions.

### 7. Roll out and keep the squad

Keep your existing squad if your call flow depends on those capabilities. The single-assistant steps above aren't a replacement for a squad migration.
Move traffic to the new assistant when it passes your saved calls. Keep the original squad and its configuration unchanged as your fallback. Revert to Classic works on converted single assistants and doesn't recreate a squad, so the squad itself is your way back.
Loading
Loading