Amazon Connect

Panoramica

L’integrazione con Amazon Connect collega direttamente un flusso di contatto Amazon Connect a un agente in ElevenAgents tramite il protocollo per agenti IA di terze parti di Amazon Connect, un’estensione del protocollo aperto A2A. Amazon Connect gestisce telefonia, instradamento e coda; ElevenAgents gestisce la conversazione. Non sono necessari trunk SIP, numeri Twilio o middleware. AWS documenta la funzionalità in Collaborazione agente-agente; questa guida tratta gli aspetti specifici di ElevenLabs e i passaggi AWS necessari per raggiungere un agente ElevenLabs.

Lo stesso flusso gestisce le chiamate in entrata e i contatti in uscita avviati con StartOutboundVoiceContact. Quando l’agente ElevenLabs termina, Amazon Connect continua il flusso di contatto e crea un ramo in base all’esito ricevuto.

Come funziona l’integrazione

1. Un flusso di contatto raggiunge un blocco Ottieni input del cliente che invoca un bot Amazon Lex V2 con l’intent AMAZON.QInConnectIntent.
2. L’agente IA di orchestrazione di Amazon Connect passa immediatamente la conversazione all’applicazione di terze parti registrata per ElevenLabs.
3. Amazon Connect apre un WebSocket verso l’endpoint ElevenLabs nell’AccessUrl dell’applicazione, autenticandosi con la chiave API archiviata in AWS Secrets Manager.
4. Amazon Connect segnala che il canale del chiamante è attivo, quindi Amazon Connect ed ElevenLabs scambiano audio PCM lineare a 16 bit come messaggi A2A. Amazon Connect propone la frequenza di campionamento ed ElevenLabs la adotta, quindi non sono necessarie modifiche al formato audio nell’agente.
5. Quando l’agente termina la chiamata o trasferisce il chiamante a un operatore, ElevenLabs conclude la sessione con un esito Complete o Escalate e il flusso continua dal blocco Lex; consulta Trasferimento a un operatore.

Requisiti

Prima di iniziare, assicurati di avere:

1. Un’istanza Amazon Connect nel piano Connect Customer con supporto per agenti IA di terze parti abilitato per l’account e la regione.
2. Un assistente Amazon Q in Connect associato all’istanza.
3. Autorizzazioni AWS per creare chiavi KMS, segreti Secrets Manager, applicazioni AppIntegrations, profili di sicurezza Connect, agenti IA Amazon Q in Connect, bot Lex V2 e flussi di contatto.
4. Un workspace ElevenLabs con il trasporto Amazon Connect abilitato.
5. Un agente ElevenLabs e una chiave API dedicata.
6. AWS CLI v2 e awscurl (pip install awscurl) per le chiamate le cui request shape non sono ancora presenti nelle versioni CLI rilasciate.

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

Registra l’applicazione ElevenLabs in AWS

Tutto in questa sezione è una chiamata API. Imposta una sola volta i valori che riutilizzerai:

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

Crea il flusso di contatto

