动作与工具

动作标签页是你管理代理在对话之外能做的一切的地方——包括代理在实时对话中调用的工具、在通话开始之前运行的预取钩子，以及通话结束后触发的通话后动作。检索变量（代理从每次对话中提取的数据字段）也位于同一个标签页中。

所有套餐

所有工具、动作以及新的预取钩子在每个套餐上都可用，包括免费套餐。

---

三个阶段

动作标签页中的每个条目都属于三个生命周期阶段之一。添加工具下拉菜单将它们分组，以便清楚地知道每个东西何时触发：

阶段	何时	示例
预取	在代理说你好之前	通过电话在你的 CRM 中查找来电者、拉取最新订单、从你的后端获取个性化问候语
实时通话	在对话期间，由 AI 在合适的时机触发	将通话转接给人工、检查日历可用性、转接给另一个代理、查询外部 API 获取数据
通话后	通话结束之后	发送摘要邮件、触发短信确认、将通话数据推送到你的 CRM

下拉菜单打开时预取位于顶部，因为其他每个阶段都已经有大量选项——新的预取条目最有可能是你正在寻找的东西。

---

预取

预取钩子让你的代理在通话开始时就已经知道是谁在打电话。它们与通话建立过程并行运行，并在说出第一个字之前将响应注入到代理的系统提示词中。

何时使用

• 通过电话号码识别回头客并称呼其姓名问候
• 拉取来电者的未完成订单、上次预约或会员等级
• 预加载取决于拨打了哪条线路的业务上下文
• 注入 CRM 备注，让代理了解潜在客户的阶段和历史

工作原理

1. 平台解析来电者的电话（入站从 SIP 获取，出站从拨打目标获取）。
2. 每个活跃的预取动作并行触发，每个请求有 1.5 s 的硬超时和 2 s 的总预算。
3. 成功的响应被拼接为命名块加入代理的系统提示词——代理在其第一轮就会读取它们。
4. 失败是静默的——缓慢或损坏的端点永远不会阻塞问候语。代理只是在没有该块的情况下开始说话。

配置

字段	描述
Name	必填。内部标签，也是提示词中的块名称——保持简短且有描述性（例如 crm_lookup、vip_check）。
API URL	必填。要获取的端点。支持 {phone}、{direction}、{agent_id}、{user_id}、{call_id} 占位符。
HTTP Method	GET 是默认值也是最合适的选择。POST / PUT / PATCH / DELETE 也可用。
Headers	可选。静态或模板化（占位符在此处也有效）。
Query Parameters	可选。新的预取动作会预填充 phone={phone}。

可用变量

这些标记会在请求时被替换到 URL、请求头和查询/正文参数中：

变量	来源	示例值
{phone}	来电者的电话（E.164）——对于出站，为目标号码	+431234567890
{direction}	inbound 或 outbound	inbound
{agent_id}	内部代理 id	65f1a2b3c4...
{user_id}	工作区所有者 id	65e0b1c2d3...
{call_id}	通话 id（让你的后端稍后关联通话后数据）	65f1f2c4d5...

未知的占位符会原样保留——错误的模板永远不会使通话崩溃。

提示词中会得到什么

如果你位于 https://crm.example.com/lookup?phone={phone} 的端点返回：

{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }

代理的系统提示词会追加一个以该动作命名、用 XML 包裹的块：

