> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Amazon Connect > **Warning** > > Amazon Connect 集成目前处于有限可用状态。必须先为 AWS 账户启用 Amazon Connect 的第三方 AI 智能体 > 支持，并且需按工作区启用 ElevenLabs 传输。路由客户流量前，请联系 ElevenLabs 代表。 ## 概述 Amazon Connect 集成通过 Amazon Connect 的第三方 AI 智能体协议（开放式 [A2A protocol](https://a2a-protocol.org/) 的扩展），将 Amazon Connect 联络流程直接连接至 ElevenAgents 中的智能体。Amazon Connect 负责电话、路由和队列；ElevenAgents 负责对话。无需 SIP 中继、Twilio 号码或中间件。AWS 在 [智能体间协作](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html)中记录了此功能； 本指南涵盖 ElevenLabs 的具体配置，以及连接 ElevenLabs 智能体所需的 AWS 步骤。 同一流程适用于呼入和通过 `StartOutboundVoiceContact` 发起的呼出联络。 ElevenLabs 智能体结束后，Amazon Connect 会继续执行联络流程，并根据接收的结果进行分支。 ## 集成的工作方式 1. 联络流程到达一个 **Get customer input** 模块，该模块使用 `AMAZON.QInConnectIntent` 意图调用 Amazon Lex V2 机器人。 2. Amazon Connect 的编排 AI 智能体会立即将对话转交给为 ElevenLabs 注册的第三方应用程序。 3. Amazon Connect 会通过应用程序 `AccessUrl` 中的 ElevenLabs 端点打开 WebSocket， 并使用存储在 AWS Secrets Manager 中的 API 密钥进行身份验证。 4. Amazon Connect 发出提示，表明来电者的渠道已就绪，然后 Amazon Connect 和 ElevenLabs 通过 A2A 消息交换 16 位线性 PCM 音频。Amazon Connect 提议采样率，ElevenLabs 会采用该采样率， 因此无需更改智能体上的音频格式。 5. 智能体结束通话或将来电者转交给人工客服时，ElevenLabs 会以 `Complete` 或 `Escalate` 结果结束会话，流程将从 Lex 模块继续；请参阅 [转交给人工客服](#transferring-to-a-human)。 ## 要求 开始前，请确保具备： 1. 使用 Connect Customer 层级的 Amazon Connect 实例，且账户和 Region 已启用第三方 AI 智能体支持。 2. 与该实例关联的 Amazon Q in Connect 助手。 3. 可创建 KMS 密钥、Secrets Manager 密钥、AppIntegrations 应用程序、 Connect 安全配置文件、Amazon Q in Connect AI 智能体、Lex V2 机器人和联络流程的 AWS 权限。 4. 已启用 Amazon Connect 传输的 ElevenLabs 工作区。 5. 一个 ElevenLabs 智能体和专用 API 密钥。 6. AWS CLI v2 和 [awscurl](https://github.com/okigan/awscurl)（`pip install awscurl`），用于调用 尚未在发布版 CLI 中提供请求结构的接口。 > **Note** > > 所有 AWS 资源必须与 Amazon Connect 实例位于同一账户和 Region。以下步骤会在 AWS CLI 支持调用时使用 AWS CLI， > 在不支持时使用 `awscurl`（经 SigV4 签名的 HTTP 请求）。这些步骤遵循 AWS 的[设置与外部 AI 智能体协作](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html)，并添加 > ElevenLabs 特有的值。 ## 配置 ElevenLabs #### 创建或选择智能体 在 ElevenAgents 中创建智能体。如果希望交接完成后立即说话，请为其设置首条消息； Amazon Connect 在会话期间不会自行播放任何内容。 #### 启用 End call 在 **Agent → Tools → System tools** 中启用 **End call**，以便智能体在解决来电者请求后结束会话。 随后 Amazon Connect 会以 `Complete` 结果继续执行流程。 #### 添加 Amazon Connect 转接规则（可选） 若要让智能体将来电者转交给人工客服，请为其添加 **Transfer to number** 系统工具，并配置一个提供商配置为 `amazon_connect` 的转接规则。该规则没有目标地址：会话会以 `Escalate` 结果结束，由联络流程选择队列。转接规则 通过 API 配置。使用 `PATCH` 将工具添加到智能体： ```bash curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6" \ -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \ -d '{ "conversation_config": {"agent": {"prompt": {"built_in_tools": { "end_call": {"type": "system", "name": "end_call", "description": "", "params": {"system_tool_type": "end_call"}}, "transfer_to_number": { "type": "system", "name": "transfer_to_number", "description": "", "params": { "system_tool_type": "transfer_to_number", "transfers": [], "transfer_rules": [{ "condition": "the caller asks to speak with a human", "provider_configs": [ {"type": "amazon_connect", "config": {"type": "amazon_connect_escalate"}} ] }] } } }}}} }' ``` 请发送智能体完整的 `built_in_tools` 对象，包括已有的工具，例如 `end_call`。 智能体会根据其 `condition` 选择规则；其返回的选项是固定令牌 `amazon_connect`，因此每个工具只需一个 Amazon Connect 规则。为其他提供商配置的电话号码和 SIP URI 不会在 Amazon Connect 通话中提供。 > **Note** > > 转接规则由 API 管理。对于使用此类规则的智能体，请如上所述通过 API 配置和更新 **Transfer to number** 工具； > 控制台的工具编辑器适用于按号码配置的转接列表。 #### 创建专用 API 密钥 在与智能体相同的工作区中创建 API 密钥，并将其限定用于 ElevenAgents。下一部分会将其存储在 AWS Secrets Manager 中； 请勿将其粘贴到其他位置。 #### 记录 WebSocket URL Amazon Connect 连接的 URL 包含智能体 ID： | 环境 | AccessUrl | | ---- | --------------------------------------------------------------------------------------------------------------------- | | 默认 | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | 数据驻留 | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > 如果 ElevenLabs 账户使用独立的数据驻留环境，请将 `` 替换为所在区域代码。有关可用 > 区域，请参阅[数据驻留](/docs/zh/overview/administration/data-residency)。 ## 在 AWS 中注册 ElevenLabs 应用 本节所有操作均通过 API 调用完成。先设置后续会重复使用的值： ```bash export AWS_REGION= # Region of your Amazon Connect instance export ACCOUNT_ID= export INSTANCE_ID= # Amazon Connect instance ID export INSTANCE_ARN=arn:aws:connect:$AWS_REGION:$ACCOUNT_ID:instance/$INSTANCE_ID export AGENT_ID= # ElevenLabs agent ID ``` #### 创建 Amazon Q in Connect 助手 如果实例已有助手，请跳过此步骤。否则，创建一个助手并将其关联到实例： ```bash aws qconnect create-assistant --name elevenlabs-assistant --type AGENT --region $AWS_REGION aws connect create-integration-association --instance-id $INSTANCE_ID \ --integration-type WISDOM_ASSISTANT --integration-arn --region $AWS_REGION ``` 记录助手 ID 和 ARN。 #### 存储 API 密钥 Amazon Connect 使用自己的服务主体从 Secrets Manager 读取密钥，因此密钥必须使用授予 `connect.amazonaws.com` 解密权限的客户托管 KMS 密钥加密。不能使用默认的 `aws/secretsmanager` 密钥。 **`kms-key-policy.json`** ```json title="kms-key-policy.json" { "Version": "2012-10-17", "Statement": [ { "Sid": "AccountAdmin", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "AllowConnectDecrypt", "Effect": "Allow", "Principal": { "Service": "connect.amazonaws.com" }, "Action": ["kms:Decrypt", "kms:DescribeKey"], "Resource": "*" } ] } ``` 将 ElevenLabs API 密钥保存到文件中，避免它出现在 shell 历史记录中，然后创建密钥和密钥： ```bash KMS_KEY_ID=$(aws kms create-key --description "ElevenLabs agent API key" \ --policy file://kms-key-policy.json --region $AWS_REGION \ --query KeyMetadata.KeyId --output text) SECRET_ARN=$(aws secretsmanager create-secret --name elevenlabs/agent-api-key \ --kms-key-id "$KMS_KEY_ID" --secret-string file://elevenlabs-api-key.txt \ --region $AWS_REGION --query ARN --output text) rm elevenlabs-api-key.txt ``` 授予 Amazon Connect 对密钥的读取权限： **`secret-resource-policy.json`** ```json title="secret-resource-policy.json" { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowConnectRead", "Effect": "Allow", "Principal": { "Service": "connect.amazonaws.com" }, "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], "Resource": "" } ] } ``` ```bash aws secretsmanager put-resource-policy --secret-id "$SECRET_ARN" \ --resource-policy file://secret-resource-policy.json --region $AWS_REGION ``` ![使用客户托管密钥加密的 Secrets Manager 密钥及其面向 connect.amazonaws.com 的资源策略](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### 创建第三方应用 将 ElevenLabs WebSocket URL 注册为类型为 `A2A_SERVER` 的 AppIntegrations 应用。此类型必须配置 `AuthConfig`。 **`create-application.json`** ```json title="create-application.json" { "Name": "elevenlabs-agent", "Namespace": "elevenlabs-agent", "Description": "ElevenLabs agent over the Amazon Connect A2A extension", "ApplicationType": "A2A_SERVER", "ApplicationSourceConfig": { "ExternalUrlConfig": { "AccessUrl": "wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/" } }, "AuthConfig": { "AuthType": "API_KEY", "CredentialProviderIdentifier": "" } } ``` ```bash awscurl --service app-integrations --region $AWS_REGION -X POST \ -H 'Content-Type: application/json' --data @create-application.json \ "https://app-integrations.$AWS_REGION.amazonaws.com/applications" ``` 响应中包含应用的 `Id` 和 `Arn`；将它们导出为 `APPLICATION_ID` 和 `APPLICATION_ARN`。Amazon Connect 控制台不会列出 `A2A_SERVER` 应用，因此请通过 API 验证： ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### 将应用关联到实例 ```bash awscurl --service connect --region $AWS_REGION -X PUT -H 'Content-Type: application/json' \ --data "{\"IntegrationArn\": \"$APPLICATION_ARN\", \"IntegrationType\": \"APPLICATION\"}" \ "https://connect.$AWS_REGION.amazonaws.com/instance/$INSTANCE_ID/integration-associations" aws connect list-integration-associations --instance-id $INSTANCE_ID \ --integration-type APPLICATION --region $AWS_REGION ``` #### 在安全配置文件中允许该应用 附加到编排 AI 智能体的安全配置文件必须在允许的 AI 智能体中列出该应用，否则运行时交接会失败。 ```bash SECURITY_PROFILE_ID=$(aws connect create-security-profile --instance-id $INSTANCE_ID \ --security-profile-name elevenlabs-a2a --permissions QConnectAIAgents.View Wisdom.View \ --region $AWS_REGION --query SecurityProfileId --output text) awscurl --service connect --region $AWS_REGION -X POST -H 'Content-Type: application/json' \ --data "{\"AllowedAIAgents\": [{\"Arn\": \"$APPLICATION_ARN\", \"Type\": \"THIRD_PARTY\"}]}" \ "https://connect.$AWS_REGION.amazonaws.com/security-profiles/$INSTANCE_ID/$SECURITY_PROFILE_ID" ``` 管理网站会显示配置文件及其权限，但不会显示允许的 AI 智能体；这些信息只能通过 API 查看。 ![Amazon Connect 管理网站中的专用安全配置文件，具有 AI 智能体查看 权限](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### 创建并发布编排 AI 智能体 编排智能体会立即将每段语音对话交给应用处理，并启用音频流。语音会话需要立即交接；ElevenLabs 不支持文本流（`audioStreamingEnabled` 设为 false）和 `delegateAgentConfiguration`。音频立即交接编排器还必须在 `toolConfigurations` 中声明类型为 `RETURN_TO_CONTROL` 的保留 `Complete` 工具；否则创建请求会失败，并显示 `An audio frontline orchestrator (with an audio immediate handoff) must configure the reserved 'Complete' RETURN_TO_CONTROL tool`。 **`create-ai-agent.json`** ```json title="create-ai-agent.json" { "name": "elevenlabs-handoff", "type": "ORCHESTRATION", "visibilityStatus": "PUBLISHED", "configuration": { "orchestrationAIAgentConfiguration": { "connectInstanceArn": "", "locale": "en_US", "multiAgentConfigurations": [ { "handoffAgentConfiguration": { "agentTarget": { "applicationId": "" }, "instruction": { "instruction": "Immediately hand off every voice conversation to the ElevenLabs agent." }, "audioStreamingEnabled": true, "immediateHandoff": true } } ], "toolConfigurations": [ { "toolName": "Complete", "toolType": "RETURN_TO_CONTROL", "description": "Close the conversation when the customer has no more questions.", "instruction": { "instruction": "Mark the conversation as complete when the customer has no additional questions or needs." }, "inputSchema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for completion" } }, "required": ["reason"] }, "userInteractionConfiguration": { "isUserConfirmationRequired": false } } ] } } } ``` ```bash awscurl --service wisdom --region $AWS_REGION -X POST -H 'Content-Type: application/json' \ --data @create-ai-agent.json \ "https://wisdom.$AWS_REGION.amazonaws.com/assistants//aiagents" aws qconnect create-ai-agent-version --assistant-id \ --ai-agent-id --region $AWS_REGION ``` 发布会返回带版本的 ARN（`:1`）；联系流会引用它。将安全配置文件附加到未带版本和带版本的智能体： ```bash for ARN in :1; do aws connect associate-security-profiles --instance-id $INSTANCE_ID --entity-arn "$ARN" \ --entity-type AI_AGENT --security-profiles Id=$SECURITY_PROFILE_ID --region $AWS_REGION done ``` ![AI 智能体设计器中的编排 AI 智能体，已附加专用安全配置文件 ](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## 构建联系流 #### 创建 Lex 机器人 1. 创建一个 Lex V2 机器人，其唯一意图为内置 `AMAZON.QInConnectIntent`，并配置助手 ARN。不要添加其他意图。 2. 在机器人区域设置中启用语音转语音。双向音频流仅适用于 Sonic 语音转语音机器人。 3. 允许机器人的 IAM 角色使用该助手。否则，交接会在任何请求到达 ElevenLabs 前于 AWS 内部失败，并显示 `HTTP 403`。附加类似以下策略： **`lex-role-policy.json`** ```json title="lex-role-policy.json" { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["wisdom:CreateSession", "wisdom:GetAssistant"], "Resource": ["", "/*"] }, { "Effect": "Allow", "Action": ["wisdom:SendMessage", "wisdom:GetNextMessage"], "Resource": "arn:aws:wisdom:::session//*" } ] } ``` 4. 构建机器人，创建版本和别名，并将别名关联到实例： ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Lex V2 机器人意图列表，包含 Q in Connect 交接意图和内置回退 意图](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### 添加助手和 Lex 模块 在流设计器中，按以下顺序添加模块： 1. **设置日志记录行为**：启用。通过流日志验证下面的交接。 2. **连接助手**：选择 Amazon Q in Connect 助手。 3. **获取客户输入**：在 **Amazon Lex** 标签中选择 **输入 ARN**，然后粘贴机器人别名 ARN。将文本转语音提示保留为一个空格，以便 Amazon Connect 在交接前不播放任何内容。在 **会话属性** 下，手动添加两个属性： | 目标键 | 值 | | ------------------------------------- | ----------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | 带版本的编排智能体 ARN（`...:1`）。 | | `x-amz-lex:qic-audio-passthrough` | `true` | ![获取客户输入模块的会话属性：带版本的 AI 智能体 ARN 和音频 直通标记](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` 在 AWS 预发布期间控制第三方语音路径。AWS 表示该功能公开后不再需要此属性；保留它也不会有影响。 #### 按结果分支 Amazon Connect 会将 ElevenLabs 的结果以 `$.Lex.SessionAttributes.Tool` 属性形式提供给流。在 Lex 模块后添加 **检查联系属性** 模块，将 **命名空间** 设为 **Lex**、**键** 设为 **会话属性**、**会话属性键** 设为 `Tool`，然后为每个结果添加一个 **等于** 条件，并将 **无匹配** 路由至错误提示： | 分支 | 含义 | 建议路由 | | ---------- | ----------------------------------------------- | -------------- | | `Complete` | 智能体结束了通话，例如使用 **结束通话** 工具。 | 断开连接 | | `Escalate` | 智能体请求人工协助（请参阅[转接人工](#transferring-to-a-human)）。 | 设置工作队列 → 转接至队列 | | 无匹配 | 任何其他值。 | 播放提示 → 断开连接 | ![检查联系属性模块配置为使用 Lex 会话属性 Tool，并针对每种结果设置 等于条件](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connect 将结果写为标题格式（`Escalate`、`Complete`），而不是在线路中发送的全大写结束类型，因此模块只需这两个条件。交接后失败的会话会以 `COMPLETE_WITH_ERROR` 类型结束；Lex 模块随后会采用其 **错误** 输出，或比较会落入 **无匹配**，因此两者都应路由到错误提示。在导出的流中，Lex 模块的 **默认** 输出是其 `NoMatchingCondition` 转换；请确保它通向比较模块，而非错误消息。 ![联系流中，获取客户输入模块连接至检查联系属性模块，后者将 Escalate 路由至队列、Complete 路由至断开连接、无匹配路由至错误 提示](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### 发布并分配 发布流，然后将已认领的电话号码指向该流： ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` 对于外呼，使用同一流发起联系；Amazon Connect 会呼叫客户，并将已接通的通话交给 ElevenLabs： ```bash aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \ --contact-flow-id --destination-phone-number \ --source-phone-number --region $AWS_REGION ``` ## 测试集成 #### 拨打电话 拨打该号码。流进入 Lex 模块几秒后，智能体的第一条消息便会播放；AWS 内部交接大约需要 3 秒，之后才会联系 ElevenLabs。进行一段简短对话后说再见：智能体会调用 **结束通话**，ElevenLabs 会话以 `Complete` 结束，流将从 Lex 模块继续执行。如果添加了转接规则，则请求人工协助：智能体会调用 **转接至号码**，会话以 `Escalate` 结束，流会进入相应分支。 #### 在 ElevenLabs 中查看对话 在 **对话** 中打开对话。其来源为 Amazon Connect，**客户端数据** 标签会列出会话收到的 `amazon_connect_*` 动态变量。 ![Amazon Connect 对话的客户端数据标签，列出了 Amazon Connect 动态 变量](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### 在 AWS 中检查流日志 启用日志记录后，每个模块都会向实例的流日志组写入条目。**获取客户输入** 模块会记录从 ElevenLabs 收到的结果： ```bash aws logs filter-log-events --log-group-name /aws/connect/ \ --start-time $(( $(date +%s) - 600 ))000 --region $AWS_REGION \ --query 'events[].message' --output text | tr '\t' '\n' | grep -o '"Results": *"[A-Za-z_]*"' ``` 对于 Lex 模块，应显示 `"Results": "Complete"`；转接后应显示 `"Results": "Escalate"`，随后是该分支上的模块。 ## 动态变量 Amazon Connect 会在每个会话中发送联系人的系统属性。ElevenLabs 会将它们以及会话标识符作为动态变量提供： | 动态变量 | 说明 | | ------------------------------------------------------------ | --------------------------------- | | `system__caller_id` | 客户的电话号码（Amazon Connect 客户端终端）。 | | `system__called_number` | 联系人所在的 Amazon Connect 电话号码（系统终端）。 | | `system__call_id` | Amazon Connect 联系 ID。 | | `amazon_connect_system_attributes_channel` | 联系渠道，例如 `VOICE`。 | | `amazon_connect_system_attributes_customer_endpoint_address` | Amazon Connect 发送的客户端终端地址。 | | `amazon_connect_system_attributes_system_endpoint_address` | Amazon Connect 发送的系统终端地址。 | | `amazon_connect_interaction_mode` | 协作模式，例如 `HANDOFF`。 | | `amazon_connect_contact_id` | Amazon Connect 联系 ID。 | | `amazon_connect_contact_arn` | 完整联系 ARN。 | | `amazon_connect_context_id` | A2A 会话（上下文）ID。 | | `amazon_connect_instance_id` | 实例 ID。 | | `amazon_connect_instance_arn` | 实例 ARN。 | 在 Amazon Connect 会话中，无论呼入还是呼出联系，`system__caller_id` 始终是客户，`system__called_number` 始终是 Amazon Connect 号码。 Amazon Connect 发送的联系上下文中的其他成员也会以相同方式提供：嵌套名称以连字符连接并转换为 snake case，置于 `amazon_connect_` 前缀下。即使 AI 智能体的安全配置文件可查看联系属性，通过 **设置联系属性** 在流中设置的自定义联系属性也不属于 Amazon Connect 当前发送的上下文；如果 AWS 开始包含它们，它们会自动以相同前缀出现。无法选择 Amazon Connect 共享哪些联系数据；AWS 会传递一组固定上下文。 如需传递额外上下文，请使用[对话发起 webhook](/docs/zh/eleven-agents/customization/personalization#conversation-initiation-webhooks)。对于 Amazon Connect 会话，webhook 会在智能体发言前调用，其中 `caller_id` 设为客户号码、`called_number` 设为 Amazon Connect 号码、`call_id` 设为 Amazon Connect 联系 ID。因此，流中的 Lambda 可以按联系 ID 存储联系属性，而 webhook 可将它们作为动态变量和配置覆盖项返回。 ## 转接人工 如[配置 ElevenLabs](#configure-elevenlabs)所示，为智能体提供带有 `amazon_connect` 转接规则的 **转接至号码** 系统工具。满足规则条件时，智能体会调用该工具，ElevenLabs 将以 `Escalate` 结果及智能体提供的原因结束会话。随后，流的 `Escalate` 分支会通过 **设置工作队列** 和 **转接至队列** 处理该联系。规则不包含目标位置，因此由流而非智能体选择队列；队列处理、耳语流和客服选择仍由 Amazon Connect 负责。 **结束通话** 工具会产生 `Complete` 结果。无论哪种结果，通话后分析和通话后 webhook 都会照常运行。 ### 向人工客服提供摘要 Amazon Connect 仅向流提供结果：`$.Lex.SessionAttributes.Tool`（以及 Lex 意图名称）包含 `Escalate`，ElevenLabs 会话中的其他信息，包括转接原因，都不会传递给流。若要向接听电话的人工客服简要说明情况，请自行将摘要存储在联系中，并让客服耳语流读出： 1. 提供一个调用 Amazon Connect `UpdateContactAttributes` API 的端点。HTTP API 后的精简 Lambda 即可；调用方必须拥有实例联系的 `connect:UpdateContactAttributes` 权限： ```python import json, os, boto3 connect = boto3.client("connect") def handler(event, _context): if (event.get("headers") or {}).get("x-shared-secret") != os.environ["SHARED_SECRET"]: return {"statusCode": 401, "body": ""} body = json.loads(event.get("body") or "{}") connect.update_contact_attributes( InstanceId=os.environ["INSTANCE_ID"], InitialContactId=body["contact_id"], Attributes={"handoff_summary": body["summary"][:1000]}, ) return {"statusCode": 200, "body": json.dumps({"ok": True})} ``` 2. 为智能体提供一个[webhook 工具](/docs/zh/eleven-agents/customization/tools/webhook-tools)，该工具向端点 `POST` 请求，其中 `contact_id` 从 `amazon_connect_contact_id` 动态变量填充，`summary` 由模型撰写。将共享密钥保存在工作区密钥中，并将其作为请求标头发送。在系统提示词中，指示智能体先调用该工具，只有在其返回后才调用 **转接至号码**；若模型在同一轮中同时发出两个调用，转接会与摘要写入发生竞争。根据我们的测试，遵循该指示后，属性会在智能体请求约 1 秒后写入联系，比 Amazon Connect 恢复流早 3 秒。 3. 在联系流的 `Escalate` 分支中，在 **转接至队列** 前添加 **设置耳语流** 模块，使其指向一个客服耳语流，该流的 **播放提示** 读取 `$.Attributes.handoff_summary`。当呼叫者听取队列处理时，Amazon Connect 会向人工客服播放该内容，然后接通双方。不要在流后续模块中再次设置 `handoff_summary`：那里的空值会覆盖端点写入的内容。 同一属性也可供 **检查联系属性** 模块用于路由决策。通话后 webhook 会在流已继续执行后才触发，因此适合 CRM 更新，而不适合路由决策。 ## 跟踪 Amazon Connect [要求外部智能体为每次协作发送跟踪数据](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html)。当 Amazon Connect 订阅会话跟踪时，ElevenLabs 会为每个智能体轮次发送一个 OpenTelemetry 跟踪，其中包含呼叫者的转录文本、智能体响应、每次工具调用及其结果，以及每个跨度的耗时。Amazon Connect 会将这些跟踪与联系一起存储；有关查看方式，请参阅 [AI 智能体跟踪](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html)。这些跟踪中的转录文本和工具结果适用与 Amazon Connect 中其他联系数据相同的脱敏设置，因此启用集成前请审查数据处理要求。与[通话后 webhook](/docs/zh/eleven-agents/workflows/post-call-webhooks)一样，跟踪会传送至你自己的系统：处于[零保留模式](/docs/zh/eleven-agents/customization/privacy/zrm)的智能体仍会发送跟踪，因为零保留模式管理的是 ElevenLabs 存储的内容，而不是 Amazon Connect 实例接收的内容。 ## 音频 Amazon Connect 会在每个会话中提议使用 8、16 或 24 kHz 的 16 位单声道线性 PCM，ElevenLabs 会采用该提议，因此智能体配置的音频格式不适用于 Amazon Connect 会话。ElevenLabs 会检测呼叫者插话，并向 Amazon Connect 报告，使缓冲播放立即清除。Amazon Connect 收集的按键输入会以 DTMF 数字形式传送给智能体。Amazon Connect 自身的静音标记会被忽略；请使用智能体的轮次超时重新提示安静的呼叫者。 ## 限制和不支持的功能 * 不支持客户端工具和 **播放键盘触摸音** 系统工具。**转接至号码** 仅可通过 Amazon Connect 转接规则使用：智能体无法从 Amazon Connect 通话中拨打电话号码或 SIP URI，且由流决定升级呼叫者将进入哪个队列。 * 数据收集结果不会返回至流，且由 Amazon Connect 决定共享哪些联系数据。额外上下文请使用以 `amazon_connect_contact_id` 为键的对话发起 webhook；路由数据请使用调用 `UpdateContactAttributes` 的 webhook 工具；其他所有内容请使用通话后 webhook。 * 无法从流中传递 `system__override_first_message` 等配置覆盖项。请改为从对话发起 webhook 返回它们。 * 语音会话需要立即交接。不支持 Amazon Connect 聊天渠道、文本流和后台（`delegateAgentConfiguration`）协作。 * 发送至 Amazon Connect 的跟踪涵盖呼叫者转录文本、智能体响应、工具调用及其结果和时序。不包含工具调用参数。 * Amazon Connect 的第三方智能体支持仅在 AWS 启用该功能的区域提供，并且可能产生额外 AWS 费用。 ## 故障排除 #### 流程失败并显示“A2A WebSocket upgrade ... failed (HTTP 403)” * 此错误在请求到达 ElevenLabs 前由 AWS 内部引发。请在 CloudTrail 中检查 Lex 服务角色是否出现 `wisdom:SendMessage` 的 `AccessDenied`：附加到机器人的角色需要对助手及其会话拥有 `wisdom:CreateSession`、`wisdom:GetAssistant`、`wisdom:SendMessage` 和 `wisdom:GetNextMessage` 权限。 * 确认安全配置文件允许该应用，并且已关联到流程引用的已发布编排智能体版本。 * 确认密钥的 KMS 密钥和资源策略已授予 `connect.amazonaws.com` 访问权限。 #### 流程失败并显示“the hand-off to the target agent could not be completed” * Amazon Connect 为建立 WebSocket 连接预留约 20 秒。确认 AWS 可以访问 `AccessUrl`：使用 `wss://`、智能体 ID 正确，且未被网络允许列表阻拦。 * 如果通过自有基础设施代理连接，请保持代理预热。冷启动的无服务器实例可能需要超过交接窗口的时间，Amazon Connect 会在 ElevenLabs 收到请求前放弃。 #### Lex 模块进入 Error 分支，来电者听不到任何内容 * 确认 **Get customer input** 模块上已设置这两个会话属性： `x-amz-lex:q-in-connect:ai-agent-arn` 应使用已发布且带版本号的智能体 ARN， `x-amz-lex:qic-audio-passthrough` 应设为 `true`。 * 确认允许该应用的安全配置文件已附加到该智能体版本。 * 查看流程日志中该模块的条目，其中包含 Amazon Connect 遇到的错误。 #### 连接后会话立即结束 * 确认 `AccessUrl` 使用 `wss://`、包含正确的智能体 ID，并指向工作区所在区域。 * 确认 API 密钥处于活跃状态、属于智能体所在工作区，且没有 IP 限制。 * 确认工作区已启用 Amazon Connect 传输方式。 #### 智能体结束后，来电者听到流程的错误提示 在 Lex 模块中，确保 **Default** 输出通向比较 `$.Lex.SessionAttributes.Tool` 的模块，并与标题格式的值 `Escalate` 和 `Complete` 进行比较。 #### 智能体始终不说话，几秒后会话结束 确认协作者已配置 `audioStreamingEnabled` 为 true。使用文本 流式传输时，Amazon Connect 会发送文本轮次并期待文本响应，而 ElevenLabs 不支持此方式；ElevenLabs 日志会显示 `INIT_SESSION carries no audio configuration`。 #### 缺少动态变量 Amazon Connect 会提供上述联系系统属性和标识符。在流程中设置的自定义联系 属性无法传递给智能体；请改为通过会话启动 webhook 传递。如果智能体的首条消息或提示词引用了从未 提供的变量，会话会在启动时失败。