通话结束。管理员工作开始。

Maya 是一名客户主管。她刚和 Larkspur Freight 的 Priya 结束了一通顺利的通话。他们原则上就价格达成了一致,Priya 想要一份书面纪要,周二有一个后续跟进,而且 Larkspur 的 CMO 应该了解一下企业版方案。

现在 Maya 距离下一通电话还有十五分钟,却有四个工具要更新:

  • HubSpot:记录通话,把交易推进到谈判阶段。
  • Apollo:找到 CMO,把她添加为联系人,放进企业版序列。
  • Google Calendar:预约周二。
  • Gmail:撰写价格纪要。

她的团队已经有一个语音智能体了。它很擅长对话。它能总结通话并建议下一步。但它碰不了这四个工具中的任何一个,所以 Maya 只能全部手动完成,又一次。

显而易见的解决办法是让智能体访问这些应用。而在语音场景下,这比听起来要难:

  • 通话过程中没有屏幕。如果 HubSpot 的连接过期了,智能体无法在 Maya 和它说话时弹出 OAuth 授权页面。
  • 每个工具都会拖慢回复。每个工具的 schema 在每一轮都会进入模型的上下文。在聊天应用里,多思考一秒钟没关系。在语音通话里,那就是一段尴尬的沉默。
  • 语音会被听错。“给 Priya 起草纪要”可能变成“给 Priya 发送纪要”。一个词听错,一封半成品邮件就发到了潜在客户那里。
  • Maya 看不到发生了什么变化。在聊天界面里,她能看到工具调用滚动出现。而在通话中,她只知道智能体告诉她的内容。

本文构建一个语音智能体,为一位销售代表处理整份清单,使用她自己的访问权限,并告诉她它做了什么。

任务:一句话,五个动作

以下是 Maya 原话描述的任务:

当我挂断和潜在客户的电话时,我想说出发生了什么,并让 CRM、后续跟进和外联工作在我下一通电话之前更新完毕。

所以通话结束后她说了一句话:

“记录 Larkspur Freight 的通话,把交易推进到谈判阶段,预约周二的后续跟进,给 Priya 起草价格纪要,并把他们的 CMO 加入企业版序列。”

这句话转化为五个动作,每个动作都由连接器文档中的一个工具支持:

Maya 的要求 应用 工具
记录通话,推进交易 HubSpot hubspot_deals_search,hubspot_call_log,hubspot_deal_update
找到 CMO 并把她加入序列 Apollo apollo_enrich_contact,apollo_create_contact,apollo_add_contacts_to_sequence
预约周二的后续跟进 Google Calendar googlecalendar_create_event
起草定价回顾 Gmail gmail_create_draft
告诉她改了什么 (该智能体) 没有,它只是回读工具返回的内容

这里有两个选择是刻意为之的。

回顾会保存为一份草稿,而不是直接发送。gmail_create_draft存在于gmail_send_message旁边,而对于语音智能体来说,草稿是正确的默认选项。如果某个词被听错了,它会留在 Maya 的草稿文件夹里,而不是 Priya 的收件箱里。

而该智能体回读它做了什么:“记录了通话,将 Larkspur 移至 Negotiation,预订了周二 10 点,将回顾保存为草稿,并将 Dana Okafor 加入企业序列。”在语音通话中,这段回读是 Maya 能看到的唯一审计记录。

自己动手搭建

你可以直接把它接起来。以下是一个 30 名销售代表的团队需要付出的代价。

三个 OAuth 应用,四个工具。HubSpot、Apollo 和 Google 各自都需要一个 OAuth 应用、一套授权流程、作用域、每位代表的加密令牌存储,以及刷新逻辑。Google Calendar 和 Gmail 可以共用一个 Google 应用,但它们的作用域仍然需要设置正确。

能在通话中途正常工作的令牌处理。某位代表的 HubSpot 令牌在下午 2 点过期。语音智能体在 2:05 尝试记录通话,结果失败。你的代码需要在通话前刷新,如果无法刷新,就大声说出来,并通过通话之外的其他方式给这位代表发一个链接。

一份小到足以对话的工具列表。这四个连接器合起来会暴露数百个工具。仅 HubSpot 连接器在 Scalekit 的目录中就有 457 个,其中 80 个具有破坏性。你需要手工挑选八个,编写它们的 schema,并在 API 变化时保持同步。

