Amazon Connect

개요

Amazon Connect 통합은 개방형 A2A 프로토콜의 확장인 Amazon Connect의 타사 AI 에이전트 프로토콜을 통해 Amazon Connect 연락처 흐름을 ElevenAgents의 에이전트에 직접 연결합니다. Amazon Connect는 전화 통신, 라우팅 및 대기열을 담당하며 ElevenAgents는 대화를 담당합니다. SIP 트렁크, Twilio 번호 또는 미들웨어가 필요하지 않습니다. AWS는 이 기능을 에이전트 간 협업에서 문서화하고 있으며, 이 가이드에서는 ElevenLabs 관련 세부 사항과 ElevenLabs 에이전트에 연결하는 데 필요한 AWS 단계를 다룹니다.

동일한 흐름은 StartOutboundVoiceContact로 시작한 수신 통화와 발신 연락 모두에 사용됩니다. ElevenLabs 에이전트가 종료되면 Amazon Connect는 연락처 흐름을 계속 진행하고 수신한 결과에 따라 분기합니다.

통합 작동 방식

1. 연락처 흐름이 AMAZON.QInConnectIntent 인텐트를 사용하는 Amazon Lex V2 봇을 호출하는 고객 입력 가져오기 블록에 도달합니다.
2. Amazon Connect의 오케스트레이션 AI 에이전트가 대화를 즉시 ElevenLabs용으로 등록한 타사 애플리케이션에 전달합니다.
3. Amazon Connect는 AWS Secrets Manager에 저장된 API 키로 인증하여 애플리케이션의 AccessUrl에 있는 ElevenLabs 엔드포인트로 WebSocket을 엽니다.
4. Amazon Connect는 발신자의 채널이 활성 상태임을 알린 후, Amazon Connect와 ElevenLabs는 A2A 메시지로 16비트 선형 PCM 오디오를 교환합니다. Amazon Connect가 샘플 레이트를 제안하고 ElevenLabs가 이를 채택하므로 에이전트에서 오디오 형식을 변경할 필요가 없습니다.
5. 에이전트가 통화를 종료하거나 발신자를 상담원에게 전달하면 ElevenLabs는 Complete 또는 Escalate 결과로 세션을 종료하고 흐름은 Lex 블록부터 계속됩니다. 상담원에게 전달을 참조하세요.

요구 사항

시작하기 전에 다음 항목을 준비하세요:

1. 계정 및 리전에서 타사 AI 에이전트 지원이 활성화된 Connect Customer 티어의 Amazon Connect 인스턴스
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. 아직 릴리스된 CLI 버전에 요청 형식이 없는 호출을 위한 AWS CLI v2 및 awscurl(pip install awscurl)

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가 전송하는 연락처 컨텍스트의 다른 모든 멤버도 같은 방식으로 제공됩니다. 중첩된 이름은 밑줄로 연결되고 amazon_connect_ 접두사 아래 스네이크 케이스로 변환됩니다. 연락처 속성 설정으로 흐름에서 설정한 사용자 지정 연락처 속성은 AI 에이전트의 보안 프로필에서 연락처 속성을 볼 수 있는 경우에도 Amazon Connect가 현재 전송하는 컨텍스트에 포함되지 않습니다. AWS가 이를 포함하기 시작하면 동일한 접두사 아래에 자동으로 표시됩니다. Amazon Connect가 공유할 연락처 데이터는 선택할 수 없으며, AWS는 고정된 컨텍스트 집합을 전달합니다.

추가 컨텍스트를 전달하려면 대화 시작 웹훅을 사용하세요. Amazon Connect 세션에서는 에이전트가 말하기 전에 웹훅이 호출되며, caller_id에는 고객 번호, called_number에는 Amazon Connect 번호, call_id에는 Amazon Connect 연락처 ID가 설정됩니다. 따라서 흐름의 Lambda는 연락처 ID를 키로 하여 연락처 속성을 저장하고, 웹훅은 이를 동적 변수 및 구성 재정의로 반환할 수 있습니다.

사람 상담원에게 전환

ElevenLabs 구성에 표시된 대로 에이전트에 amazon_connect 전환 규칙이 있는 번호로 전환 시스템 도구를 제공하세요. 규칙 조건이 충족되면 에이전트가 도구를 호출하고 ElevenLabs는 에이전트가 제공한 이유와 함께 세션을 Escalate 결과로 종료합니다. 그러면 흐름의 Escalate 분기가 작업 큐 설정 및 큐로 전환을 통해 연락처를 처리합니다. 규칙에는 대상이 없으므로 큐는 에이전트가 아니라 흐름에서 선택합니다. 큐 처리, 위스퍼 흐름 및 상담원 선택은 Amazon Connect에서 유지됩니다.

