Amazon Connect

Vue d’ensemble

L’intégration Amazon Connect connecte directement un flux de contact Amazon Connect à un agent dans ElevenAgents via le protocole d’agent IA tiers d’Amazon Connect, une extension du protocole A2A ouvert. Amazon Connect gère la téléphonie, le routage et la file d’attente ; ElevenAgents gère la conversation. Aucun trunk SIP, numéro Twilio ou middleware n’est requis. AWS documente cette fonctionnalité sous Collaboration agent à agent ; ce guide couvre les spécificités d’ElevenLabs ainsi que les étapes AWS nécessaires pour accéder à un agent ElevenLabs.

Le même flux sert les appels entrants et les contacts sortants démarrés avec StartOutboundVoiceContact. Lorsque l’agent ElevenLabs termine, Amazon Connect poursuit votre flux de contact et crée une branche selon le résultat reçu.

Fonctionnement de l’intégration

1. Un flux de contact atteint un bloc Get customer input qui appelle un bot Amazon Lex V2 avec l’intention AMAZON.QInConnectIntent.
2. L’agent IA d’orchestration d’Amazon Connect transfère immédiatement la conversation à l’application tierce que vous avez enregistrée pour ElevenLabs.
3. Amazon Connect ouvre un WebSocket vers le point de terminaison ElevenLabs dans AccessUrl de l’application, en s’authentifiant avec la clé API stockée dans AWS Secrets Manager.
4. Amazon Connect signale que le canal de l’appelant est actif, puis Amazon Connect et ElevenLabs échangent de l’audio PCM linéaire 16 bits sous forme de messages A2A. Amazon Connect propose la fréquence d’échantillonnage et ElevenLabs l’adopte, aucun changement de format audio n’est donc nécessaire côté agent.
5. Lorsque l’agent met fin à l’appel ou transfère l’appelant à un humain, ElevenLabs termine la session avec un résultat Complete ou Escalate, et le flux se poursuit depuis le bloc Lex ; consultez Transférer à un humain.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

1. Une instance Amazon Connect au niveau Connect Customer, avec la prise en charge des agents IA tiers activée pour le compte et la région.
2. Un assistant Amazon Q in Connect associé à l’instance.
3. Des autorisations AWS pour créer des clés KMS, des secrets Secrets Manager, des applications AppIntegrations, des profils de sécurité Connect, des agents IA Amazon Q in Connect, des bots Lex V2 et des flux de contact.
4. Un Workspace ElevenLabs avec le transport Amazon Connect activé.
5. Un agent ElevenLabs et une clé API dédiée.
6. AWS CLI v2 et awscurl (pip install awscurl) pour les appels dont les formats de requête ne sont pas encore disponibles dans les versions publiées de la CLI.

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

Enregistrez l’application ElevenLabs dans AWS

Tous les éléments de cette section sont des appels API. Définissez une seule fois les valeurs que vous réutiliserez :

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

Créez le flux de contact

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

Tester l’intégration

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

Variables dynamiques

Amazon Connect envoie les attributs système du contact à chaque session. ElevenLabs les expose, avec les identifiants de session, sous forme de variables dynamiques :

Dans les sessions Amazon Connect, system__caller_id correspond toujours au client et system__called_number correspond toujours au numéro Amazon Connect, pour les contacts entrants comme sortants.

Tous les autres membres du contexte de contact envoyés par Amazon Connect sont exposés de la même manière : les noms imbriqués sont joints par des traits de soulignement et convertis en snake case sous le préfixe amazon_connect_. Les attributs de contact personnalisés définis dans votre flux avec Définir les attributs de contact ne font pas partie actuellement du contexte envoyé par Amazon Connect, même lorsque le profil de sécurité de l’agent IA peut consulter les attributs de contact. Si AWS commence à les inclure, ils apparaîtront automatiquement sous le même préfixe. Vous ne pouvez pas choisir les données de contact partagées par Amazon Connect ; AWS transmet un ensemble de contexte fixe.

Pour transmettre du contexte supplémentaire, utilisez le webhook de démarrage de conversation. Pour les sessions Amazon Connect, le webhook est appelé avant que l’agent ne parle, avec caller_id défini sur le numéro du client, called_number défini sur le numéro Amazon Connect et call_id défini sur l’ID de contact Amazon Connect. Une Lambda dans votre flux peut donc stocker des attributs de contact indexés par ID de contact, et le webhook peut les renvoyer comme variables dynamiques et remplacements de configuration.

Transférer vers un humain

Donnez à l’agent l’outil système Transférer vers un numéro avec une règle de transfert amazon_connect, comme indiqué dans Configurer ElevenLabs. Lorsque la condition de la règle est remplie, l’agent appelle l’outil et ElevenLabs termine la session avec le résultat Escalate et la raison fournie par l’agent. La branche Escalate de votre flux gère alors le contact avec Définir la file de travail et Transférer vers la file. La règle ne comporte aucune destination : la file est choisie dans le flux, et non par l’agent. Le traitement de file, les flux de chuchotement et la sélection des agents restent dans Amazon Connect.

L’outil Mettre fin à l’appel produit un résultat Complete. L’analyse après appel et le webhook après appel s’exécutent normalement après l’un ou l’autre résultat.

Fournir un résumé à l’agent humain

