Back to Details

create-squad

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vapi Squad Creation

Vapi 多助手团队创建

Create squads that orchestrate multiple specialized assistants with context-preserving handoffs. Break complex workflows into focused assistants that transfer calls between each other.
Setup: Ensure 
VAPI_API_KEY
is set. See the 
setup-api-key
skill if needed.
创建可编排多个专业助手并保留上下文的转接团队。将复杂工作流拆分为各司其职的助手，实现助手间的通话转接。
设置说明： 确保已配置
VAPI_API_KEY
。若需要可参考
setup-api-key
技能。

Why Squads?

为什么使用多助手团队？

Single assistants with large prompts cause higher hallucination rates, increased costs, and greater latency. Squads solve this by creating focused assistants with specific roles:
  • Triage → Booking → Confirmation
  • Sales → Technical Support → Billing
  • Receptionist → Department Specialist
使用大提示词的单一助手会导致更高的幻觉率、成本增加以及延迟提升。多助手团队通过创建具有特定角色的专注型助手解决这些问题：
  • 分诊 → 预约 → 确认
  • 销售 → 技术支持 → 计费
  • 前台接待 → 部门专员

Quick Start

快速开始

cURL

cURL

bash
curl -X POST https://api.vapi.ai/squad \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Squad",
    "members": [
      {
        "assistant": {
          "name": "Receptionist",
          "firstMessage": "Hello! How can I direct your call today?",
          "model": {
            "provider": "openai",
            "model": "gpt-4.1",
            "messages": [
              {
                "role": "system",
                "content": "You are a receptionist. Determine if the caller needs sales or support, then transfer them to the right department."
              }
            ],
            "tools": [
              {
                "type": "handoff",
                "destinations": [
                  {
                    "type": "assistant",
                    "assistantId": "sales-assistant-id",
                    "description": "Transfer when the caller asks about pricing, plans, or wants to purchase"
                  },
                  {
                    "type": "assistant",
                    "assistantId": "support-assistant-id",
                    "description": "Transfer when the caller has a technical issue or needs help"
                  }
                ]
              }
            ]
          },
          "voice": { "provider": "vapi", "voiceId": "Lily" },
          "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
        }
      },
      {
        "assistantId": "sales-assistant-id"
      },
      {
        "assistantId": "support-assistant-id"
      }
    ]
  }'
bash
curl -X POST https://api.vapi.ai/squad \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Squad",
    "members": [
      {
        "assistant": {
          "name": "Receptionist",
          "firstMessage": "Hello! How can I direct your call today?",
          "model": {
            "provider": "openai",
            "model": "gpt-4.1",
            "messages": [
              {
                "role": "system",
                "content": "You are a receptionist. Determine if the caller needs sales or support, then transfer them to the right department."
              }
            ],
            "tools": [
              {
                "type": "handoff",
                "destinations": [
                  {
                    "type": "assistant",
                    "assistantId": "sales-assistant-id",
                    "description": "Transfer when the caller asks about pricing, plans, or wants to purchase"
                  },
                  {
                    "type": "assistant",
                    "assistantId": "support-assistant-id",
                    "description": "Transfer when the caller has a technical issue or needs help"
                  }
                ]
              }
            ]
          },
          "voice": { "provider": "vapi", "voiceId": "Lily" },
          "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
        }
      },
      {
        "assistantId": "sales-assistant-id"
      },
      {
        "assistantId": "support-assistant-id"
      }
    ]
  }'

TypeScript (Server SDK)

TypeScript（服务端SDK）

typescript
import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

const squad = await vapi.squads.create({
  name: "Support Squad",
  members: [
    {
      assistant: {
        name: "Receptionist",
        firstMessage: "Hello! How can I direct your call today?",
        model: {
          provider: "openai",
          model: "gpt-4.1",
          messages: [
            {
              role: "system",
              content:
                "You are a receptionist. Determine if the caller needs sales or support, then transfer them.",
            },
          ],
          tools: [
            {
              type: "handoff",
              destinations: [
                {
                  type: "assistant",
                  assistantId: "sales-assistant-id",
                  description: "Transfer for pricing and purchasing questions",
                },
                {
                  type: "assistant",
                  assistantId: "support-assistant-id",
                  description: "Transfer for technical issues",
                },
              ],
            },
          ],
        },
        voice: { provider: "vapi", voiceId: "Lily" },
        transcriber: { provider: "deepgram", model: "nova-3", language: "en" },
      },
    },
    { assistantId: "sales-assistant-id" },
    { assistantId: "support-assistant-id" },
  ],
});