防止听错的护栏。你需要确保无论请求是如何被转写的,任何删除、归档或发送工具都无法被触达。

按代表记录每一个操作。当一笔交易推进了阶段却没人记得原因时,你需要知道是哪个代表的智能体做的、什么时候做的,以及返回了什么。

这些单独来看都不难。合在一起就构成了项目的大部分工作量,而且每新增一个应用、每新增一位代表,它都会变得更大。结果发现,语音那部分才是简单的部分。

用 Scalekit 和 Vapi 搭建

这个版本扩展了 Scalekit 的Vapi 语音助手 cookbook,它展示了与 Google Calendar、HubSpot、Apollo 和 Gmail 的模式。Vapi 负责语音和对话。Scalekit 位于智能体和应用之间:它保存每位销售代表的连接,只暴露该角色所需的工具,并记录每一次调用。

第 1 步:每位销售代表只需连接一次自己的应用

在 Maya 第一次通话之前,她会连接 HubSpot、Apollo 和 Google,例如从你应用中的设置页面进行连接。你的后端会针对每个连接向 Scalekit 查询她的已连接账号,如果该连接尚未激活,就获取一个授权链接发送给她:

import os
from scalekit import ScalekitClient

scalekit = ScalekitClient(
    env_url=os。environ["SCALEKIT_ENV_URL"],
    client_id=os。environ["SCALEKIT_CLIENT_ID"],
    client_secret=os。environ["SCALEKIT_CLIENT_SECRET"],
)
actions = scalekit。actions

# 使用你在 Scalekit 仪表板中创建的连接名称
CONNECTIONS = ["hubspot", "apollo", "googlecalendar", "gmail"]

def links_needed(rep_id: str) -> dict:
    """为每个尚未激活的连接返回一个授权链接。"""
    links = {}
    for name in CONNECTIONS:
        account = actions。get_or_create_connected_account(
            connection_name=name, identifier=rep_id
        )。connected_account
        if account。status != "ACTIVE":
            links[name] = actions。get_authorization_link(
                connection_name=name, identifier=rep_id
            )。link
    return links

rep_id是你应用中 Maya 的 ID。她的令牌加密保存在 Scalekit 中,并在那里刷新。你的语音应用和模型都看不到它们。

第 2 步:一个只包含该角色工具的 Virtual MCP 服务器

这四个连接器总共暴露了数百个工具。Maya 的智能体只获得八个。你只需为该角色定义一次,作为一个Virtual MCP 服务器:

from scalekit。actions。models。mcp_config import McpConfigConnectionToolMapping as Tools

response = actions。mcp。create_config(
    name="ae-post-call",
    description="Post-call updates for account executives",
    connection_tool_mappings=[
        Tools(connection_name="hubspot", tools=[
            "hubspot_deals_search", "hubspot_call_log", "hubspot_deal_update",
        ]),
        Tools(connection_name="apollo", tools=[
            "apollo_enrich_contact", "apollo_create_contact",
            "apollo_add_contacts_to_sequence",
        ]),
        Tools(connection_name="googlecalendar", tools=["googlecalendar_create_event"]),
        Tools(connection_name="gmail", tools=["gmail_create_draft"]),
    ],
)
MCP_CONFIG_ID = response。config。id
MCP_SERVER_URL = response。config。mcp_server_url

看看哪些不在列表里。HubSpot 的 80 个破坏性工具一个都没有,Apollo 的两个(apollo_archive_sequence,apollo_remove_records_from_list)也没有,Google Calendar 的六个、Gmail 的八个删除和清空工具同样没有。gmail_send_message也不在其中。不管转录内容怎么说,智能体都无法删除、归档、移除或发送。而且八个 schema 而非数百个,能让每一轮对话保持简短,这在有人等待语音回复时至关重要。

第 3 步:在每次调用开始时传入销售代表的身份

当 Maya 点击“开始通话”时,你的后端会检查她的连接,然后在该服务器上为她签发一个会话令牌。该令牌绑定到她的标识符,因此本次对话中的每次工具调用都以她的权限运行,而非他人。

from datetime import timedelta