{
  "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 l’integrazione

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

Variabili dinamiche

Amazon Connect invia gli attributi di sistema del contatto con ogni sessione. ElevenLabs li espone, insieme agli identificatori della sessione, come variabili dinamiche:

Nelle sessioni Amazon Connect, system__caller_id è sempre il cliente e system__called_number è sempre il numero Amazon Connect, sia per i contatti in entrata sia per quelli in uscita.

Ogni altro elemento del contesto del contatto inviato da Amazon Connect viene esposto allo stesso modo: i nomi annidati vengono uniti con trattini bassi e convertiti in snake case con il prefisso amazon_connect_. Gli attributi di contatto personalizzati impostati nel flusso con Imposta attributi di contatto non fanno parte del contesto che Amazon Connect invia attualmente, anche quando il profilo di sicurezza dell’agente IA può visualizzare gli attributi di contatto; se AWS inizierà a includerli, appariranno automaticamente con lo stesso prefisso. Non puoi scegliere quali dati di contatto Amazon Connect condivide; AWS trasmette un set fisso di contesto.

Per trasmettere contesto aggiuntivo, usa il webhook di avvio della conversazione. Per le sessioni Amazon Connect, il webhook viene chiamato prima che l’agente parli con caller_id impostato sul numero del cliente, called_number impostato sul numero Amazon Connect e call_id impostato sull’ID del contatto Amazon Connect, quindi una Lambda nel flusso può archiviare attributi di contatto indicizzati per ID contatto e il webhook può restituirli come variabili dinamiche e override della configurazione.

Trasferimento a un operatore umano

Fornisci all’agente lo strumento di sistema Trasferisci a numero con una regola di trasferimento amazon_connect, come mostrato in Configura ElevenLabs. Quando viene soddisfatta la condizione della regola, l’agente chiama lo strumento e ElevenLabs conclude la sessione con l’esito Escalate e il motivo fornito dall’agente. Il ramo Escalate del flusso gestisce poi il contatto con Imposta coda di lavoro e Trasferisci alla coda. La regola non contiene una destinazione, quindi la coda viene scelta nel flusso, non dall’agente; gestione della coda, whisper flow e selezione dell’agente restano in Amazon Connect.

Lo strumento Termina chiamata produce un esito Complete. L’analisi post-chiamata e il webhook post-chiamata vengono eseguiti come di consueto dopo entrambi gli esiti.

Fornire un riepilogo all’operatore umano

Amazon Connect espone al flusso solo l’esito: $.Lex.SessionAttributes.Tool (e il nome dell’intent Lex) contiene Escalate, e nient’altro della sessione ElevenLabs, incluso il motivo del trasferimento, raggiunge il flusso. Per aggiornare l’operatore umano che prende la chiamata, salva tu stesso il riepilogo sul contatto e lascia che un agent whisper flow lo legga:

1. Esponi un endpoint che chiama l’API UpdateContactAttributes di Amazon Connect. È sufficiente una Lambda minima dietro un’API HTTP; il chiamante deve avere il permesso connect:UpdateContactAttributes sui contatti dell’istanza:

   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. Fornisci all’agente uno strumento webhook che esegua un POST verso quell’endpoint con contact_id compilato dalla variabile dinamica amazon_connect_contact_id e un summary scritto dal modello. Conserva il segreto condiviso in un secret del workspace e invialo come header della richiesta. Nel prompt di sistema, indica all’agente di chiamare prima questo strumento e di chiamare Trasferisci a numero solo dopo il suo ritorno; un modello che emette entrambe le chiamate nello stesso turno mette in competizione il trasferimento con il riepilogo. Con questa istruzione, nei nostri test l’attributo era sul contatto circa un secondo dopo la richiesta dell’agente, tre secondi prima che Amazon Connect riprendesse il flusso.

3. Nel ramo Escalate del flusso di contatto, aggiungi un blocco Imposta whisper flow prima di **Trasferisci alla coda **, che punti a un agent whisper flow il cui Riproduci prompt legge $.Attributes.handoff_summary. Amazon Connect lo riproduce all’operatore umano mentre il chiamante ascolta la gestione della coda, quindi collega i due. Non impostare di nuovo handoff_summary in un blocco successivo del flusso: un valore vuoto sostituisce quello scritto dall’endpoint.

Lo stesso attributo è disponibile per un blocco Controlla attributi di contatto per le decisioni di instradamento. Il webhook post-chiamata si attiva dopo che il flusso è già proseguito, quindi è adatto agli aggiornamenti CRM anziché alle decisioni di instradamento.

Tracce

Amazon Connect richiede agli agenti esterni di inviare dati di traccia per ogni collaborazione. Quando Amazon Connect si iscrive al tracciamento della sessione, ElevenLabs invia una traccia OpenTelemetry per ogni turno dell’agente contenente la trascrizione del chiamante, la risposta dell’agente, ogni chiamata di strumento con il relativo risultato e la temporizzazione per span. Amazon Connect archivia queste tracce con il contatto; consulta Tracce dell’agente IA per sapere come visualizzarle. Le trascrizioni e i risultati degli strumenti in queste tracce sono soggetti alle stesse impostazioni di redazione degli altri dati di contatto in Amazon Connect, quindi esamina i requisiti di gestione dei dati prima di abilitare l’integrazione. Come i webhook post-chiamata, le tracce vengono inviate ai tuoi sistemi: gli agenti in modalità zero retention le inviano comunque, perché zero retention regola ciò che ElevenLabs archivia, non ciò che riceve l’istanza Amazon Connect.

Audio

Amazon Connect propone PCM lineare mono a 16 bit a 8, 16 o 24 kHz per ogni sessione, e ElevenLabs adotta la proposta, quindi i formati audio configurati dall’agente non vengono usati per le sessioni Amazon Connect. L’interruzione da parte del chiamante viene rilevata da ElevenLabs e segnalata ad Amazon Connect affinché la riproduzione in buffer venga svuotata immediatamente. L’input da tastierino raccolto da Amazon Connect viene inviato all’agente come cifre DTMF. Il marker di silenzio di Amazon Connect viene ignorato; usa il timeout di turno dell’agente per richiedere nuovamente una risposta a un chiamante silenzioso.

Limitazioni e funzionalità non supportate

• Gli strumenti client e lo strumento di sistema Riproduci tono del tastierino non sono supportati. Trasferisci a numero funziona solo tramite una regola di trasferimento Amazon Connect: l’agente non può chiamare un numero di telefono o un URI SIP da una chiamata Amazon Connect e il flusso decide quale coda riceve un chiamante per cui è stata effettuata un’escalation.
• I risultati della raccolta dati non vengono restituiti al flusso e Amazon Connect decide quali dati di contatto condividere. Usa il webhook di avvio della conversazione indicizzato tramite amazon_connect_contact_id per contesto aggiuntivo, uno strumento webhook che chiama UpdateContactAttributes per i dati di instradamento e il webhook post-chiamata per tutto il resto.
• Gli override di configurazione come system__override_first_message non possono essere trasmessi dal flusso. Restituiscili invece dal webhook di avvio della conversazione.
• Le sessioni vocali richiedono un passaggio di consegne immediato. Il canale chat di Amazon Connect, lo streaming di testo e la collaborazione in background (delegateAgentConfiguration) non sono supportati.
• Le tracce inviate ad Amazon Connect includono la trascrizione del chiamante, le risposte dell’agente, le chiamate degli strumenti con i relativi risultati e la temporizzazione. I parametri delle chiamate degli strumenti non sono inclusi.
• Il supporto di Amazon Connect per gli agenti di terze parti è disponibile solo dove AWS lo ha abilitato e può comportare costi AWS aggiuntivi.

Risoluzione dei problemi