Amazon Connect

Overzicht

De Amazon Connect-integratie verbindt een Amazon Connect-contactflow rechtstreeks met een agent in ElevenAgents via het protocol voor externe AI-agents van Amazon Connect, een uitbreiding van het open A2A-protocol. Amazon Connect beheert telefonie, routering en de wachtrij; ElevenAgents beheert het gesprek. Er is geen SIP-trunk, Twilio-nummer of middleware vereist. AWS documenteert de functie onder Agent-to-agent collaboration; deze handleiding behandelt de ElevenLabs-specifieke aspecten en de AWS-stappen die nodig zijn om een ElevenLabs-agent te bereiken.

Dezelfde flow bedient inkomende gesprekken en uitgaande contacten die zijn gestart met StartOutboundVoiceContact. Wanneer de ElevenLabs-agent klaar is, vervolgt Amazon Connect je contactflow en vertakt op basis van de ontvangen uitkomst.

Zo werkt de integratie

1. Een contactflow bereikt een blok Get customer input dat een Amazon Lex V2-bot aanroept met de intent AMAZON.QInConnectIntent.
2. De orkestratie-AI-agent van Amazon Connect draagt het gesprek direct over aan de externe applicatie die je voor ElevenLabs hebt geregistreerd.
3. Amazon Connect opent een WebSocket naar het ElevenLabs-endpoint in de AccessUrl van de applicatie, en verifieert met de API-sleutel die is opgeslagen in AWS Secrets Manager.
4. Amazon Connect geeft aan dat het kanaal van de beller actief is. Vervolgens wisselen Amazon Connect en ElevenLabs 16-bits lineaire PCM-audio uit als A2A-berichten. Amazon Connect stelt de samplefrequentie voor en ElevenLabs neemt die over, dus er zijn geen wijzigingen aan het audioformaat nodig op de agent.
5. Wanneer de agent het gesprek beëindigt of de beller overdraagt aan een medewerker, beëindigt ElevenLabs de sessie met een Complete- of Escalate-uitkomst en gaat de flow verder vanaf het Lex-blok; zie Overdragen aan een medewerker.

Vereisten

Controleer voordat je begint of je het volgende hebt:

1. Een Amazon Connect-instance op de Connect Customer-tier met ondersteuning voor externe AI-agents ingeschakeld voor het account en de Region.
2. Een Amazon Q in Connect-assistent die is gekoppeld aan de instance.
3. AWS-machtigingen om KMS-sleutels, Secrets Manager-secrets, AppIntegrations-applicaties, Connect-beveiligingsprofielen, Amazon Q in Connect AI-agents, Lex V2-bots en contactflows te maken.
4. Een ElevenLabs-workspace met het Amazon Connect-transport ingeschakeld.
5. Een ElevenLabs-agent en een speciale API-sleutel.
6. AWS CLI v2 en awscurl (pip install awscurl) voor de aanroepen waarvan de requeststructuur nog niet in uitgebrachte CLI-versies staat.

ElevenLabs configureren

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

Registreer de ElevenLabs-applicatie in AWS

Alles in deze sectie is een API-aanroep. Stel de waarden die je opnieuw gebruikt één keer in:

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

Bouw de contactflow

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

Test de integratie

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

Dynamische variabelen

Amazon Connect verzendt de systeemattributen van het contact bij elke sessie. ElevenLabs maakt deze, samen met de sessie-ID’s, beschikbaar als dynamische variabelen:

In Amazon Connect-sessies is system__caller_id altijd de klant en system__called_number altijd het Amazon Connect-nummer, voor zowel inkomende als uitgaande contacten.

Elk ander lid van de contactcontext dat Amazon Connect verzendt, wordt op dezelfde manier beschikbaar gemaakt: geneste namen worden met underscores samengevoegd en omgezet naar snake case onder het voorvoegsel amazon_connect_. Aangepaste contactattributen die je in je flow instelt met Contactattributen instellen, maken geen deel uit van de context die Amazon Connect momenteel verzendt, zelfs niet wanneer het beveiligingsprofiel van de AI-agent contact- attributen mag bekijken; als AWS deze gaat opnemen, verschijnen ze automatisch onder hetzelfde voorvoegsel. Je kunt niet kiezen welke contactgegevens Amazon Connect deelt; AWS geeft een vaste set context door.

Gebruik voor aanvullende context de webhook voor gespreksinitiatie. Voor Amazon Connect-sessies wordt de webhook aangeroepen voordat de agent spreekt, met caller_id ingesteld op het nummer van de klant, called_number ingesteld op het Amazon Connect-nummer en call_id ingesteld op de Amazon Connect-contact-ID. Een Lambda in je flow kan contactattributen dus opslaan op basis van de contact-ID, en de webhook kan ze teruggeven als dynamische variabelen en configuratieoverschrijvingen.

Overdragen aan een persoon

Geef de agent de systeemtool Overdragen naar nummer met een amazon_connect-overdrachtsregel, zoals weergegeven in ElevenLabs configureren. Wanneer aan de voorwaarde van de regel is voldaan, roept de agent de tool aan en beëindigt ElevenLabs de sessie met de uitkomst Escalate en de reden die de agent heeft opgegeven. De vertakking Escalate van je flow verwerkt het contact vervolgens met Werkqueue instellen en Overdragen naar queue. De regel bevat geen bestemming, dus de queue wordt in de flow gekozen en niet door de agent; queuebehandeling, whisperflows en agentselectie blijven in Amazon Connect.

De tool Gesprek beëindigen geeft de uitkomst Complete. Analyse na het gesprek en de webhook na het gesprek worden na beide uitkomsten zoals gebruikelijk uitgevoerd.