<call_context>
  <block name="crm_lookup">
  { "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }
  </block>
</call_context>

你不需要告诉代理如何使用它——LLM 会自然地领会上下文。你也可以选择在系统提示词中提及预取："If <call_context> contains a customer name, greet them by name."

重要约束

• 仅限电话通话。 预取不会为小部件（网页）通话运行——没有电话号码可用于模板。
• 响应正文上限 8 KB——超过部分会在注入前被截断。该上限保护你的提示词 token 预算，并限制恶意端点的影响范围。
• 不进行 condition 评估——预取在活跃时总是触发。此时还没有可供评估的转录内容。

提示

使用 GET 配合以电话为键的查找端点。保持响应小而结构化（包含 3-5 个字段的 JSON 对象）。代理不需要你完整的客户记录——只需要那些会改变对话的部分。

---

实时通话工具

这些工具在对话期间运行。AI 会根据每个工具的描述和当前对话来决定何时调用它。

可用工具

工具	用途	何时使用
Call Forwarding	转接给人工话务员	客户要求找人，或问题复杂
Google Calendar	检查可用性并预约	客户想安排会议
Outlook Calendar	同上，通过 Microsoft Outlook	客户想安排会议
API Tool RAG	从外部 API 获取实时数据	需要实时信息（订单、库存、账户状态）
Agent Transfer	转接给另一个语音代理	来电者需要不同的部门或专家
HubSpot CRM	在 HubSpot 中读写联系人和交易	将通话记录到 HubSpot，或查找潜在客户
MCP servers	暴露来自你已注册的任何 MCP 服务器的工具	你运行一个 MCP 兼容的工具服务器，并希望代理在对话中使用其工具

呼叫转移

在满足特定条件时将通话转接给人工。

设置	描述	示例
Name	必填。人员或部门名称	"Sales Manager"
Forwarding Number	转接的默认电话号码	"+49 123 456 789"
Trigger Condition	代理应何时转接	"Customer asks for manager or issue cannot be resolved"
Conditional Routing Numbers	用于路由的条件到号码映射	{"billing": "+49 111 222", "technical": "+49 333 444"}

工作原理：

1. 在对话期间，AI 评估触发条件。
2. 如果设置了条件路由号码，匹配的条件决定拨打哪个号码。
3. 否则使用转接号码。
4. 代理告知来电者即将转接。
5. 通话被转接——如果无人接听，则返回给代理。

提示

你可以为不同部门添加多个呼叫转移工具——一个用于"销售"，另一个用于"技术支持"，各自有不同的条件和号码。

Google Calendar

连接你的 Google Calendar，使代理能在通话期间检查可用性并预约。

设置：

1. 先前往 Integration → Calendars 并连接你的 Google 账户。
2. 在代理的动作标签页中添加 Google Calendar 工具。
3. 选择要使用的日历。
4. 配置你的可用性设置。

设置	描述	默认值
Calendar	必填。使用哪个日历	你的主日历
Timezone	预约的时区（IANA 格式）	自动检测
Work Start Time	工作时间开始	上午 9:00
Work End Time	工作时间结束	下午 6:00
Slot Duration	预约时长（分钟）	30
Working Days	一周中的可用日	周一至周五
Buffer Between Appointments	预约之间的缓冲时间（0–60 分钟）	0

支持的时段时长：15、30、45、60、75、90、105、120 分钟。

提示

准确设置你的工作时间和工作日——代理只会在你配置的可用时间内提供时段。

Outlook Calendar

连接你的 Outlook Calendar 以在通话期间安排预约。工作方式与 Google Calendar 相同。

设置：

1. 先前往 Integration → Calendars 并连接你的 Outlook 账户。
2. 在代理的动作标签页中添加 Outlook Calendar 工具。
3. 选择要使用的日历。
4. 配置你的可用性设置。

这些设置与 Google Calendar 完全相同（时区、工作时间、时段时长、工作日、缓冲时间）。

代理转接

将通话转接给你账户上的另一个语音代理。当你为不同部门设置了专门的代理时很有用。

设置	描述
Target Agent	必填。选择要转接到哪个代理
Trigger Condition	何时转接（例如"来电者询问技术支持"）

示例： 一个前台代理在来电者询问价格时将其转接给销售代理，或在遇到技术问题时转接给支持代理。

HubSpot CRM

在通话期间读写你的 HubSpot CRM。让代理记录互动、通过电话查找联系人，或推送交易更新，而无需你编写 API 调用脚本。

设置：

1. 前往 Integrations 页面并连接你的 HubSpot 账户。
2. 在代理的动作标签页中添加 HubSpot CRM 工具。
3. 选择允许代理操作的管道和属性。

添加工具后，AI 可以通过电话将来电者匹配到 HubSpot 联系人、获取交易阶段并更新字段——全部在实时对话中完成。

MCP servers

暴露来自你已连接到 Hanc.AI 的任何 MCP 兼容服务器的工具。一个代理可以从多个 MCP 服务器拉取工具；一个 MCP 服务器可以服务多个代理。

设置：

1. 在 Integration → MCP servers 下一次性连接你的 MCP 服务器。完整的注册步骤请参见专门的 MCP Servers 页面。
2. 将 MCP servers 条目添加到此代理的动作标签页——它在添加动作下拉菜单中归类于实时通话下。
3. 打开此代理应有权访问的那些已注册连接的开关。
4. 添加一条简短的**"何时使用"**说明，让代理知道何时使用这些工具。

代理在每次通话开始时从每个已启用的 MCP 服务器重新发现工具集，因此你在服务器端所做的更改会在下次通话时自动出现。工具会以连接标签作为前缀重命名，这样来自不同服务器的同名工具就不会冲突。

API Tool RAG

连接到外部 API 以在通话期间获取实时信息——查找订单、检查库存、验证账户，或访问任何可通过 API 获得的数据。

设置	描述	示例
Name	必填。工具名称	"Order Lookup"
Description / When to Use	必填。何时查询 API	"Customer asks about order status"
API URL	必填。API 端点。可以包含 {placeholder} 标记，这些标记将被 Body Parameters Schema 中的值替换（见下文）。	"https://api.yourshop.com/orders/{order_id}"
HTTP Method	必填。HTTP 方法	GET、POST、PUT、DELETE、PATCH
Loading Message	代理在等待时说的话	"Let me check that for you..."
Timeout	最大等待时间（ms）	5000（默认）
Headers	每个请求都发送的静态 HTTP 请求头	{"Authorization": "Bearer KEY"}
Query Parameters	添加到每个请求的静态查询字符串参数	{"apiVersion": "v2"}
Body Parameters Schema	必填。描述 AI 应从对话中提取并传递给工具的参数的 JSON Schema。参见编写 Body Parameters Schema。	JSON Schema 对象

提示

始终设置一条加载消息——API 调用期间的沉默会让来电者觉得出了故障。

备注

API Tool RAG 上旧的"Run on call start"复选框已被专门的 **预取**条目取代。当你希望在对话开始前获取数据时使用预取；当代理应在通话期间决定是否获取时使用 API Tool RAG。

编写 Body Parameters Schema

尽管名字如此，Body Parameters Schema 并不是原始的请求正文。它是一个 JSON Schema，描述 AI 应从对话中提取并传递给你的工具的内容。根据 HTTP 方法和 URL 模板的不同，这些值最终会进入 URL、查询字符串或 JSON 正文：

HTTP 方法	提取的值去向
URL 包含 {name}	匹配的值被替换到 URL 中
GET、DELETE	其余值以 ?key=value 追加到 URL
POST、PUT、PATCH	其余值作为 JSON 正文发送

最简结构

{
  "type": "object",
  "properties": {
    "param_name": {
      "type": "string",
      "description": "What this value is and how the AI should pick it"
    }
  },
  "required": ["param_name"]
}

根 type 始终为 "object"。properties 列出每个参数。required 标记哪些参数是 AI 必须始终提供的——如果客户还没说，AI 会在调用工具前询问。

字段参考

字段	用途
type	值的 JSON 类型："string"、"number"、"integer"、"boolean"、"array"、"object"
description	最重要。 告诉 AI 该值的含义、使用什么格式，以及何时提供。尽可能添加示例。
enum	将值限制为固定列表中的一个。AI 会将自然语言映射到最接近的选项（例如 "the blue one" → "blue"）。
minimum、maximum	数值范围。AI 会拒绝/钳制超出范围的值。
default	当 AI 不传递此字段时使用的值。非必需，但可记录隐含值。
format	验证提示，例如 "email"、"date"（YYYY-MM-DD）、"uri"。

示例

产品搜索（仅关键词）：

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Product search keyword — e.g. \"phone\", \"laptop\", \"Apple\", \"Samsung\""
    }
  },
  "required": ["query"]
}