@app。post("/api/voice/start")
def start_call(user=Depends(current_user)):
    rep_id = user。id  # 来自你自己的认证,绝不来自浏览器

    missing = links_needed(rep_id)
    if missing:
        notify_rep(rep_id, missing)  # 例如通过 Slack 私信或邮件发送链接
        return {"status": "reconnect", "apps": list(missing)}

    session = actions。mcp。create_session_token(
        mcp_config_id=MCP_CONFIG_ID,
        identifier=rep_id,
        expiry=timedelta(minutes=30),
    )
    return {
        "status": "ok",
        "scalekitToken": session。token,
        "sequenceId": user。team。enterprise_sequence_id,
        "mailboxId": user。apollo_mailbox_id,
    }

这就是在没有屏幕的情况下处理失效连接的方式。如果 Maya 的 HubSpot 授权已过期,通话不会在静默损坏的状态下开始。你的应用会告诉她需要重新连接哪个应用,并把链接发送到她能看到的地方。如果连接在通话中途失效,工具调用会失败,而智能体的指令(第 4 步)会告诉它大声说明这一点,而不是猜测。

这里的会话令牌有效期为 30 分钟(Scalekit 允许 60 秒到 24 小时)。它无法刷新,因此每次通话都会获得一个新的令牌。

第 4 步:将 Vapi 助手指向该服务器

在 Vapi 中,为助手添加一个MCP 工具。Vapi 的 MCP 工具接受服务器 URL 和请求头,而请求头可以使用变量:

{
  "type": "mcp",
  "server": {
    "url": "<MCP_SERVER_URL>",
    "headers": { "Authorization": "Bearer {{scalekitToken}}" }
  }
}

然后用该销售代表的值从浏览器发起通话:

const res = await fetch("/api/voice/start", { 方法: "POST" })。然后((r) => r。json());

if (res。status === "reconnect") {
  showBanner(`重新连接 ${res.apps.join(", ")}。我们已向你发送链接。`);
} else {
  vapi。start(ASSISTANT_ID, {
    variableValues: {
      scalekitToken: res。scalekitToken,
      sequenceId: res。sequenceId,
      mailboxId: res。mailboxId,
    },
  });
}

通话开始时,Vapi 会发现这八个工具。剩下的由系统提示词完成:

You help an account executive update their tools right after a sales call.
- Before writing anything, repeat back names, dates and the deal you found, and wait for a yes.
- Find the deal with hubspot_deals_search before updating it.
- Emails are always drafts. You cannot send email.
- Add contacts to sequence {{sequenceId}}, sending from mailbox {{mailboxId}}.
- If a tool says a connection needs to be re-authorized, say which app
  and tell the rep a reconnect link is on its way. Do not retry.
- When you're done, read back every change you made, one line each.

HubSpot 文档中的一条说明:hubspot_call_log接收通话标题、正文、方向、时长和状态。在依赖它之前,请先在 Scalekit playground 中查看已记录的通话如何与你门户中的交易关联。

第 5 步:每个操作都会记录到销售代表名下

每次工具调用都会经过 Scalekit,因此每一次调用都会被记录,包括工具、销售代表的标识符、时间和结果。如果下周 Larkspur 的交易阶段看起来不对,你可以确切看到是哪一通电话推动了它、来自谁的智能体,以及 HubSpot 返回了什么。失败会被标记为连接器错误(HubSpot 限流、它拒绝的某个权限范围)或 API 错误(你的配置问题)。

更偏好 LiveKit?

Scalekit 的LiveKit cookbook用另一种方式完成同样的标识符传递。你的服务器读取已登录用户,并在智能体的 dispatch metadata 中传递该标识符,worker 则对它定义的每个工具调用executeTool。该 cookbook 指出,@livekit/agents1.4.11 没有 MCP toolset,因此在那里你通过选择要包装哪些工具来限定工具范围。

两个 cookbook 都有可以克隆的仓库:Vapi和LiveKit。

何时不需要这套方案

如果语音智能体只供你个人使用,运行在你自己的 HubSpot 和 Google 账户上,你可以跳过集成层。把 API 密钥放进环境变量,手写这八个工具,一个下午就能搞定。

当第二个销售代表想要自己的访问权限、当某个连接在季度中途过期,或者当有人问是哪个智能体推动了某笔交易时,它就开始变得重要了。那时,按销售代表区分的连接、限定范围的工具列表和按通话记录日志就不再是可有可无的。

开始使用

要用你自己的账户试用,请从Scalekit quickstart开始,然后在仪表板中添加 HubSpot、Apollo、Google Calendar 和 Gmail 连接。