console.log("Squad created:", squad.id);
typescript
import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

const squad = await vapi.squads.create({
  name: "Support Squad",
  members: [
    {
      assistant: {
        name: "Receptionist",
        firstMessage: "Hello! How can I direct your call today?",
        model: {
          provider: "openai",
          model: "gpt-4.1",
          messages: [
            {
              role: "system",
              content:
                "You are a receptionist. Determine if the caller needs sales or support, then transfer them.",
            },
          ],
          tools: [
            {
              type: "handoff",
              destinations: [
                {
                  type: "assistant",
                  assistantId: "sales-assistant-id",
                  description: "Transfer for pricing and purchasing questions",
                },
                {
                  type: "assistant",
                  assistantId: "support-assistant-id",
                  description: "Transfer for technical issues",
                },
              ],
            },
          ],
        },
        voice: { provider: "vapi", voiceId: "Lily" },
        transcriber: { provider: "deepgram", model: "nova-3", language: "en" },
      },
    },
    { assistantId: "sales-assistant-id" },
    { assistantId: "support-assistant-id" },
  ],
});

console.log("Squad created:", squad.id);

Squad Structure

团队结构

Members

成员

The first member in the array starts the call. Each member is either:
  • Transient — Defined inline with 
    assistant: { ... }
  • Persistent — References a saved assistant via 
    assistantId: "..."
json
{
  "members": [
    { "assistant": { "name": "Inline Assistant", "..." : "..." } },
    { "assistantId": "saved-assistant-id" }
  ]
}
数组中的第一个成员启动通话。每个成员可以是：
  • 临时成员 — 通过
    assistant: { ... }
    内联定义
  • 持久成员 — 通过
    assistantId: "..."
    引用已保存的助手
json
{
  "members": [
    { "assistant": { "name": "Inline Assistant", "..." : "..." } },
    { "assistantId": "saved-assistant-id" }
  ]
}

Handoff Tools

转接工具

Handoff tools define how assistants transfer between each other:
json
{
  "type": "handoff",
  "destinations": [
    {
      "type": "assistant",
      "assistantId": "target-assistant-id",
      "description": "Clear description of WHEN to transfer. Be specific about trigger conditions."
    }
  ],
  "function": {
    "name": "handoff_to_sales"
  }
}
转接工具定义助手之间如何转接：
json
{
  "type": "handoff",
  "destinations": [
    {
      "type": "assistant",
      "assistantId": "target-assistant-id",
      "description": "Clear description of WHEN to transfer. Be specific about trigger conditions."
    }
  ],
  "function": {
    "name": "handoff_to_sales"
  }
}

Assistant Overrides

助手覆盖配置

Override saved assistant settings within the squad context without modifying the original:
json
{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "firstMessage": "Overridden greeting for this squad"
  }
}
在团队上下文中覆盖已保存助手的设置，而不修改原助手配置：
json
{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "firstMessage": "Overridden greeting for this squad"
  }
}

Appending Tools via Overrides

通过覆盖配置添加工具

Add squad-specific tools to a saved assistant:
json
{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "tools:append": [
      {
        "type": "handoff",
        "destinations": [
          {
            "type": "assistant",
            "assistantId": "another-assistant-id",
            "description": "Transfer when customer needs billing help"
          }
        ],
        "function": { "name": "handoff_to_billing" }
      }
    ]
  }
}
为已保存的助手添加团队专属工具：
json
{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "tools:append": [
      {
        "type": "handoff",
        "destinations": [
          {
            "type": "assistant",
            "assistantId": "another-assistant-id",
            "description": "Transfer when customer needs billing help"
          }
        ],
        "function": { "name": "handoff_to_billing" }
      }
    ]
  }
}

Member Overrides

成员全局覆盖配置