配合 URL https://dummyjson.com/products/search?q={query}&limit=5 和 GET 使用：query 值进入 URL 占位符。正文中不会有任何内容。

按 ID 查找订单：

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Order ID the customer is asking about, usually 6 to 10 digits. Ask the customer if not provided."
    }
  },
  "required": ["order_id"]
}

配合 URL https://api.example.com/orders/{order_id} 和 GET 使用。

带多个必填字段的预订：

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID returned by a previous search_products call."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "How many items to reserve. Default 1."
    },
    "delivery_method": {
      "type": "string",
      "enum": ["pickup", "home_delivery", "locker"],
      "description": "How the customer wants to receive the item."
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "description": "Customer's email for order confirmation. Ask if not provided."
    }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

配合 POST https://api.example.com/reservations 使用：四个值进入 JSON 正文。AI 会在调用工具前向客户询问缺失的 required 字段。

无参数工具：

{
  "type": "object",
  "properties": {}
}

当端点完全静态（例如 GET /store/hours）且 AI 不需要传递任何内容时使用此项。

语音代理的最佳实践

• 保持 schema 扁平。 嵌套的对象和数组可以工作，但 AI 在电话中说话时可能出错。最多优先使用 3–5 个顶层字段。
• 始终为每个字段编写 description。 包含示例（e.g. "phone", "laptop"）——示例比抽象定义更可靠地引导 AI。
• 只要有固定的值列表就使用 enum。 它消除了 AI 编造值或发送 "Electronics" 而非 "electronics" 的风险。
• 只有当工具没有某字段就无法工作时才将其标记为 required。 其他一切都是可选的，AI 会在客户没有提及时跳过它——不会有尴尬的额外提问。
• 使用 snake_case 命名，并与 URL 中的任何 {placeholder} 标记完全匹配。
• 在 description 中记录缺失值时的行为——例如 "Omit if no budget limit"、"Default 5"。

