通话结束。管理员工作开始。
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 连接。