Apply configuration to ALL members simultaneously:
json
{
  "members": [
    { "assistant": { "name": "Agent A", "..." : "..." } },
    { "assistantId": "agent-b-id" }
  ],
  "memberOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
  }
}
同时对所有成员应用配置：
json
{
  "members": [
    { "assistant": { "name": "Agent A", "..." : "..." } },
    { "assistantId": "agent-b-id" }
  ],
  "memberOverrides": {
    "voice": { "provider": "vapi", "voiceId": "Elliot" },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
  }
}

Using Squads in Calls

在通话中使用多助手团队

Outbound call with a squad

使用团队发起外呼

bash
curl -X POST https://api.vapi.ai/call \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "squadId": "your-squad-id",
    "phoneNumberId": "your-phone-number-id",
    "customer": {
      "number": "+11234567890"
    }
  }'
bash
curl -X POST https://api.vapi.ai/call \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "squadId": "your-squad-id",
    "phoneNumberId": "your-phone-number-id",
    "customer": {
      "number": "+11234567890"
    }
  }'

Transient squad in a call

在通话中使用临时团队

json
{
  "squad": {
    "members": [
      { "assistant": { "..." : "..." } },
      { "assistantId": "..." }
    ]
  },
  "phoneNumberId": "phone-number-id",
  "customer": { "number": "+11234567890" }
}
json
{
  "squad": {
    "members": [
      { "assistant": { "..." : "..." } },
      { "assistantId": "..." }
    ]
  },
  "phoneNumberId": "phone-number-id",
  "customer": { "number": "+11234567890" }
}

Common Patterns

常见模式

Clinic Triage → Scheduling

诊所：分诊 → 预约

json
{
  "name": "Clinic Squad",
  "members": [
    {
      "assistant": {
        "name": "Triage Nurse",
        "firstMessage": "Hello, this is the clinic. How can I help you today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            {
              "role": "system",
              "content": "You are a clinic triage assistant. Assess the caller's needs: if they need an appointment, transfer to scheduling. If it's urgent, transfer to the nurse line."
            }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                {
                  "type": "assistant",
                  "assistantId": "scheduling-assistant-id",
                  "description": "Transfer when caller wants to book, reschedule, or cancel an appointment"
                },
                {
                  "type": "assistant",
                  "assistantId": "nurse-assistant-id",
                  "description": "Transfer for urgent medical questions or symptoms"
                }
              ]
            }
          ]
        },
        "voice": { "provider": "vapi", "voiceId": "Lily" }
      }
    },
    { "assistantId": "scheduling-assistant-id" },
    { "assistantId": "nurse-assistant-id" }
  ]
}
json
{
  "name": "Clinic Squad",
  "members": [
    {
      "assistant": {
        "name": "Triage Nurse",
        "firstMessage": "Hello, this is the clinic. How can I help you today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            {
              "role": "system",
              "content": "You are a clinic triage assistant. Assess the caller's needs: if they need an appointment, transfer to scheduling. If it's urgent, transfer to the nurse line."
            }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                {
                  "type": "assistant",
                  "assistantId": "scheduling-assistant-id",
                  "description": "Transfer when caller wants to book, reschedule, or cancel an appointment"
                },
                {
                  "type": "assistant",
                  "assistantId": "nurse-assistant-id",
                  "description": "Transfer for urgent medical questions or symptoms"
                }
              ]
            }
          ]
        },
        "voice": { "provider": "vapi", "voiceId": "Lily" }
      }
    },
    { "assistantId": "scheduling-assistant-id" },
    { "assistantId": "nurse-assistant-id" }
  ]
}

E-commerce: Sales → Support → Returns

电商：销售 → 支持 → 退货