---

实时消息动作

（v2.4） Send SMS live 和 Send Email live 让代理在通话过程中发送短信或邮件——就在它仍与来电者交谈时——而不像它们的通话后对应动作那样只在通话结束后发送。用它们来发送链接、预订确认、验证码，或来电者在挂断前可以据以行动的摘要。

AI 会根据动作的描述和对话在当下自行触发这些动作——与它决定调用任何其他实时工具的方式相同。

动作	触发时机	发送对象
Send SMS live	通话期间	来电者的电话号码
Send Email live	通话期间	来电者的邮箱

每次通话的发送上限

每个渠道的上限为每次通话每个渠道 3 次发送。一个代理在单次通话中最多可发送三条实时短信和最多三封实时邮件；某个渠道上的第四次发送会被拒绝。这可以防止喋喋不休或循环的对话向来电者发送垃圾信息。

拒绝矩阵

在以下情况下实时发送会被拒绝（并会告知代理原因，以便其优雅地恢复）：

条件	结果
无效或缺失的邮箱（针对 Send Email live）	被拒绝——代理请来电者确认其邮箱
无效或缺失的电话（针对 Send SMS live）	被拒绝——代理请来电者确认其号码
正文超过 160 个字符	被拒绝——消息太长无法照原样发送
达到渠道上限（本次通话已发送 3 次）	被拒绝——该渠道不再发送

由于代理会得到拒绝原因，它可以在对话中修正问题（"能帮我拼一下那个邮箱吗？"）并重试，而不是静默失败。

CRM 时间线记录

