> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 核心概念
> 平台中所有内容的地图——每个对象的作用、其在控制台中的位置，以及与之交互的 API。
ThunderPhone 是一个用于构建、运行和改进 AI 语音智能体的完整平台。本页是一张地图：您将遇到的每个概念都对应一个简短章节，并说明其控制台界面及支撑它的 API。您可以先快速浏览一遍，之后遇到需要进一步解释的术语时再回来查阅。
控制台侧边栏与此结构对应：
[智能体](#agents)、[电话号码](#phone-numbers)、
[网页小组件](#web-widgets)、[通话](#calls)、
[知识库](#knowledge-bases)。
[实时监控](#live-monitoring)和外呼
[活动](#campaigns)。
您的智能体可使用的[应用、API、MCP 服务器和 VoIP 提供商](#connections)。
[模拟](#simulations)、[实验](#experiments)、
[问题](#issues)、[报告](#reports)、
[可观测性](#observability)。
[团队与角色](#team-and-roles)、[API 密钥](#organizations)、
[警报](#alerts)、[计费](#billing)。
用于您自有代码的[Webhook](#webhooks)和[函数工具](#function-tools)。
***
## 组织
**组织**是租户单位。其他所有资源——智能体、电话号码、通话、密钥——都恰好属于一个组织。您的账户可以属于多个组织；每个组织都有各自的余额、密钥和成员列表。
您在**组织 → 密钥**下创建的 `sk_live_` API 密钥会绑定到一个组织。正是这一绑定让 REST API 如此扁平：您无需在 URL 路径中添加组织 ID，因为您的密钥已可识别该组织。
**在控制台中：**组织切换器（侧边栏底部）和**组织**设置——包含常规、密钥、警报、计费设置和计费历史选项卡。
**在 API 中：**[`/v1/orgs`](/api-reference/organizations)、
[`/v1/developer/api-keys`](/api-reference/developer-api-keys)。
***
## 智能体
**智能体**是运行通话的 AI 配置。它包含：
* 用于规定智能体说什么以及如何行为的**提示词**——包括转接、按键和挂断等通话操作；这些都是普通的提示词行，而非单独的配置。
* **引擎层级**（`spark`、`bolt`、`storm-*`）：Spark 针对成本优化，Bolt 针对速度优化，Storm 则为复杂提示词提供更强的智能能力。
* **音色**以及**主要语言**和可选的**附加语言**——当来电者切换语言时，智能体会自动切换。请参阅[支持的语言](/zh/guides/supported-languages)。
* 已附加的能力：[已连接的应用](#connections)、
[API 连接](#connections)、[知识库](#knowledge-bases)、
[MCP 服务器](#connections)以及内联
[函数工具](#function-tools)。
* 行为调节项：发言顺序、确认模式、背景音轨、保持超时。
您在构建器中的编辑会**自动保存为草稿**；只有在您点击**发布**后才会生效。每次发布都会在构建器的**历史记录**选项卡中创建快照，因此您可以检查并恢复任何先前版本。
\*\*在控制台中：\*\***语音智能体** → 智能体构建器
(`/dashboard/agents`)。请参阅
[构建您的第一个语音智能体](/zh/guides/build-an-agent)。
**在 API 中：**[`/v1/agents`](/api-reference/agents)——CRUD、
复制、转接、版本历史记录和提示词辅助工具。
***
## 电话号码
一个**电话号码**属于一个组织，并将呼入电话路由到某个
智能体（也可用于外呼）。有两种来源：
* **演示号码** —— 从 ThunderPhone 的号码池中配置的真实美国
号码，数秒内即可启用。仅支持呼入，会通过简短的语音
免责声明接听，且控制台将每个组织限制为 10 个。非常适合
初次测试，但不适用于生产环境。
* **VoIP 号码** —— 通过您自己的服务提供商并借助
[VoIP 连接](#connections)接入。Twilio 和 Telnyx 可直接连接
（Telnyx 提供引导式设置）；SignalWire 和 Vonage 即将推出——
目前您可通过手动 SIP 配置接入它们，该配置支持任何
SIP 中继。导入并验证后，VoIP 号码支持呼入和外呼。
每个号码行都可让您设置路由模式、选择呼入智能体，
并为号码添加标签。
**在控制台中：** **电话号码**（`/dashboard/phone-numbers`）。
请参阅[获取电话号码](/zh/guides/get-a-phone-number)。
**在 API 中：** [`/v1/phone-numbers`](/api-reference/phone-numbers)，
[`/v1/voip-connections`](/api-reference/voip-connections)，
[`/v1/phone-number-labels`](/api-reference/phone-number-labels)。
***
## 通话
每次呼入电话、外呼电话、模拟和小组件会话
都会成为一条**通话日志**。通话包含完整的带角色标记的转录文本、
结构化轮次历史记录（包括工具调用）、录音、
账单总额，以及可选的 AI 评分和问题报告。
当通话处于**进行中**状态时，您可以打开并**旁听**——您会
静默加入，通话中的任何人都不会听到您。开始旁听后，您可以
**低语**：输入一条直接发送给您的智能体的指令，
智能体会在通话过程中接收；来电者永远不会听到，智能体会实时执行。
**在控制台中：** 使用**通话记录**（`/dashboard/call-history`）查看
归档和每通电话的详细信息；使用**进行中**查看正在进行的通话。请参阅
[查看、旁听和指导您的通话](/zh/guides/review-calls)。
**在 API 中：** [`/v1/calls`](/api-reference/calls) —— 列表、转录文本、
历史记录、音频、评分、导出；
[`/v1/issue-reports`](/api-reference/issue-reports)。
***
## 网页小组件
**网页小组件**让您的网站访客能够通过麦克风与智能体对话——
无需电话号码。它使用**可发布密钥**（`pk_live_...`）进行身份验证，
该密钥会被源站限制在您允许的域名中，因此可安全地用于
客户端代码。
密钥以两种模式之一运行：`agent`（静态绑定到一个智能体）
或 `webhook`（您的服务器为每位访客选择配置——请参阅
[按通话动态配置](/zh/guides/dynamic-call-config)）。小组件
会话与电话通话使用相同的通话基础设施。
**在控制台中：** **网页小组件**（`/dashboard/web-widgets`）——
创建小组件、设置模式和智能体、管理允许的域名，并
复制嵌入代码片段。请参阅
[创建网页小组件](/zh/guides/embed-a-web-widget-dashboard)。
**在 API 中：** [`/v1/publishable-key`](/api-reference/publishable-keys)，
[`/v1/mic-session`](/api-reference/mic-sessions)，以及
[小组件 SDK 文档](/zh/widget/overview)。
***
## 知识库
**知识库**是一组您的智能体可在通话过程中搜索的文档，
用于为其回答提供依据——直接上传文件或从
Google Drive 导入，然后在构建器中将知识库关联到智能体。
智能体会在对话需要时使用内置搜索工具查询它。
**在控制台中：** 使用**知识库**（`/dashboard/knowledge`）查看
文档库；在构建器的**知识库**部分将知识库关联到
智能体。请参阅
[为您的智能体提供知识库](/zh/guides/knowledge-base)。
***
## 连接
连接让智能体能够与外部世界交互。共有四种类型，归在一个侧边栏分组中：
* **应用**（`/dashboard/app-connections`）——与 Slack、HubSpot、Salesforce、Google Calendar、Google Sheets 和 Cal.com 的 OAuth 连接。连接一次后，即可为任意智能体启用或停用按操作划分的工具（发送 Slack 消息、更新或插入 HubSpot 联系人、预订 Cal.com 时段……）。请参阅[连接应用](/zh/guides/connect-apps)。
* **API**（`/dashboard/api-connections`）——将任意 HTTP API 转换为智能体操作。粘贴一条 cURL 命令，AI 向导即可起草工具定义；您也可以手动构建。**测试请求**按钮会在您发布前发起一次沙盒调用。请参阅 [API 连接](/zh/guides/api-connections)——这是 [`/v1/integrations`](/api-reference/integrations) 的控制台界面。
* **MCP**（`/dashboard/mcp-connections`）——通过 URL 添加 Model Context Protocol 服务器，并让智能体使用其公开的工具。请参阅[添加 MCP 服务器](/zh/guides/mcp-servers)。
* **VoIP**（`/dashboard/voip-connections`）——用于[使用您自己的电话号码](#phone-numbers)的服务提供商凭据。请参阅[连接 VoIP 服务提供商](/zh/guides/voip-providers)。
**在 API 中：**[`/v1/integrations`](/api-reference/integrations) 和 [`/v1/voip-connections`](/api-reference/voip-connections)；另请参阅[构建工具集成](/zh/guides/build-tool-integration)。
***
## 营销活动
**营销活动**可大规模发起呼出：上传联系人 CSV，选择智能体和主叫号码，并设置呼叫时段（按时区计算的日期和时间）、并发量及重试策略（最大尝试次数，以及哪些结果——无人接听、语音信箱、失败——需要重试）。营销活动会依次处理列表，并在通话记录中记录每一通通话。
\*\*在控制台中：\*\***营销活动**（`/dashboard/campaigns`）。请参阅[运行呼出营销活动](/zh/guides/outbound-campaigns)。
\*\*对于一次性编程呼叫：\*\*使用[呼出通话 API](/zh/guides/place-outbound-calls)。
***
## 实时监控
**实时**会显示整个组织中所有正在进行的通话，并允许您打开其中任意一通，以便[实时旁听和耳语指导](#calls)。这是监督界面：您可以观察新提示词接入第一批真实流量，或持续关注正在运行的营销活动。
\*\*在控制台中：\*\***实时**（`/dashboard/live`）。请参阅[查看和监督实时通话](/zh/guides/monitor-live-calls)。
***
## 模拟
**模拟**是由 AI 呼叫方与您的智能体进行一次真实对话——采用相同的电话路径、真实的转录文本和真实的评估——因此您可以在发布前（以及发布后）进行测试。您可以将其指向一个智能体或电话号码，自行编写呼叫方场景，或根据智能体的提示词通过 AI **生成场景**（如有要求，也会包含边缘情况），然后实时观看通话。
场景会归入**套件**，套件会设定最低通过率，并可在 CI 中作为发布门槛；系统会按场景报告相对于已接受基线的回归。
\*\*在控制台中：\*\***模拟**（`/dashboard/simulations`），以及智能体构建器中的 **模拟**按钮。请参阅[模拟一次通话](/zh/guides/simulate-a-call)。
**在 API 中：**[`/v1/test-calls`](/api-reference/test-calls) 和套件运行器——请参阅[端到端测试智能体](/zh/guides/test-agents)。
***
## 实验
**实验**可在实时流量上对智能体配置进行 A/B 测试：定义变体（不同的提示词、引擎或设置），在变体之间分配流量，并按变体比较结果。使用它可避免在 webhook 中手动编写分桶逻辑。
\*\*在控制台中：\*\***实验**（`/dashboard/experiments`）以及智能体构建器中的 **A/B** 选项卡。请参阅[实验（A/B 测试）](/zh/guides/experiments-ab-testing)。
***
## 问题
**问题**是特定通话中被标记的问题——可由人工审核员提交，或由 AI 评分检测。问题包含严重程度、来源和状态；“问题”页面是分诊队列：您可以筛选、检查存在问题的通话并跟踪修复进度。
**在控制台中：** **问题**（`/dashboard/issues`），以及通话记录中的单次通话标记。请参阅[问题分诊](/zh/guides/issues)。
**在 API 中：** [`/v1/issue-reports`](/api-reference/issue-reports)。
***
## 报告
**报告**通过 AI 撰写的分析回答有关您的通话数据的自然语言问题（“上周来电者要求转人工的前三个原因是什么？”），并可限定您选择的智能体和日期范围。
**在控制台中：** **报告**（`/dashboard/reports`）。请参阅[报告](/zh/guides/reports)。
***
## 可观测性
**可观测性**是指标视图：通话量、结果和质量随时间的变化。您可以按智能体和时间窗口筛选，并导出数据以供下游分析。
**在控制台中：** **可观测性**（`/dashboard/observability`）。请参阅[可观测性](/zh/guides/observability)。
***
## 警报
**警报规则**会在一个时间窗口内监控指标（成功率、失败率、平均得分、通话量、套件回归），并在其越过您设定的阈值时触发。通知会发送至电子邮件和 Slack，并向您的[Webhook 端点](/zh/webhooks/endpoints)触发 `alert.triggered` 事件。
**在控制台中：** **组织 → 警报**。请参阅[警报](/zh/guides/alerts)。
***
## Webhook
当通话期间和通话结束后发生事件时，ThunderPhone 会向您的服务器发送 **HTTP POST Webhook**。支持两种交付模式：
* **Webhook 端点**（推荐）：在 [`/v1/developer/webhook-endpoints`](/zh/webhooks/endpoints) 管理多个 URL，并为每个端点设置密钥和事件订阅。
* **旧版单 URL Webhook**：每个组织一个 URL。在 [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) 或 **组织 → 常规** 下管理。保留此功能以实现向后兼容。
事件分为两类：
* **阻塞事件**要求您的服务器返回会影响进行中通话的配置——即[来电事件](/zh/webhooks/call-incoming)（`telephony.incoming` / `web.incoming`）。您最多有 10 秒钟响应；若超时，则由静态分配的智能体处理通话。
* **非阻塞事件**是即发即弃的通知，并会采用指数退避重试——请参阅[交付语义](/zh/webhooks/overview)。
每个请求都会在 `X-ThunderPhone-Signature` 中携带 HMAC-SHA256 签名。请参阅[签名验证](/zh/webhooks/overview)。
***
## 函数工具
**函数工具**是您的智能体可在对话过程中调用的 HTTP 端点。您向 ThunderPhone 提供 OpenAI 风格的函数架构和端点 URL；智能体决定何时调用，ThunderPhone 从其服务器发起已签名的 HTTP 请求，并将结果返回给智能体。
智能体还提供**内置通话能力**——转接通话、发送按键（DTMF）输入、结束通话、保持等待——您无需定义工具，只需通过简单的提示词行即可启用。
**在控制台中：** 构建器的 **API 连接**部分（请参阅[连接](#connections)）。
**在 API 中：** [`/v1/integrations`](/api-reference/integrations) 和[函数工具规范](/zh/tools/overview)。
***
## 团队和角色
每个组织都有成员列表，包含两种角色：**成员**负责构建和运营智能体；**管理员**还可管理团队和账单。您可以通过电子邮件邀请成员——邀请会在 7 天后过期，也可撤销；成员行中的 ⋯ 菜单可用于更改角色或移除成员。可在整个组织范围内配置单点登录——请参阅[SSO](/zh/guides/sso)。
**在控制台中：** **组织 → 常规**。请参阅[邀请您的团队](/zh/guides/invite-your-team)。
**在 API 中：** [`/v1/members`](/api-reference/members)，
[`/v1/invites`](/api-reference/invites)。
***
## 计费
ThunderPhone 采用**预付费**模式。每个组织都有美元余额；通话会按智能体的每分钟费率扣费（引擎套餐加附加费——构建器会在您更改设置时实时显示全包费率，[高级语言](/zh/guides/supported-languages)额外收取 2¢/分钟）。当余额降至零时，系统会拒绝呼入电话，呼出电话会返回 `402 Payment Required`。
您可以手动充值，或启用**自动充值**并设置余额阈值、充值金额和可选的每月支出上限——确保通话不会在句中中断。
**在控制台中：** **组织 → 计费设置**和**计费记录**。请参阅[充值并启用自动充值](/zh/guides/billing-and-topups)。
**在 API 中：** [`/v1/billing`](/api-reference/billing)。
***
## 应用内副驾驶
控制台内置了**副驾驶**功能——向它询问“如何执行 X”，它会根据这些文档回答，提供逐步点击的操作指引并突出显示实际控件，还可以重播任何引导式导览。这是查找本页面提及控件的最快方式。请参阅[询问应用内副驾驶](/zh/guides/ask-the-copilot)。
***
## 整合使用
五步向导：智能体 → 计费 → 号码 → 模拟 → 审核。
通过四个 REST 调用完成同一个首次通话。
构建智能体、充值、获取号码、模拟并审核通话。
OAuth 应用、自定义 API、MCP 服务器和 VoIP 提供商。
报告、可观测性、实验、问题和告警。
邀请和角色、API 密钥、安全性和 SSO。
API 示例：呼入、呼出、动态配置、工具和测试。
一次正确完成 HMAC 校验，随处复用。