통화 종료 도구는 Complete 결과를 생성합니다. 두 결과 모두 통화 후 분석 및 통화 후 웹훅은 평소처럼 실행됩니다.

상담원에게 요약 제공

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. amazon_connect_contact_id 동적 변수로 채운 contact_id와 모델이 작성한 summary를 엔드포인트에 POST하는 웹훅 도구를 에이전트에 제공하세요. 공유 시크릿은 워크스페이스 시크릿에 저장하고 요청 헤더로 전송하세요. 시스템 프롬프트에서 에이전트에게 먼저 이 도구를 호출하고, 반환된 후에만 번호로 전환을 호출하도록 지시하세요. 한 턴에 두 호출을 모두 내보내는 모델은 전환과 요약 사이에 경합이 발생합니다. 이 지침을 적용한 테스트에서는 에이전트 요청 후 약 1초 만에 속성이 연락처에 저장되었고, Amazon Connect가 흐름을 재개하기 3초 전이었습니다.

3. 연락처 흐름의 Escalate 분기에서 큐로 전환 전에 위스퍼 흐름 설정 블록을 추가하고, 프롬프트 재생이 $.Attributes.handoff_summary를 읽는 상담원 위스퍼 흐름을 지정하세요. Amazon Connect는 발신자가 큐 처리를 듣는 동안 이를 상담원에게 말한 다음 두 사람을 연결합니다. 흐름의 이후 블록에서 handoff_summary를 다시 설정하지 마세요. 그곳의 빈 값이 엔드포인트에서 작성한 값을 대체합니다.

동일한 속성은 라우팅 결정을 위한 연락처 속성 확인 블록에서도 사용할 수 있습니다. 통화 후 웹훅은 흐름이 이미 계속된 후에 실행되므로 라우팅 결정이 아닌 CRM 업데이트에 적합합니다.

추적

Amazon Connect는 모든 협업에 대해 외부 에이전트가 추적 데이터를 전송하도록 요구합니다. Amazon Connect가 세션의 추적을 구독하면 ElevenLabs는 각 에이전트 턴에 대해 발신자 트랜스크립트, 에이전트 응답, 결과를 포함한 각 도구 호출 및 스팬별 타이밍이 포함된 OpenTelemetry 추적을 전송합니다. Amazon Connect는 이러한 추적을 연락처와 함께 저장합니다. 확인 방법은 AI 에이전트 추적을 참조하세요. 이 추적의 트랜스크립트와 도구 결과에는 Amazon Connect의 나머지 연락처 데이터와 동일한 수정 설정이 적용되므로, 통합을 활성화하기 전에 데이터 처리 요구사항을 검토하세요. 통화 후 웹훅과 마찬가지로 추적은 자체 시스템으로 전송됩니다. 제로 보존 모드의 에이전트도 이를 전송합니다. 제로 보존은 Amazon Connect 인스턴스가 수신하는 데이터가 아니라 ElevenLabs가 저장하는 데이터를 관리하기 때문입니다.

오디오

Amazon Connect는 각 세션에서 8, 16 또는 24kHz의 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를 키로 하는 대화 시작 웹훅을, 라우팅 데이터에는 UpdateContactAttributes를 호출하는 웹훅 도구를, 그 외 모든 작업에는 통화 후 웹훅을 사용하세요.
• system__override_first_message와 같은 구성 재정의는 흐름에서 전달할 수 없습니다. 대신 대화 시작 웹훅에서 반환하세요.
• 음성 세션에는 즉시 핸드오프가 필요합니다. Amazon Connect 채팅 채널, 텍스트 스트리밍 및 백그라운드(delegateAgentConfiguration) 협업은 지원되지 않습니다.
• Amazon Connect로 전송되는 추적에는 발신자의 트랜스크립트, 에이전트의 응답, 결과를 포함한 도구 호출 및 타이밍이 포함됩니다. 도구 호출 매개변수는 포함되지 않습니다.
• Amazon Connect의 타사 에이전트 지원은 AWS가 활성화한 환경에서만 제공되며, 추가 AWS 요금이 발생할 수 있습니다.

문제 해결