每次实时发送都会记录到联系人的 CRM 时间线中，因此代理在通话中发送的消息会与通话记录并排显示——你可以准确看到发送了什么、发往哪个渠道以及何时发送。

智能表单到渠道链接

当网页来电者提交小部件表单时只填写了部分联系方式，代理只会使用它实际拥有的渠道：

• 来电者只提交了邮箱 → 代理触发 Send Email live（绝不用短信）。
• 来电者只提交了电话 → 代理触发 Send SMS live（绝不用邮件）。
• 来电者两者都提交 → 代理可以根据对话需要使用任一渠道。

这意味着代理绝不会尝试给只提供了邮箱的来电者发短信，或给只提供了号码的来电者发邮件——可用的表单数据决定了哪个实时动作可用。

---

通话后动作

通话后动作在通话结束、分析链生成摘要、情感和提取的变量之后触发。它们消费通话数据——不与客户交谈。

可用动作

动作	用途
Send Email	向你的团队或客户发送结构化摘要邮件
Send SMS	向来电者发送短信确认
Send WhatsApp	WhatsApp 消息或模板（在 24 小时窗口内外均有效）
API Call	将完整的通话数据推送到外部 API（CRM、webhook、你的数据仓库）

Send Email

设置	描述
Name	必填。动作标识符
Subject	必填。邮件主题行
Message Body	必填。邮件正文——可包含检索变量
Trigger Condition	何时发送（留空 = 始终）
Recipients	必填。始终收到邮件的邮箱地址
Conditional Recipients	条件到收件人的映射

在邮件中使用变量：

New lead from phone call:

Name: {{customer_name}}
Email: {{customer_email}}
Interested in: {{selected_plan}}
Notes: {{call_notes}}

Send SMS

设置	描述
Name	必填。动作标识符
Sender Name	显示的发件人名称
Message	必填。短信内容（可包含变量）
Trigger Condition	何时发送
Recipients	必填。始终收到短信的电话号码
Conditional Recipients	条件到号码的映射

Send WhatsApp

HANC 上的 WhatsApp 消息使用来自中央 Twilio Content 账户的预先批准的模板——你不需要手动粘贴 Template SID。动作编辑器显示一个下拉列表，包含当前所有活跃且已批准的模板，你从中选择一个。然后模板内的占位符（{{1}}、{{2}}……）会用通话变量或你在编辑器中映射的静态文本内联填充。

设置	描述
Name	必填。动作标识符
Trigger Condition	何时发送
Recipients	必填。始终收到消息的电话号码
Conditional Recipients	条件到号码的映射
Template	必填。从中央 Twilio Content 账户同步的预先批准的 WhatsApp 模板下拉选择器。每个条目显示模板名称、语言和正文预览，让你知道该选哪个。
Template Variables	对于你选择的模板，编辑器会列出每个占位符（{{1}}、{{2}}……），并让你将其映射到通话变量（见下文）或静态字符串。

你可以映射到模板占位符的可用通话变量：

变量	描述
{{call_from}}	来电者的电话号码
{{call_to}}	被拨打的号码
{{call_summary}}	AI 生成的通话摘要
{{call_sentiment}}	情感（positive/neutral/negative）
{{call_task_achieved}}	通话任务是否达成
{{call_transcription}}	完整的通话转录

为什么用选择器而非自由文本

WhatsApp 要求每条在 24 小时客服窗口之外由企业发起的消息都必须使用预先批准的模板。HANC 从共享的 Twilio Content 账户同步已批准的模板列表，因此下拉菜单始终显示当前可发送的确切内容——你不会意外选到草稿、被拒绝的模板或不存在的 SID。要添加新模板，请联系支持；一旦获 WhatsApp 批准，它就会自动出现在下拉菜单中。

API Call

通话后 API Call 动作是你通向技术栈其余部分的通用 webhook。选择方法、设置 URL，我们就会发送整个通话数据——你的端点会收到一个描述所发生事情的结构化 JSON 对象。