json
{
  "name": "E-commerce Squad",
  "members": [
    {
      "assistant": {
        "name": "Sales Agent",
        "firstMessage": "Welcome to our store! Are you looking to make a purchase today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            { "role": "system", "content": "You are a sales assistant. Help customers find products and make purchases. Transfer to support for order issues or returns." }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                { "type": "assistant", "assistantId": "support-id", "description": "Transfer for order status, shipping, or account issues" },
                { "type": "assistant", "assistantId": "returns-id", "description": "Transfer for returns, refunds, or exchanges" }
              ]
            }
          ]
        }
      }
    },
    { "assistantId": "support-id" },
    { "assistantId": "returns-id" }
  ]
}
json
{
  "name": "E-commerce Squad",
  "members": [
    {
      "assistant": {
        "name": "Sales Agent",
        "firstMessage": "Welcome to our store! Are you looking to make a purchase today?",
        "model": {
          "provider": "openai",
          "model": "gpt-4.1",
          "messages": [
            { "role": "system", "content": "You are a sales assistant. Help customers find products and make purchases. Transfer to support for order issues or returns." }
          ],
          "tools": [
            {
              "type": "handoff",
              "destinations": [
                { "type": "assistant", "assistantId": "support-id", "description": "Transfer for order status, shipping, or account issues" },
                { "type": "assistant", "assistantId": "returns-id", "description": "Transfer for returns, refunds, or exchanges" }
              ]
            }
          ]
        }
      }
    },
    { "assistantId": "support-id" },
    { "assistantId": "returns-id" }
  ]
}

Best Practices

最佳实践

  1. Keep assistants focused — Each assistant should have 1-3 goals maximum
  2. Minimize squad size — Split only when there's a clear functional boundary
  3. Write specific handoff descriptions — The LLM uses these to decide when to transfer
  4. Mention handoffs in system prompts — Tell each assistant what departments exist
  5. Use member overrides — Apply consistent voice and transcriber settings across the squad
  1. 保持助手专注 — 每个助手最多负责1-3个目标
  2. 最小化团队规模 — 仅在有明确功能边界时拆分
  3. 编写具体的转接描述 — 大语言模型会根据这些描述决定何时转接
  4. 在系统提示词中提及转接 — 告知每个助手存在哪些部门
  5. 使用成员全局覆盖配置 — 为整个团队应用统一的语音和转录器设置

Managing Squads

管理多助手团队

bash
undefined
bash
undefined

List squads

列出所有团队

curl https://api.vapi.ai/squad -H "Authorization: Bearer $VAPI_API_KEY"
curl https://api.vapi.ai/squad -H "Authorization: Bearer $VAPI_API_KEY"

Get a squad

获取单个团队详情

curl https://api.vapi.ai/squad/{id} -H "Authorization: Bearer $VAPI_API_KEY"
curl https://api.vapi.ai/squad/{id} -H "Authorization: Bearer $VAPI_API_KEY"

Update a squad

更新团队

curl -X PATCH https://api.vapi.ai/squad/{id}
-H "Authorization: Bearer $VAPI_API_KEY"
-H "Content-Type: application/json"
-d '{"name": "Updated Squad Name"}'
curl -X PATCH https://api.vapi.ai/squad/{id}
-H "Authorization: Bearer $VAPI_API_KEY"
-H "Content-Type: application/json"
-d '{"name": "Updated Squad Name"}'

Delete a squad

删除团队

curl -X DELETE https://api.vapi.ai/squad/{id}
-H "Authorization: Bearer $VAPI_API_KEY"
undefined
curl -X DELETE https://api.vapi.ai/squad/{id}
-H "Authorization: Bearer $VAPI_API_KEY"
undefined

References

参考资料

Additional Resources

额外资源

This skills repository includes a Vapi documentation MCP server (
vapi-docs
) that gives your AI agent access to the full Vapi knowledge base. Use the 
searchDocs
tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.
Auto-configured: If you cloned or installed these skills, the MCP server is already configured via 
.mcp.json
(Claude Code), 
.cursor/mcp.json
(Cursor), or 
.vscode/mcp.json
(VS Code Copilot).
Manual setup: If your agent doesn't auto-detect the config, run:
bash
claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server
See the README for full setup instructions across all supported agents.
本技能仓库包含一个Vapi文档MCP服务器（
vapi-docs
），可让你的AI Agent访问完整的Vapi知识库。使用
searchDocs
工具查找本技能未涵盖的内容——高级配置、故障排除、SDK细节等。
自动配置： 如果你克隆或安装了这些技能，MCP服务器已通过
.mcp.json
（Claude Code）、
.cursor/mcp.json
（Cursor）或
.vscode/mcp.json
（VS Code Copilot）完成配置。
手动配置： 如果你的Agent未自动检测到配置，请运行：
bash
claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server
查看README获取所有支持Agent的完整设置说明。