Amazon Connect

概述

Amazon Connect 集成通过 Amazon Connect 的第三方 AI 智能体协议（开放式 A2A protocol 的扩展），将 Amazon Connect 联络流程直接连接至 ElevenAgents 中的智能体。Amazon Connect 负责电话、路由和队列；ElevenAgents 负责对话。无需 SIP 中继、Twilio 号码或中间件。AWS 在 智能体间协作中记录了此功能； 本指南涵盖 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 模块继续；请参阅 转交给人工客服。

要求

开始前，请确保具备：

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（pip install awscurl），用于调用 尚未在发布版 CLI 中提供请求结构的接口。

配置 ElevenLabs

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"}}
            ]
          }]
        }
      }
    }}}}
  }'

在 AWS 中注册 ElevenLabs 应用

本节所有操作均通过 API 调用完成。先设置后续会重复使用的值：

export AWS_REGION=<REGION>          # Region of your Amazon Connect instance
export ACCOUNT_ID=<ACCOUNT_ID>
export INSTANCE_ID=<INSTANCE_ID>    # Amazon Connect instance ID
export INSTANCE_ARN=arn:aws:connect:$AWS_REGION:$ACCOUNT_ID:instance/$INSTANCE_ID
export AGENT_ID=<AGENT_ID>          # ElevenLabs agent ID

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 <ASSISTANT_ARN> --region $AWS_REGION

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccountAdmin",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<ACCOUNT_ID>:root" },
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "AllowConnectDecrypt",
      "Effect": "Allow",
      "Principal": { "Service": "connect.amazonaws.com" },
      "Action": ["kms:Decrypt", "kms:DescribeKey"],
      "Resource": "*"
    }
  ]
}

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

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowConnectRead",
      "Effect": "Allow",
      "Principal": { "Service": "connect.amazonaws.com" },
      "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
      "Resource": "<SECRET_ARN>"
    }
  ]
}

aws secretsmanager put-resource-policy --secret-id "$SECRET_ARN" \
  --resource-policy file://secret-resource-policy.json --region $AWS_REGION

{
  "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/<AGENT_ID>"
    }
  },
  "AuthConfig": {
    "AuthType": "API_KEY",
    "CredentialProviderIdentifier": "<SECRET_ARN>"
  }
}

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"

aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION

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

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"

{
  "name": "elevenlabs-handoff",
  "type": "ORCHESTRATION",
  "visibilityStatus": "PUBLISHED",
  "configuration": {
    "orchestrationAIAgentConfiguration": {
      "connectInstanceArn": "<INSTANCE_ARN>",
      "locale": "en_US",
      "multiAgentConfigurations": [
        {
          "handoffAgentConfiguration": {
            "agentTarget": { "applicationId": "<APPLICATION_ARN>" },
            "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 }
        }
      ]
    }
  }
}

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/<ASSISTANT_ID>/aiagents"
aws qconnect create-ai-agent-version --assistant-id <ASSISTANT_ID> \
  --ai-agent-id <AI_AGENT_ID> --region $AWS_REGION

for ARN in <AI_AGENT_ARN> <AI_AGENT_ARN>: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

构建联系流

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["wisdom:CreateSession", "wisdom:GetAssistant"],
      "Resource": ["<ASSISTANT_ARN>", "<ASSISTANT_ARN>/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["wisdom:SendMessage", "wisdom:GetNextMessage"],
      "Resource": "arn:aws:wisdom:<REGION>:<ACCOUNT_ID>:session/<ASSISTANT_ID>/*"
    }
  ]
}

aws connect associate-bot --instance-id $INSTANCE_ID \
  --lex-v2-bot AliasArn=<LEX_ALIAS_ARN> --region $AWS_REGION

aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \
  --phone-number-id <PHONE_NUMBER_ID> --contact-flow-id <CONTACT_FLOW_ID> --region $AWS_REGION

aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \
  --contact-flow-id <CONTACT_FLOW_ID> --destination-phone-number <E164_NUMBER> \
  --source-phone-number <YOUR_CONNECT_NUMBER> --region $AWS_REGION

测试集成

aws logs filter-log-events --log-group-name /aws/connect/<INSTANCE_ALIAS> \
  --start-time $(( $(date +%s) - 600 ))000 --region $AWS_REGION \
  --query 'events[].message' --output text | tr '\t' '\n' | grep -o '"Results": *"[A-Za-z_]*"'

动态变量

Amazon Connect 会在每个会话中发送联系人的系统属性。ElevenLabs 会将它们以及会话标识符作为动态变量提供：

在 Amazon Connect 会话中，无论呼入还是呼出联系，system__caller_id 始终是客户，system__called_number 始终是 Amazon Connect 号码。

Amazon Connect 发送的联系上下文中的其他成员也会以相同方式提供：嵌套名称以连字符连接并转换为 snake case，置于 amazon_connect_ 前缀下。即使 AI 智能体的安全配置文件可查看联系属性，通过 设置联系属性 在流中设置的自定义联系属性也不属于 Amazon Connect 当前发送的上下文；如果 AWS 开始包含它们，它们会自动以相同前缀出现。无法选择 Amazon Connect 共享哪些联系数据；AWS 会传递一组固定上下文。

如需传递额外上下文，请使用对话发起 webhook。对于 Amazon Connect 会话，webhook 会在智能体发言前调用，其中 caller_id 设为客户号码、called_number 设为 Amazon Connect 号码、call_id 设为 Amazon Connect 联系 ID。因此，流中的 Lambda 可以按联系 ID 存储联系属性，而 webhook 可将它们作为动态变量和配置覆盖项返回。

转接人工

如配置 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 权限：

   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 工具，该工具向端点 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 要求外部智能体为每次协作发送跟踪数据。当 Amazon Connect 订阅会话跟踪时，ElevenLabs 会为每个智能体轮次发送一个 OpenTelemetry 跟踪，其中包含呼叫者的转录文本、智能体响应、每次工具调用及其结果，以及每个跨度的耗时。Amazon Connect 会将这些跟踪与联系一起存储；有关查看方式，请参阅 AI 智能体跟踪。这些跟踪中的转录文本和工具结果适用与 Amazon Connect 中其他联系数据相同的脱敏设置，因此启用集成前请审查数据处理要求。与通话后 webhook一样，跟踪会传送至你自己的系统：处于零保留模式的智能体仍会发送跟踪，因为零保留模式管理的是 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 费用。

故障排除