De menselijke agent een samenvatting geven

Amazon Connect maakt alleen de uitkomst beschikbaar voor je flow: $.Lex.SessionAttributes.Tool (en de Lex- intentnaam) bevatten Escalate, en niets anders van de ElevenLabs-sessie, ook de overdrachtsreden niet, bereikt de flow. Om de persoon die het gesprek aanneemt te informeren, sla je de samenvatting zelf op bij het contact en laat je een agent-whisperflow deze voorlezen:

1. Maak een endpoint dat de UpdateContactAttributes-API van Amazon Connect aanroept. Een minimale Lambda achter een HTTP API volstaat; de aanroeper moet connect:UpdateContactAttributes mogen gebruiken voor de contacten van de instance:

   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. Geef de agent een webhooktool die een POST uitvoert naar dat endpoint met contact_id ingevuld vanuit de dynamische variabele amazon_connect_contact_id en een summary die het model schrijft. Bewaar het gedeelde geheim in een workspacegeheim en verstuur dit als requestheader. Geef de agent in de systeemprompt de instructie om deze tool eerst aan te roepen en Overdragen naar nummer pas aan te roepen nadat deze is teruggekeerd; een model dat beide aanroepen in één beurt uitvoert, laat de overdracht concurreren met de samenvatting. Met deze instructie stond het attribuut in onze tests ongeveer een seconde na het request van de agent op het contact, drie seconden voordat Amazon Connect de flow hervatte.

3. Voeg in de vertakking Escalate van de contactflow vóór Overdragen naar queue een blok Whisperflow instellen toe dat verwijst naar een agent-whisperflow waarvan Prompt afspelen $.Attributes.handoff_summary voorleest. Amazon Connect spreekt dit uit voor de menselijke agent terwijl de beller de queuebehandeling hoort, en verbindt vervolgens beide. Stel handoff_summary niet opnieuw in een later blok van de flow in: een lege waarde daar vervangt wat het endpoint heeft geschreven.

Hetzelfde attribuut is beschikbaar voor een blok Contactattributen controleren voor routeringsbeslissingen. De webhook na het gesprek wordt geactiveerd nadat de flow al verder is gegaan, en is daarom geschikt voor CRM-updates in plaats van routeringsbeslissingen.

Traces

Amazon Connect vereist dat externe agents tracedata verzenden voor elke samenwerking. Wanneer Amazon Connect zich abonneert op tracing voor de sessie, verzendt ElevenLabs voor elke agentbeurt een OpenTelemetry-trace met het transcript van de beller, de reactie van de agent, elke toolaanroep met het resultaat en de timing per span. Amazon Connect slaat deze traces op bij het contact; zie AI-agenttraces voor informatie over hoe je deze kunt bekijken. Transcripten en toolresultaten in deze traces vallen onder dezelfde redactie-instellingen als de rest van je contactgegevens in Amazon Connect. Controleer daarom je vereisten voor gegevensverwerking voordat je de integratie inschakelt. Net als webhooks na het gesprek worden traces geleverd aan je eigen systemen: agents in zero retention mode verzenden ze nog steeds, omdat zero retention bepaalt wat ElevenLabs opslaat en niet wat je Amazon Connect-instance ontvangt.

Audio

Amazon Connect stelt voor elke sessie 16-bits mono lineaire PCM op 8, 16 of 24 kHz voor en ElevenLabs accepteert het voorstel. De geconfigureerde audioformaten van de agent worden dus niet gebruikt voor Amazon Connect- sessies. Onderbreking door de beller wordt gedetecteerd door ElevenLabs en gemeld aan Amazon Connect, zodat gebufferde afspeelcontent onmiddellijk wordt gewist. Toetsenbordinvoer die Amazon Connect verzamelt, wordt als DTMF-cijfers aan de agent geleverd. De eigen stiltemarkering van Amazon Connect wordt genegeerd; gebruik de beurt-time-out van de agent om een stille beller opnieuw te vragen.

Beperkingen en niet-ondersteunde functies

• Clienttools en de systeemtool Toetstoontje afspelen worden niet ondersteund. Overdragen naar nummer werkt alleen via een Amazon Connect-overdrachtsregel: de agent kan vanuit een Amazon Connect-gesprek geen telefoonnummer of SIP-URI bellen en de flow bepaalt welke queue een geëscaleerde beller ontvangt.
• Resultaten van gegevensverzameling worden niet teruggestuurd naar de flow, en Amazon Connect bepaalt welke contact- gegevens het deelt. Gebruik voor aanvullende context de webhook voor gespreksinitiatie op basis van amazon_connect_contact_id, een webhooktool die UpdateContactAttributes aanroept voor routeringsgegevens, en de webhook na het gesprek voor al het overige.
• Configuratieoverschrijvingen zoals system__override_first_message kunnen niet vanuit de flow worden doorgegeven. Geef deze in plaats daarvan terug via de webhook voor gespreksinitiatie.
• Spraaksessies vereisen onmiddellijke overdracht. Het Amazon Connect-chatkanaal, tekststreaming en samenwerking op de achtergrond (delegateAgentConfiguration) worden niet ondersteund.
• Traces die naar Amazon Connect worden verzonden, omvatten het transcript van de beller, reacties van de agent, toolaanroepen met hun resultaten en timing. Parameters van toolaanroepen zijn niet opgenomen.
• Ondersteuning voor externe agents van Amazon Connect is alleen beschikbaar waar AWS deze heeft ingeschakeld en kan extra AWS-kosten met zich meebrengen.

Problemen oplossen