Amazon Connect

Översikt

Amazon Connect-integrationen ansluter ett Amazon Connect-kontaktflöde direkt till en agent i ElevenAgents via Amazon Connects protokoll för AI-agenter från tredje part, en utökning av det öppna A2A-protokollet. Amazon Connect hanterar telefoni, dirigering och kön; ElevenAgents hanterar konversationen. Ingen SIP trunk, inget Twilio-nummer eller mellanprogram krävs. AWS dokumenterar funktionen under Agent-till-agent-samarbete; den här guiden beskriver detaljerna för ElevenLabs och de AWS-steg som krävs för att nå en ElevenLabs-agent.

Samma flöde hanterar inkommande samtal och utgående kontakter som startas med StartOutboundVoiceContact. När ElevenLabs-agenten avslutar fortsätter Amazon Connect ditt kontaktflöde och förgrenar utifrån det resultat som den tog emot.

Så fungerar integrationen

1. Ett kontaktflöde når ett Get customer input-block som anropar en Amazon Lex V2-bot med avsikten AMAZON.QInConnectIntent.
2. Amazon Connects orkestreringsagent för AI överlämnar omedelbart konversationen till tredjepartsapplikationen som du har registrerat för ElevenLabs.
3. Amazon Connect öppnar en WebSocket till ElevenLabs-slutpunkten i applikationens AccessUrl, och autentiserar med API-nyckeln som lagras i AWS Secrets Manager.
4. Amazon Connect signalerar att uppringarens kanal är aktiv, sedan utbyter Amazon Connect och ElevenLabs 16-bitars linjärt PCM-ljud som A2A-meddelanden. Amazon Connect föreslår samplingsfrekvensen och ElevenLabs använder den, så inga ändringar av ljudformat krävs för agenten.
5. När agenten avslutar samtalet eller överlämnar uppringaren till en människa avslutar ElevenLabs sessionen med resultatet Complete eller Escalate, och flödet fortsätter från Lex-blocket. Se Överföra till en människa.

Krav

Innan du börjar kontrollerar du att du har:

1. En Amazon Connect-instans på nivån Connect Customer där stöd för AI-agenter från tredje part är aktiverat för kontot och regionen.
2. En Amazon Q in Connect-assistent kopplad till instansen.
3. AWS-behörigheter för att skapa KMS-nycklar, Secrets Manager-hemligheter, AppIntegrations-applikationer, Connect-säkerhetsprofiler, Amazon Q in Connect AI-agenter, Lex V2-botar och kontaktflöden.
4. En ElevenLabs-arbetsyta där Amazon Connect-transporten är aktiverad.
5. En ElevenLabs-agent och en särskild API-nyckel.
6. AWS CLI v2 och awscurl (pip install awscurl) för de anrop vars begärandeformat ännu inte finns i släppta CLI-versioner.

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

Registrera ElevenLabs-applikationen i AWS

Allt i det här avsnittet är ett API-anrop. Ange de värden du kommer att återanvända en gång:

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

Bygg kontaktflödet

{
  "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

Testa integrationen

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_]*"'

Dynamiska variabler

Amazon Connect skickar kontaktens systemattribut med varje session. ElevenLabs exponerar dem, tillsammans med sessionsidentifierarna, som dynamiska variabler:

I Amazon Connect-sessioner är system__caller_id alltid kunden och system__called_number alltid Amazon Connect-numret, både för inkommande och utgående kontakter.

Alla andra delar av kontaktkontexten som Amazon Connect skickar exponeras på samma sätt: kapslade namn sammanfogas med understreck och konverteras till snake case under prefixet amazon_connect_. Anpassade kontaktattribut som anges i flödet med Ange kontaktattribut ingår inte i den kontext som Amazon Connect för närvarande skickar, även när AI-agentens säkerhetsprofil kan visa kontaktattribut. Om AWS börjar inkludera dem visas de automatiskt under samma prefix. Du kan inte välja vilka kontaktdata Amazon Connect delar; AWS skickar en fast uppsättning kontext.

Om du vill skicka ytterligare kontext använder du webhooken för samtalsinitiering. För Amazon Connect-sessioner anropas webhooken innan agenten talar, med caller_id satt till kundens nummer, called_number satt till Amazon Connect-numret och call_id satt till Amazon Connects kontakt-ID. En Lambda i ditt flöde kan därför lagra kontaktattribut nycklade efter kontakt-ID, och webhooken kan returnera dem som dynamiska variabler och konfigurationsåsidosättningar.

Överföra till en människa

Ge agenten systemverktyget Överför till nummer med en amazon_connect-överföringsregel, enligt Konfigurera ElevenLabs. När regelns villkor uppfylls anropar agenten verktyget och ElevenLabs avslutar sessionen med resultatet Escalate och den anledning som agenten angav. Flödets Escalate-gren hanterar sedan kontakten med Ange arbetskö och Överför till kö. Regeln innehåller ingen destination, så kön väljs i flödet, inte av agenten; köhantering, viskningsflöden och agentval stannar i Amazon Connect.