设置	描述
Name	必填。动作标识符
Trigger Condition	何时触发（留空 = 每次通话）。由 LLM 针对转录内容进行评估。
API URL	必填。API 端点 URL
HTTP Method	必填。GET、POST、PUT、DELETE、PATCH
Headers	可选的请求头
Query Parameters	可选的查询字符串参数

你的端点会收到什么

对于 POST / PUT / PATCH，你的端点会在请求正文中收到一个 JSON 对象。你配置的正文参数会与完整的通话数据合并：

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "call_summary": "Customer asked about pricing…",
  "task_achieved": true,
  "sentiment": { "sentiment": "positive", "explanation": "…" },
  "custom_analysis_data": {
    "name": "John",
    "email": "john@example.com"
  },
  "collected_data": { /* in-call form submissions */ },
  "transfer_history": [ /* if any agent transfer happened */ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup",
  "is_anonymous": false,
  "is_simulation": false,
  "created_at": 1730000000000,
  "updated_at": 1730000187000
}

对于 GET / DELETE，相同的字段会被展平到查询字符串中——但像 transcription、sentiment 和 custom_analysis_data 这样的嵌套值会被丢弃（URL 无法合理地承载结构化数据）。如果你需要转录内容，请使用 POST/PUT/PATCH。

每个请求还会附带一个用于追踪的 X-Correlation-Id 请求头，并在 30 秒后超时。

预取 vs 通话后 API Call

• 预取将 {phone} 等模板化到 URL/请求头/查询/正文中。在通话前将结果返回到提示词中。
• 通话后 API Call 在正文或查询中发送整个通话数据转储。没有 URL 模板——你的端点得到静态 URL + 动态正文。

---

检索变量

检索变量是 AI 自动从对话中提取的自定义数据字段。例如，代理可以捕获来电者的姓名、邮箱、电话号码或你定义的任何其他信息。

默认变量

每个新代理创建时都带有两个默认检索变量：

变量	类型	描述
Email	Email	来电者的邮箱地址
Phone	Phone	来电者的电话号码

这些默认启用并显示在通话小部件表单中。你可以编辑或删除它们，并添加自己的自定义变量。

变量类型

类型	用例	示例
Text	姓名、地址、备注、自由格式输入	客户姓名、送货地址
Number	数量、预算、ID	订单数量、预算金额
Email	带验证的邮箱地址	客户邮箱
Phone	带验证的电话号码	客户电话号码
Selector	从预定义选项中选择	首选套餐（Basic/Pro/Enterprise）
Checkbox	是/否同意或确认	"我同意接收营销邮件"

配置变量

字段	描述	示例
Variable Name	必填。变量标识符	customer_email
Instructions for AI	必填。告诉 AI 何时以及如何提取此值的说明	"The customer's email address. Ask if not provided."
Example Format	（可选） 预期格式示例	"john@example.com"
Options (for Selector)	（仅 Selector） 允许的选项列表	["Basic", "Pro", "Enterprise"]
Show in Form	是否在通话小部件表单中显示此字段	默认启用

在表单中显示

当启用在表单中显示时，该变量会在通话前和通话期间作为可见的输入字段出现在网页小部件中。这让来电者可以直接填写他们的信息，作为 AI 从对话中提取的补充。

提示

AI 会在对话中自然地询问缺失的信息。设置一个清晰的描述，如"客户的邮箱地址，如未提供则礼貌询问"，代理就会处理它。

---

添加工具与动作

1. 导航到你代理的动作标签页。
2. 点击添加工具。
3. 从下拉菜单中选择正确的阶段——预取、实时通话或通话后。
4. 配置设置。
5. 保存——更改在下次通话时生效。

所有条目都一起列在动作表中。点击任意行进行编辑，或使用垃圾桶图标删除。

---

相关

• 语音代理概述
• 提示词工程 — 在提示词中引用工具
• 知识库 — 信息源
• 集成 — 你的工具可以对接的外部系统