> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Amazon Connect > **Warning** > > L'integrazione con Amazon Connect è disponibile in modo limitato. Il supporto di Amazon Connect per gli agenti IA > di terze parti deve essere abilitato per il tuo account AWS e il trasporto ElevenLabs viene abilitato per ciascun > workspace. Contatta il tuo referente ElevenLabs prima di instradare il traffico dei clienti. ## 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](https://a2a-protocol.org/). 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](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html); 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](#transferring-to-a-human). ## 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](https://github.com/okigan/awscurl) (`pip install awscurl`) per le chiamate le cui request shape non sono ancora presenti nelle versioni CLI rilasciate. > **Note** > > Mantieni tutte le risorse AWS nello stesso account e nella stessa regione dell'istanza Amazon Connect. I passaggi > seguenti usano AWS CLI quando supporta la chiamata e `awscurl` (una richiesta HTTP firmata SigV4) quando > non la supporta. Seguono la procedura AWS [Configurare la collaborazione con un agente IA esterno](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html) e aggiungono i > valori specifici di ElevenLabs. ## Configura ElevenLabs #### Crea o seleziona un agente Crea l'agente in ElevenAgents. Assegnagli un primo messaggio se deve parlare non appena il trasferimento viene completato; Amazon Connect non riproduce alcun audio proprio durante la sessione. #### Abilita Termina chiamata In **Agente → Strumenti → Strumenti di sistema**, abilita **Termina chiamata** affinché l'agente possa terminare la sessione quando la richiesta del chiamante è stata risolta. Amazon Connect continua quindi il tuo flusso con l'esito `Complete`. #### Aggiungi una regola di trasferimento Amazon Connect (facoltativo) Per consentire all'agente di trasferire il chiamante a un operatore, assegnagli lo strumento di sistema **Trasferisci a numero** con una regola di trasferimento la cui configurazione del provider sia `amazon_connect`. La regola non ha una destinazione: la sessione termina con l'esito `Escalate` e il tuo flusso di contatto sceglie la coda. Le regole di trasferimento sono configurate tramite API. Aggiungi lo strumento con un `PATCH` sull'agente: ```bash 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"}} ] }] } } }}}} }' ``` Invia l'intero oggetto `built_in_tools` dell'agente, inclusi gli strumenti già presenti come `end_call`. L'agente seleziona la regola in base alla relativa `condition`; l'opzione che restituisce è il token fisso `amazon_connect`, quindi è sufficiente una regola Amazon Connect per strumento. Numeri di telefono e URI SIP configurati per altri provider non vengono offerti nelle chiamate Amazon Connect. > **Note** > > Le regole di trasferimento sono un'impostazione gestita tramite API. Configura e aggiorna tramite API, come sopra, > lo strumento **Trasferisci a numero** di un agente che le utilizza; l'editor degli strumenti della dashboard funziona con l'elenco di trasferimento > per numero. #### Crea una chiave API dedicata Crea una chiave API nello stesso workspace dell'agente e limitane l'ambito a ElevenAgents. La archivierai in AWS Secrets Manager nella sezione successiva; non incollarla altrove. #### Annota l'URL WebSocket Amazon Connect si connette a un URL che contiene l'ID dell'agente: | Ambiente | AccessUrl | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | Predefinito | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Residenza dati | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > Se il tuo account ElevenLabs si trova in un ambiente di residenza isolato, sostituisci `` con il codice > della tua regione. Consulta la [residenza dei dati](/docs/it/overview/administration/data-residency) per le regioni > disponibili. ## Registra l'applicazione ElevenLabs in AWS Tutto in questa sezione è una chiamata API. Imposta una sola volta i valori che riutilizzerai: ```bash export AWS_REGION= # Region of your Amazon Connect instance export ACCOUNT_ID= export INSTANCE_ID= # Amazon Connect instance ID export INSTANCE_ARN=arn:aws:connect:$AWS_REGION:$ACCOUNT_ID:instance/$INSTANCE_ID export AGENT_ID= # ElevenLabs agent ID ``` #### Crea un assistente Amazon Q in Connect Salta questo passaggio se l'istanza ha già un assistente. Altrimenti, creane uno e associalo all'istanza: ```bash 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 --region $AWS_REGION ``` Annota l'ID e l'ARN dell'assistente. #### Archivia la chiave API Amazon Connect legge la chiave da Secrets Manager usando il proprio service principal, quindi il secret deve essere crittografato con una chiave KMS gestita dal cliente che conceda a `connect.amazonaws.com` l'accesso per la decrittografia. Non puoi usare la chiave predefinita `aws/secretsmanager`. **`kms-key-policy.json`** ```json title="kms-key-policy.json" { "Version": "2012-10-17", "Statement": [ { "Sid": "AccountAdmin", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "AllowConnectDecrypt", "Effect": "Allow", "Principal": { "Service": "connect.amazonaws.com" }, "Action": ["kms:Decrypt", "kms:DescribeKey"], "Resource": "*" } ] } ``` Salva la chiave API di ElevenLabs in un file affinché non compaia mai nella cronologia della shell, poi crea la chiave e il secret: ```bash 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 ``` Concedi ad Amazon Connect l'accesso in lettura al secret: **`secret-resource-policy.json`** ```json title="secret-resource-policy.json" { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowConnectRead", "Effect": "Allow", "Principal": { "Service": "connect.amazonaws.com" }, "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], "Resource": "" } ] } ``` ```bash aws secretsmanager put-resource-policy --secret-id "$SECRET_ARN" \ --resource-policy file://secret-resource-policy.json --region $AWS_REGION ``` ![Secret di Secrets Manager crittografato con la chiave gestita dal cliente e relativa policy delle risorse per connect.amazonaws.com](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### Crea l'applicazione di terze parti Registra l'URL WebSocket di ElevenLabs come applicazione AppIntegrations di tipo `A2A_SERVER`. `AuthConfig` è obbligatorio per questo tipo. **`create-application.json`** ```json title="create-application.json" { "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/" } }, "AuthConfig": { "AuthType": "API_KEY", "CredentialProviderIdentifier": "" } } ``` ```bash 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" ``` La risposta contiene `Id` e `Arn` dell'applicazione; esportali come `APPLICATION_ID` e `APPLICATION_ARN`. La console Amazon Connect non elenca le applicazioni `A2A_SERVER`, quindi verifica con l'API: ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### Associa l'applicazione alla tua istanza ```bash 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 ``` #### Consenti l'applicazione in un profilo di sicurezza Il profilo di sicurezza associato all'agente IA di orchestrazione deve elencare l'applicazione tra i propri agenti IA consentiti, altrimenti il passaggio di consegne non riesce in fase di runtime. ```bash 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" ``` Il sito di amministrazione mostra il profilo e le relative autorizzazioni, ma non gli agenti IA consentiti; questi sono visibili solo tramite l'API. ![Profilo di sicurezza dedicato nel sito di amministrazione Amazon Connect con autorizzazioni per visualizzare gli agenti IA](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### Crea e pubblica l'agente IA di orchestrazione L'agente di orchestrazione passa subito ogni conversazione vocale all'applicazione, con lo streaming audio abilitato. Le sessioni vocali richiedono un passaggio di consegne immediato; lo streaming di testo (`audioStreamingEnabled` impostato su false) e `delegateAgentConfiguration` non sono supportati da ElevenLabs. Un orchestratore con passaggio di consegne audio immediato deve inoltre dichiarare lo strumento riservato `Complete` di tipo `RETURN_TO_CONTROL` in `toolConfigurations`; senza di esso, la richiesta di creazione non riesce con `An audio frontline orchestrator (with an audio immediate handoff) must configure the reserved 'Complete' RETURN_TO_CONTROL tool`. **`create-ai-agent.json`** ```json title="create-ai-agent.json" { "name": "elevenlabs-handoff", "type": "ORCHESTRATION", "visibilityStatus": "PUBLISHED", "configuration": { "orchestrationAIAgentConfiguration": { "connectInstanceArn": "", "locale": "en_US", "multiAgentConfigurations": [ { "handoffAgentConfiguration": { "agentTarget": { "applicationId": "" }, "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 } } ] } } } ``` ```bash 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//aiagents" aws qconnect create-ai-agent-version --assistant-id \ --ai-agent-id --region $AWS_REGION ``` La pubblicazione restituisce un ARN con versione (`:1`); il flusso di contatto vi fa riferimento. Associa il profilo di sicurezza sia all'agente senza versione sia a quello con versione: ```bash for ARN in :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 ``` ![Agente IA di orchestrazione nel designer degli agenti IA con il profilo di sicurezza dedicato associato](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## Crea il flusso di contatto #### Crea il bot Lex 1. Crea un bot Lex V2 il cui unico intent sia l'`AMAZON.QInConnectIntent` integrato, configurato con l'ARN del tuo assistente. Non aggiungere altri intent. 2. Abilita speech-to-speech nelle impostazioni locali del bot. Lo streaming audio bidirezionale funziona solo con bot Sonic speech-to-speech. 3. Consenti al ruolo IAM del bot di usare l'assistente. Senza questo, il passaggio di consegne non riesce in AWS con `HTTP 403` prima che una richiesta raggiunga ElevenLabs. Associa una policy come questa: **`lex-role-policy.json`** ```json title="lex-role-policy.json" { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["wisdom:CreateSession", "wisdom:GetAssistant"], "Resource": ["", "/*"] }, { "Effect": "Allow", "Action": ["wisdom:SendMessage", "wisdom:GetNextMessage"], "Resource": "arn:aws:wisdom:::session//*" } ] } ``` 4. Crea il bot, poi crea una versione e un alias, quindi associa l'alias all'istanza: ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Elenco degli intent del bot Lex V2 con l'intent di passaggio di consegne Q in Connect e l'intent di fallback integrato](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### Aggiungi l'assistente e il blocco Lex Nel designer del flusso, aggiungi questi blocchi nell'ordine indicato: 1. **Imposta comportamento di logging**: abilitato. Il log del flusso consente di verificare il passaggio di consegne riportato di seguito. 2. **Connetti assistente**: seleziona il tuo assistente Amazon Q in Connect. 3. **Ottieni input del cliente**: nella scheda **Amazon Lex** scegli **Inserisci un ARN** e incolla l'ARN dell'alias del bot. Lascia il prompt Text to Speech come singolo spazio affinché Amazon Connect non riproduca nulla prima del passaggio di consegne. In **Attributi di sessione**, aggiungi manualmente due attributi: | Chiave di destinazione | Valore | | ------------------------------------- | ----------------------------------------------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | L'ARN dell'agente di orchestrazione con versione (`...:1`). | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Attributi di sessione del blocco Ottieni input del cliente: l'ARN dell'agente IA con versione e il flag di passthrough audio](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` abilita il percorso vocale di terze parti durante il periodo di pre-lancio di AWS. > AWS dichiara che l'attributo non sarà più necessario quando la funzionalità sarà pubblica; lasciarlo attivo è > innocuo. #### Crea rami in base all'esito Amazon Connect espone al flusso l'esito di ElevenLabs come attributo `$.Lex.SessionAttributes.Tool`. Dopo il blocco Lex, aggiungi un blocco **Controlla attributi di contatto**, imposta **Namespace** su **Lex**, **Chiave** su **Attributi di sessione** e **Chiave attributo di sessione** su `Tool`, quindi aggiungi una condizione **Uguale a** per ogni esito e instrada **Nessuna corrispondenza** a un prompt di errore: | Ramo | Significato | Percorso suggerito | | ---------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `Complete` | L'agente ha terminato la chiamata, ad esempio con lo strumento **Termina chiamata**. | Disconnetti | | `Escalate` | L'agente ha richiesto un operatore umano (vedi [Trasferimento a un operatore umano](#transferring-to-a-human)). | Imposta coda di lavoro → Trasferisci alla coda | | Nessuna corrispondenza | Qualsiasi altro valore. | Riproduci prompt → Disconnetti | ![Blocco Controlla attributi di contatto configurato sull'attributo di sessione Lex Tool con condizioni Uguale a per ogni esito](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connect scrive l'esito con iniziale maiuscola (`Escalate`, `Complete`), non come tipo di > completamento tutto maiuscolo inviato tramite il collegamento, quindi queste due condizioni sono tutto ciò che serve al blocco. Una sessione che > non riesce dopo il passaggio di consegne termina con il tipo `COMPLETE_WITH_ERROR`; il blocco Lex segue quindi il > relativo output **Errore** oppure il confronto passa a **Nessuna corrispondenza**, quindi instrada entrambi al prompt di > errore. In un flusso esportato, l'output **Predefinito** del blocco Lex è la sua transizione `NoMatchingCondition`; > assicurati che conduca al blocco di confronto anziché a un messaggio di errore. ![Flusso di contatto con il blocco Ottieni input del cliente che conduce a un blocco Controlla attributi di contatto, il quale instrada Escalate a una coda, Complete a una disconnessione e Nessuna corrispondenza a un prompt di errore](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### Pubblica e assegna Pubblica il flusso, quindi indirizza a esso un numero di telefono richiesto: ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` Per le chiamate in uscita, avvia il contatto con lo stesso flusso; Amazon Connect chiama il cliente e passa la chiamata con risposta a ElevenLabs: ```bash aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \ --contact-flow-id --destination-phone-number \ --source-phone-number --region $AWS_REGION ``` ## Testa l'integrazione #### Effettua una chiamata Chiama il numero. Il primo messaggio dell'agente viene riprodotto pochi secondi dopo che il flusso raggiunge il blocco Lex; il passaggio di consegne in AWS richiede circa tre secondi prima che ElevenLabs venga contattato. Fai una breve conversazione e saluta: l'agente chiama **Termina chiamata**, la sessione ElevenLabs termina con `Complete` e il flusso prosegue dal blocco Lex. Se hai aggiunto una regola di trasferimento, chiedi invece un operatore umano: l'agente chiama **Trasferisci a numero**, la sessione termina con `Escalate` e il flusso segue quel ramo. #### Controlla la conversazione in ElevenLabs Apri la conversazione in **Conversazioni**. La relativa origine è Amazon Connect e la scheda **Dati client** elenca le variabili dinamiche `amazon_connect_*` ricevute dalla sessione. ![Scheda Dati client di una conversazione Amazon Connect che elenca le variabili dinamiche di Amazon Connect](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### Controlla il log del flusso in AWS Con il logging abilitato, ogni blocco scrive una voce nel gruppo di log del flusso dell'istanza. Il blocco **Ottieni input del cliente** registra l'esito ricevuto da ElevenLabs: ```bash aws logs filter-log-events --log-group-name /aws/connect/ \ --start-time $(( $(date +%s) - 600 ))000 --region $AWS_REGION \ --query 'events[].message' --output text | tr '\t' '\n' | grep -o '"Results": *"[A-Za-z_]*"' ``` Per il blocco Lex, aspettati `"Results": "Complete"` oppure `"Results": "Escalate"` dopo un trasferimento, seguito dai blocchi di quel ramo. ## 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: | Variabile dinamica | Descrizione | | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | `system__caller_id` | Il numero di telefono del cliente (endpoint cliente di Amazon Connect). | | `system__called_number` | Il numero di telefono Amazon Connect su cui si trova il contatto (endpoint di sistema). | | `system__call_id` | L'ID del contatto Amazon Connect. | | `amazon_connect_system_attributes_channel` | Il canale di contatto, ad esempio `VOICE`. | | `amazon_connect_system_attributes_customer_endpoint_address` | L'indirizzo dell'endpoint cliente inviato da Amazon Connect. | | `amazon_connect_system_attributes_system_endpoint_address` | L'indirizzo dell'endpoint di sistema inviato da Amazon Connect. | | `amazon_connect_interaction_mode` | La modalità di collaborazione, ad esempio `HANDOFF`. | | `amazon_connect_contact_id` | L'ID del contatto Amazon Connect. | | `amazon_connect_contact_arn` | L'ARN completo del contatto. | | `amazon_connect_context_id` | L'ID della sessione A2A (contesto). | | `amazon_connect_instance_id` | L'ID dell'istanza. | | `amazon_connect_instance_arn` | L'ARN dell'istanza. | 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](/docs/it/eleven-agents/customization/personalization#conversation-initiation-webhooks). 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](#configure-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: ```python 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](/docs/it/eleven-agents/customization/tools/webhook-tools) 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](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html) 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](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html) 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](/docs/it/eleven-agents/workflows/post-call-webhooks), le tracce vengono inviate ai tuoi sistemi: gli agenti in [modalità zero retention](/docs/it/eleven-agents/customization/privacy/zrm) 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 #### Il flusso non riesce con 'A2A WebSocket upgrade ... failed (HTTP 403)' * L'errore si verifica all'interno di AWS prima che qualsiasi richiesta raggiunga ElevenLabs. Controlla CloudTrail per verificare la presenza di `AccessDenied` su `wisdom:SendMessage` dal service role Lex: il ruolo associato al bot richiede `wisdom:CreateSession`, `wisdom:GetAssistant`, `wisdom:SendMessage` e `wisdom:GetNextMessage` sull'assistente e sulle relative sessioni. * Verifica che il profilo di sicurezza consenta l'applicazione e sia associato alla versione pubblicata dell'agente di orchestrazione a cui fa riferimento il flusso. * Verifica che la chiave KMS e la policy delle risorse del segreto concedano l'accesso a `connect.amazonaws.com`. #### Il flusso non riesce con 'the hand-off to the target agent could not be completed' * Amazon Connect concede alla connessione WebSocket circa 20 secondi per stabilirsi. Verifica che `AccessUrl` sia raggiungibile da AWS: `wss://`, l'ID agente corretto e nessuna allow-list di rete che interferisca. * Se instradi la connessione tramite la tua infrastruttura, mantieni attivo il proxy. Un'istanza serverless inattiva può richiedere più tempo della finestra di hand-off e Amazon Connect rinuncia prima che ElevenLabs riceva la richiesta. #### Il blocco Lex segue il ramo Error e il chiamante non sente nulla * Verifica che entrambi gli attributi di sessione siano impostati nel blocco **Acquisisci input del cliente**: `x-amz-lex:q-in-connect:ai-agent-arn` con l'ARN dell'agente pubblicato e versionato e `x-amz-lex:qic-audio-passthrough` impostato su `true`. * Verifica che il profilo di sicurezza che autorizza l'applicazione sia associato a quella versione dell'agente. * Leggi la voce del blocco nel log del flusso: contiene l'errore riscontrato da Amazon Connect. #### La sessione termina subito dopo la connessione * Verifica che `AccessUrl` utilizzi `wss://`, contenga l'ID agente corretto e punti alla regione in cui risiede il tuo workspace. * Verifica che la chiave API sia attiva, appartenga al workspace dell'agente e non abbia restrizioni IP. * Verifica che il trasporto Amazon Connect sia abilitato per il tuo workspace. #### Il chiamante sente il messaggio di errore del flusso al termine dell'agente Nel blocco Lex, assicurati che l'output **Default** conduca al blocco che confronta `$.Lex.SessionAttributes.Tool` e confrontalo con i valori in maiuscolo iniziale `Escalate` e `Complete`. #### L'agente non parla mai e la sessione termina dopo pochi secondi Verifica che il collaboratore sia configurato con `audioStreamingEnabled` impostato su true. Con lo streaming di testo, Amazon Connect invia turni di testo e si aspetta risposte testuali, che ElevenLabs non supporta; nei log di ElevenLabs viene visualizzato `INIT_SESSION carries no audio configuration`. #### Mancano variabili dinamiche Amazon Connect fornisce gli attributi di sistema e gli identificatori del contatto elencati sopra. Gli attributi di contatto personalizzati impostati nel flusso non raggiungono l'agente; passali invece tramite il webhook di avvio della conversazione. Se il primo messaggio o il prompt dell'agente fa riferimento a una variabile che non viene mai fornita, la sessione non si avvia.