Amazon Connect expose uniquement le résultat à votre flux : $.Lex.SessionAttributes.Tool (ainsi que le nom de l’intention Lex) contient Escalate, et aucune autre information de la session ElevenLabs, y compris la raison du transfert, n’atteint le flux. Pour informer l’humain qui prend l’appel, stockez vous-même le résumé sur le contact et laissez un flux de chuchotement à l’agent le lire :

1. Exposez un point de terminaison qui appelle l’API UpdateContactAttributes d’Amazon Connect. Une Lambda minimale derrière une API HTTP suffit ; l’appelant doit être autorisé à utiliser connect:UpdateContactAttributes sur les contacts de l’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. Donnez à l’agent un outil webhook qui effectue une requête POST vers ce point de terminaison avec contact_id renseigné à partir de la variable dynamique amazon_connect_contact_id et un summary rédigé par le modèle. Conservez le secret partagé dans un secret du Workspace et envoyez-le comme en-tête de requête. Dans le prompt système, indiquez à l’agent d’appeler d’abord cet outil et d’appeler Transférer vers un numéro seulement après son retour ; un modèle qui émet les deux appels dans le même tour met le transfert en concurrence avec le résumé. Avec cette instruction, lors de nos tests, l’attribut était présent sur le contact environ une seconde après la requête de l’agent, soit trois secondes avant qu’Amazon Connect ne reprenne le flux.

3. Dans la branche Escalate du flux de contact, ajoutez un bloc Définir le flux de chuchotement avant Transférer vers la file , qui pointe vers un flux de chuchotement à l’agent dont l’ Invite de lecture lit $.Attributes.handoff_summary. Amazon Connect le lit à l’agent humain pendant que l’appelant entend le traitement de file, puis met les deux interlocuteurs en relation. Ne définissez pas à nouveau handoff_summary dans un bloc ultérieur du flux : une valeur vide remplacerait celle écrite par le point de terminaison.

Le même attribut est disponible dans un bloc Vérifier les attributs de contact pour prendre des décisions de routage. Le webhook après appel se déclenche après que le flux a déjà continué ; il convient donc aux mises à jour CRM plutôt qu’aux décisions de routage.

Traces

Amazon Connect exige que les agents externes envoient des données de trace pour chaque collaboration. Lorsqu’Amazon Connect s’abonne au traçage d’une session, ElevenLabs envoie une trace OpenTelemetry pour chaque tour de l’agent, contenant la transcription de l’appelant, la réponse de l’agent, chaque appel d’outil avec son résultat et le temps par plage. Amazon Connect stocke ces traces avec le contact ; consultez Traces des agents IA pour savoir comment les afficher. Les transcriptions et résultats d’outils de ces traces sont soumis aux mêmes paramètres de masquage que le reste de vos données de contact dans Amazon Connect. Vérifiez donc vos exigences de traitement des données avant d’activer l’intégration. Comme les webhooks après appel, les traces sont transmises à vos propres systèmes : les agents en mode zéro rétention les envoient toujours, car la rétention zéro régit ce qu’ElevenLabs stocke, et non ce que votre instance Amazon Connect reçoit.

Audio

Amazon Connect propose du PCM linéaire mono 16 bits à 8, 16 ou 24 kHz pour chaque session, et ElevenLabs accepte cette proposition. Les formats audio configurés pour l’agent ne sont donc pas utilisés pour les sessions Amazon Connect. L’interruption par l’appelant est détectée par ElevenLabs et signalée à Amazon Connect afin que la lecture mise en mémoire tampon soit immédiatement interrompue. Les entrées au clavier collectées par Amazon Connect sont transmises à l’agent sous forme de chiffres DTMF. Le marqueur de silence d’Amazon Connect est ignoré ; utilisez le délai d’expiration du tour de l’agent pour relancer un appelant silencieux.

Limites et fonctionnalités non prises en charge

• Les outils client et l’outil système Lire une tonalité tactile du clavier ne sont pas pris en charge. Transférer vers un numéro fonctionne uniquement avec une règle de transfert Amazon Connect : l’agent ne peut pas composer un numéro de téléphone ou un URI SIP depuis un appel Amazon Connect, et le flux détermine la file qui reçoit un appelant transféré.
• Les résultats de collecte de données ne sont pas renvoyés au flux, et Amazon Connect détermine les données de contact qu’il partage. Utilisez le webhook de démarrage de conversation indexé par amazon_connect_contact_id pour obtenir du contexte supplémentaire, un outil webhook qui appelle UpdateContactAttributes pour les données de routage, et le webhook après appel pour tout le reste.
• Les remplacements de configuration tels que system__override_first_message ne peuvent pas être transmis depuis le flux. Renvoyez-les plutôt depuis le webhook de démarrage de conversation.
• Les sessions vocales exigent un transfert immédiat. Le canal de chat Amazon Connect, le streaming texte et la collaboration en arrière-plan (delegateAgentConfiguration) ne sont pas pris en charge.
• Les traces envoyées à Amazon Connect couvrent la transcription de l’appelant, les réponses de l’agent, les appels d’outils avec leurs résultats et le timing. Les paramètres d’appel d’outil ne sont pas inclus.
• La prise en charge des agents tiers par Amazon Connect est disponible uniquement là où AWS l’a activée et peut entraîner des frais AWS supplémentaires.

Résolution des problèmes