Verktyget Avsluta samtal ger resultatet Complete. Efteranalyssamtal och webhooken efter samtal körs som vanligt efter båda resultaten.

Ge den mänskliga agenten en sammanfattning

Amazon Connect exponerar endast resultatet för ditt flöde: $.Lex.SessionAttributes.Tool (och Lex- intentnamnet) innehåller Escalate, och inget annat från ElevenLabs-sessionen, inte heller överföringsorsaken, når flödet. Om du vill informera människan som tar samtalet måste du själv lagra sammanfattningen på kontakten och låta ett agentviskningsflöde läsa upp den:

1. Exponera en slutpunkt som anropar Amazon Connects UpdateContactAttributes API. En minimal Lambda bakom ett HTTP API räcker; anroparen måste ha behörigheten connect:UpdateContactAttributes för instansens kontakter:

   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. Ge agenten ett webhookverktyg som skickar POST till slutpunkten med contact_id ifyllt från den dynamiska variabeln amazon_connect_contact_id och en summary som modellen skriver. Behåll den delade hemligheten i en arbetsytehemlighet och skicka den som en begärandeheader. I systemprompten instruerar du agenten att anropa detta verktyg först och att anropa Överför till nummer först efter att det har returnerat; en modell som skickar båda anropen i samma tur låter överföringen konkurrera med sammanfattningen. Med den instruktionen fanns attributet på kontakten ungefär en sekund efter agentens begäran i våra tester, tre sekunder innan Amazon Connect återupptog flödet.

3. Lägg i kontaktflödets Escalate-gren till ett block för Ange viskningsflöde före Överför till kö som pekar på ett agentviskningsflöde vars Spela upp prompt läser $.Attributes.handoff_summary. Amazon Connect läser upp den för den mänskliga agenten medan uppringaren hör köhanteringen och kopplar sedan samman dem. Ange inte handoff_summary igen i ett senare block i flödet: ett tomt värde där ersätter det som slutpunkten skrev.

Samma attribut är tillgängligt för ett block för Kontrollera kontaktattribut vid routingbeslut. Webhooken efter samtal utlöses efter att flödet redan har fortsatt, så den passar för CRM-uppdateringar snarare än routingbeslut.

Spårningar

Amazon Connect kräver att externa agenter skickar spårningsdata för varje samarbete. När Amazon Connect prenumererar på spårning för sessionen skickar ElevenLabs en OpenTelemetry-spårning för varje agenttur som innehåller uppringarens transkription, agentens svar, varje verktygsanrop med resultat samt tidsangivelser per spann. Amazon Connect lagrar dessa spårningar med kontakten; se AI-agentspårningar för hur du visar dem. Transkriptioner och verktygsresultat i dessa spårningar omfattas av samma maskeringsinställningar som resten av dina kontaktdata i Amazon Connect, så granska dina krav för uppgiftshantering innan du aktiverar integrationen. Precis som webhooks efter samtal levereras spårningar till dina egna system: agenter i nollagringsläge skickar dem fortfarande, eftersom nolllagring styr vad ElevenLabs lagrar, inte vad din Amazon Connect-instans tar emot.

Ljud

Amazon Connect föreslår 16-bitars mono linjär PCM vid 8, 16 eller 24 kHz för varje session och ElevenLabs använder förslaget, så agentens konfigurerade ljudformat används inte för Amazon Connect-sessioner. Avbrott från uppringaren identifieras av ElevenLabs och rapporteras till Amazon Connect så att buffrad uppspelning töms direkt. Knappsatsinmatning som samlas in av Amazon Connect levereras till agenten som DTMF-siffror. Amazon Connects egen tystnadsmarkör ignoreras; använd agentens turtidsgräns för att uppmana en tyst uppringare igen.

Begränsningar och funktioner som inte stöds

• Klientverktyg och systemverktyget Spela upp knappsatston stöds inte. Överför till nummer fungerar endast genom en Amazon Connect-överföringsregel: agenten kan inte ringa ett telefonnummer eller en SIP-URI från ett Amazon Connect-samtal, och flödet avgör vilken kö som tar emot en eskalerad uppringare.
• Resultat från datainsamling returneras inte till flödet och Amazon Connect avgör vilka kontaktdata som delas. Använd webhooken för samtalsinitiering nycklad med amazon_connect_contact_id för ytterligare kontext, ett webhookverktyg som anropar UpdateContactAttributes för routningsdata och webhooken efter samtal för allt annat.
• Konfigurationsåsidosättningar som system__override_first_message kan inte skickas från flödet. Returnera dem från webhooken för samtalsinitiering i stället.
• Röstsessioner kräver omedelbar överlämning. Amazon Connects chattkanal, textströmning och samarbete i bakgrunden (delegateAgentConfiguration) stöds inte.
• Spårningar som skickas till Amazon Connect omfattar uppringarens transkription, agentens svar, verktygsanrop med resultat och tidsangivelser. Verktygsanropsparametrar ingår inte.
• Amazon Connects stöd för tredjepartsagenter är endast tillgängligt där AWS har aktiverat det och kan medföra ytterligare AWS-kostnader.

Felsökning