> 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** > > A integração com o Amazon Connect está disponível de forma limitada. O suporte a agentes de IA de > terceiros do Amazon Connect precisa estar habilitado para sua conta AWS, e o transporte da ElevenLabs é habilitado por > workspace. Entre em contato com seu representante da ElevenLabs antes de direcionar o tráfego de clientes. ## Visão geral A integração com o Amazon Connect conecta um fluxo de contato do Amazon Connect diretamente a um agente no ElevenAgents pelo protocolo de agentes de IA de terceiros do Amazon Connect, uma extensão do protocolo aberto [A2A](https://a2a-protocol.org/). O Amazon Connect gerencia a telefonia, o roteamento e a fila; o ElevenAgents gerencia a conversa. Não é necessário usar tronco SIP, número Twilio nem middleware. A AWS documenta o recurso em [Colaboração entre agentes](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html); este guia, explicamos os detalhes específicos da ElevenLabs e as etapas da AWS necessárias para chegar a um agente da ElevenLabs. O mesmo fluxo atende chamadas recebidas e contatos de saída iniciados com `StartOutboundVoiceContact`. Quando o agente da ElevenLabs termina, o Amazon Connect continua seu fluxo de contato e segue a ramificação com base no resultado recebido. ## Como a integração funciona 1. Um fluxo de contato chega a um bloco **Obter informações do cliente** que invoca um bot do Amazon Lex V2 com a intenção `AMAZON.QInConnectIntent`. 2. O agente de IA de orquestração do Amazon Connect transfere a conversa imediatamente para o aplicativo de terceiros que você registrou para a ElevenLabs. 3. O Amazon Connect abre um WebSocket para o endpoint da ElevenLabs no `AccessUrl` do aplicativo, autenticando-se com a chave de API armazenada no AWS Secrets Manager. 4. O Amazon Connect sinaliza que o canal do chamador está ativo e, então, o Amazon Connect e a ElevenLabs trocam áudio PCM linear de 16 bits como mensagens A2A. O Amazon Connect propõe a taxa de amostragem e a ElevenLabs a adota, portanto não são necessárias alterações no formato de áudio do agente. 5. Quando o agente encerra a chamada ou transfere o chamador para uma pessoa, a ElevenLabs finaliza a sessão com o resultado `Complete` ou `Escalate`, e o fluxo continua a partir do bloco Lex; consulte [Transferir para uma pessoa](#transferring-to-a-human). ## Requisitos Antes de começar, confira se você tem: 1. Uma instância do Amazon Connect no nível Connect Customer, com suporte a agentes de IA de terceiros habilitado para a conta e a região. 2. Um assistente do Amazon Q in Connect associado à instância. 3. Permissões da AWS para criar chaves KMS, segredos do Secrets Manager, aplicativos AppIntegrations, perfis de segurança do Connect, agentes de IA do Amazon Q in Connect, bots Lex V2 e fluxos de contato. 4. Um workspace da ElevenLabs com o transporte do Amazon Connect habilitado. 5. Um agente da ElevenLabs e uma chave de API exclusiva. 6. AWS CLI v2 e [awscurl](https://github.com/okigan/awscurl) (`pip install awscurl`) para as chamadas cujas estruturas de solicitação ainda não estão nas versões lançadas da CLI. > **Note** > > Mantenha todos os recursos da AWS na mesma conta e região da instância do Amazon Connect. As etapas > abaixo usam a AWS CLI quando ela oferece suporte à chamada e `awscurl` (uma solicitação HTTP assinada com SigV4) quando > não oferece. Elas seguem o guia da AWS para [Configurar colaboração com um agente de IA externo](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html) e adicionam os > valores específicos da ElevenLabs. ## Configurar a ElevenLabs #### Criar ou selecionar um agente Crie o agente no ElevenAgents. Dê a ele uma primeira mensagem caso ele deva falar assim que a transferência for concluída; o Amazon Connect não reproduz nada por conta própria durante a sessão. #### Habilitar Encerrar chamada Em **Agente → Ferramentas → Ferramentas do sistema**, habilite **Encerrar chamada** para que o agente possa finalizar a sessão quando a solicitação do chamador for resolvida. O Amazon Connect então continua seu fluxo com o resultado `Complete`. #### Adicionar uma regra de transferência do Amazon Connect (opcional) Para permitir que o agente transfira o chamador para uma pessoa, dê a ele a ferramenta de sistema **Transferir para número** com uma regra de transferência cuja configuração de provedor seja `amazon_connect`. A regra não tem destino: a sessão termina com o resultado `Escalate`, e seu fluxo de contato escolhe a fila. As regras de transferência são configuradas pela API. Adicione a ferramenta com um `PATCH` no 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"}} ] }] } } }}}} }' ``` Envie o objeto `built_in_tools` completo do agente, incluindo ferramentas que ele já possui, como `end_call`. O agente escolhe a regra pela `condition`; a opção retornada é o token fixo `amazon_connect`, portanto basta uma regra do Amazon Connect por ferramenta. Números de telefone e URIs SIP configurados para outros provedores não são oferecidos em chamadas do Amazon Connect. > **Note** > > As regras de transferência são uma configuração gerenciada pela API. Configure e atualize a ferramenta **Transferir para número** > de um agente que as utiliza pela API, como acima; o editor de ferramentas do painel funciona com a > lista de transferências por número. #### Criar uma chave de API exclusiva Crie uma chave de API no mesmo workspace do agente e limite-a ao ElevenAgents. Você vai armazená-la no AWS Secrets Manager na próxima seção; não a cole em nenhum outro lugar. #### Anotar a URL do WebSocket O Amazon Connect se conecta a uma URL que contém o ID do seu agente: | Ambiente | AccessUrl | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | Padrão | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Residência de dados | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > Se sua conta da ElevenLabs estiver em um ambiente isolado de residência, substitua `` pelo código da > sua região. Consulte [residência de dados](/docs/pt/overview/administration/data-residency) para ver as regiões > disponíveis. ## Registrar o aplicativo da ElevenLabs na AWS Tudo nesta seção é uma chamada de API. Defina uma vez os valores que você reutilizará: ```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 ``` #### Criar um assistente do Amazon Q in Connect Ignore esta etapa se a instância já tiver um assistente. Caso contrário, crie um e associe-o à instância: ```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 ``` Registre o ID e o ARN do assistente. #### Armazenar a chave de API O Amazon Connect lê a chave do Secrets Manager com seu próprio principal de serviço, portanto o segredo precisa ser criptografado com uma chave KMS gerenciada pelo cliente que conceda ao `connect.amazonaws.com` acesso para descriptografar. A chave padrão `aws/secretsmanager` não pode ser usada. **`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": "*" } ] } ``` Salve a chave de API da ElevenLabs em um arquivo para que ela nunca apareça no histórico do shell e, então, crie a chave e o segredo: ```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 ``` Conceda ao Amazon Connect acesso de leitura ao segredo: **`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 ``` ![Segredo do Secrets Manager criptografado com a chave gerenciada pelo cliente e sua política de recurso para connect.amazonaws.com](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### Criar o aplicativo de terceiros Registre a URL do WebSocket da ElevenLabs como um aplicativo AppIntegrations do tipo `A2A_SERVER`. `AuthConfig` é obrigatório para esse 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" ``` A resposta contém o `Id` e o `Arn` do aplicativo; exporte-os como `APPLICATION_ID` e `APPLICATION_ARN`. O console do Amazon Connect não lista aplicativos `A2A_SERVER`, então confirme com a API: ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### Associar o aplicativo à sua instância ```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 ``` #### Permitir o aplicativo em um perfil de segurança O perfil de segurança associado ao agente de IA de orquestração precisa listar o aplicativo entre os agentes de IA permitidos; caso contrário, a transferência falhará em tempo de execução. ```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" ``` O site de administração mostra o perfil e as permissões dele, mas não os agentes de IA permitidos; eles só ficam visíveis pela API. ![Perfil de segurança exclusivo no site de administração do Amazon Connect com permissões de visualização de agentes de IA](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### Criar e publicar o agente de IA de orquestração O agente de orquestração transfere imediatamente todas as conversas de voz para o aplicativo, com streaming de áudio habilitado. As sessões de voz exigem transferência imediata; streaming de texto (`audioStreamingEnabled` definido como false) e `delegateAgentConfiguration` não são compatíveis com a ElevenLabs. Um orquestrador de transferência imediata de áudio também precisa declarar a ferramenta reservada `Complete` do tipo `RETURN_TO_CONTROL` em `toolConfigurations`; sem ela, a solicitação de criação falha com `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 ``` A publicação retorna um ARN versionado (`:1`); o fluxo de contato o referencia. Anexe o perfil de segurança tanto ao agente sem versão quanto ao agente versionado: ```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 de IA de orquestração no designer de agentes de IA com o perfil de segurança exclusivo anexado](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## Criar o fluxo de contato #### Criar o bot Lex 1. Crie um bot Lex V2 cuja única intenção seja a `AMAZON.QInConnectIntent` integrada, configurada com o ARN do seu assistente. Não adicione outras intenções. 2. Habilite fala para fala na localidade do bot. O streaming de áudio bidirecional só funciona com bots Sonic de fala para fala. 3. Permita que a função IAM do bot use o assistente. Sem isso, a transferência falha dentro da AWS com `HTTP 403` antes que qualquer solicitação chegue à ElevenLabs. Anexe uma política como esta: **`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. Crie o bot, crie uma versão e um alias e associe o alias à instância: ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Lista de intenções do bot Lex V2 com a intenção de transferência do Q in Connect e a intenção de fallback integrada](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### Adicionar o assistente e o bloco Lex No designer de fluxo, adicione estes blocos na ordem: 1. **Definir comportamento de registro**: habilitado. O log do fluxo é como você verifica a transferência abaixo. 2. **Conectar assistente**: selecione seu assistente do Amazon Q in Connect. 3. **Obter informações do cliente**: na guia **Amazon Lex**, escolha **Inserir um ARN** e cole o ARN do alias do bot. Deixe o prompt de conversão de texto em fala como um único espaço para que o Amazon Connect não reproduza nada antes da transferência. Em **Atributos da sessão**, adicione dois atributos definidos manualmente: | Chave de destino | Valor | | ------------------------------------- | ----------------------------------------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | O ARN do agente de orquestração versionado (`...:1`). | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Atributos de sessão do bloco Obter informações do cliente: o ARN do agente de IA versionado e a sinalização de passagem de áudio](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` controla o caminho de voz de terceiros durante o período de pré-lançamento da AWS. > A AWS informa que o atributo deixa de ser necessário quando o recurso se torna público; mantê-lo > não causa problemas. #### Criar ramificações com base no resultado O Amazon Connect disponibiliza o resultado da ElevenLabs para o fluxo como o atributo `$.Lex.SessionAttributes.Tool`. Adicione um bloco **Verificar atributos de contato** depois do bloco Lex, defina **Namespace** como **Lex**, **Chave** como **Atributos da sessão** e **Chave de atributo da sessão** como `Tool`; depois, adicione uma condição **É igual a** para cada resultado e direcione **Sem correspondência** para um prompt de erro: | Ramificação | Significado | Rota sugerida | | ------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | `Complete` | O agente encerrou a chamada, por exemplo com a ferramenta **Encerrar chamada**. | Desconectar | | `Escalate` | O agente solicitou uma pessoa (consulte [Transferir para uma pessoa](#transferring-to-a-human)). | Definir fila de trabalho → Transferir para fila | | Sem correspondência | Qualquer outro valor. | Reproduzir prompt → Desconectar | ![Bloco Verificar atributos de contato configurado no atributo de sessão Lex Tool com condições É igual a para cada resultado](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > O Amazon Connect grava o resultado em formato de título (`Escalate`, `Complete`), não como o tipo de finalização em > maiúsculas enviado na transmissão, portanto essas duas condições são tudo de que o bloco precisa. Uma sessão que > falha depois da transferência termina com o tipo `COMPLETE_WITH_ERROR`; o bloco Lex então segue pela saída > **Erro** ou a comparação cai em **Sem correspondência**, então direcione ambos para o prompt de erro. > Em um fluxo exportado, a saída **Padrão** do bloco Lex é sua transição `NoMatchingCondition`; > verifique se ela leva ao bloco de comparação, em vez de a uma mensagem de erro. ![Fluxo de contato com o bloco Obter informações do cliente levando a um bloco Verificar atributos de contato que direciona Escalate para uma fila, Complete para desconexão e Sem correspondência para um prompt de erro](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### Publicar e atribuir Publique o fluxo e direcione um número de telefone reivindicado para ele: ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` Para chamadas de saída, inicie o contato com o mesmo fluxo; o Amazon Connect liga para o cliente e transfere a chamada atendida para 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 ``` ## Testar a integração #### Fazer uma chamada Ligue para o número. A primeira mensagem do agente é reproduzida alguns segundos depois que o fluxo chega ao bloco Lex; a transferência dentro da AWS leva cerca de três segundos antes que a ElevenLabs seja contatada. Tenha uma conversa breve e diga adeus: o agente chama **Encerrar chamada**, a sessão da ElevenLabs termina com `Complete`, e seu fluxo continua a partir do bloco Lex. Se você adicionou uma regra de transferência, peça para falar com uma pessoa: o agente chama **Transferir para número**, a sessão termina com `Escalate`, e o fluxo segue essa ramificação. #### Verificar a conversa na ElevenLabs Abra a conversa em **Conversas**. A origem dela é o Amazon Connect, e a guia **Dados do cliente** lista as variáveis dinâmicas `amazon_connect_*` recebidas pela sessão. ![Guia Dados do cliente de uma conversa do Amazon Connect listando as variáveis dinâmicas do Amazon Connect](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### Verificar o log do fluxo na AWS Com o registro habilitado, cada bloco grava uma entrada no grupo de logs de fluxo da instância. O bloco **Obter informações do cliente** registra o resultado recebido 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_]*"' ``` Espere por `"Results": "Complete"` ou, após uma transferência, `"Results": "Escalate"` para o bloco Lex, seguidos pelos blocos dessa ramificação. ## Variáveis dinâmicas O Amazon Connect envia os atributos de sistema do contato em todas as sessões. A ElevenLabs os disponibiliza, junto com os identificadores da sessão, como variáveis dinâmicas: | Variável dinâmica | Descrição | | ------------------------------------------------------------ | ------------------------------------------------------------------------ | | `system__caller_id` | O número de telefone do cliente (endpoint de cliente do Amazon Connect). | | `system__called_number` | O número do Amazon Connect em que o contato está (endpoint do sistema). | | `system__call_id` | O ID de contato do Amazon Connect. | | `amazon_connect_system_attributes_channel` | O canal de contato, por exemplo, `VOICE`. | | `amazon_connect_system_attributes_customer_endpoint_address` | O endereço do endpoint do cliente conforme enviado pelo Amazon Connect. | | `amazon_connect_system_attributes_system_endpoint_address` | O endereço do endpoint do sistema conforme enviado pelo Amazon Connect. | | `amazon_connect_interaction_mode` | O modo de colaboração, por exemplo, `HANDOFF`. | | `amazon_connect_contact_id` | O ID de contato do Amazon Connect. | | `amazon_connect_contact_arn` | O ARN completo do contato. | | `amazon_connect_context_id` | O ID da sessão A2A (contexto). | | `amazon_connect_instance_id` | O ID da instância. | | `amazon_connect_instance_arn` | O ARN da instância. | Nas sessões do Amazon Connect, `system__caller_id` é sempre o cliente, e `system__called_number` é sempre o número do Amazon Connect, tanto para contatos recebidos quanto para contatos de saída. Todos os outros membros do contexto de contato enviados pelo Amazon Connect são disponibilizados da mesma forma: os nomes aninhados são unidos por sublinhados e convertidos para snake case sob o prefixo `amazon_connect_`. Atributos de contato personalizados definidos no seu fluxo com **Definir atributos de contato** não fazem parte do contexto que o Amazon Connect envia atualmente, mesmo quando o perfil de segurança do agente de IA pode visualizar atributos de contato; se a AWS começar a incluí-los, eles aparecerão automaticamente sob o mesmo prefixo. Você não pode escolher quais dados de contato o Amazon Connect compartilha; a AWS transmite um conjunto fixo de contexto. Para transmitir contexto adicional, use o [webhook de início de conversa](/docs/pt/eleven-agents/customization/personalization#conversation-initiation-webhooks). Para sessões do Amazon Connect, o webhook é chamado antes de o agente falar, com `caller_id` definido como o número do cliente, `called_number` definido como o número do Amazon Connect e `call_id` definido como o ID de contato do Amazon Connect, portanto uma Lambda no seu fluxo pode armazenar atributos de contato indexados pelo ID de contato e o webhook pode retorná-los como variáveis dinâmicas e substituições de configuração. ## Transferência para um atendente humano Dê ao agente a ferramenta de sistema **Transferir para número** com uma regra de transferência `amazon_connect`, como mostrado em [Configurar o ElevenLabs](#configure-elevenlabs). Quando a condição da regra é atendida, o agente chama a ferramenta, e o ElevenLabs encerra a sessão com o resultado `Escalate` e o motivo informado pelo agente. A ramificação `Escalate` do seu fluxo então atende o contato com **Definir fila de trabalho** e **Transferir para fila**. A regra não contém um destino, então a fila é escolhida no fluxo, e não pelo agente; o tratamento da fila, os fluxos de sussurro e a seleção de atendente permanecem no Amazon Connect. A ferramenta **Encerrar chamada** gera um resultado `Complete`. A análise pós-chamada e o webhook pós-chamada são executados normalmente após qualquer um dos resultados. ### Como fornecer um resumo ao atendente humano O Amazon Connect expõe apenas o resultado ao seu fluxo: `$.Lex.SessionAttributes.Tool` (e o nome da intenção Lex) contém `Escalate`, e nenhuma outra informação da sessão do ElevenLabs, incluindo o motivo da transferência, chega ao fluxo. Para informar a pessoa que atende a chamada, armazene você mesmo o resumo no contato e deixe um fluxo de sussurro para atendente lê-lo: 1. Exponha um endpoint que chama a API `UpdateContactAttributes` do Amazon Connect. Uma Lambda mínima por trás de uma API HTTP é suficiente; o chamador precisa ter permissão para usar `connect:UpdateContactAttributes` nos contatos da instância: ```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. Dê ao agente uma [ferramenta de webhook](/docs/pt/eleven-agents/customization/tools/webhook-tools) que faça `POST` nesse endpoint com `contact_id` preenchido pela variável dinâmica `amazon_connect_contact_id` e um `summary` escrito pelo modelo. Mantenha o segredo compartilhado em um segredo do workspace e envie-o como cabeçalho da solicitação. No prompt do sistema, instrua o agente a chamar essa ferramenta primeiro e chamar **Transferir para número** somente depois que ela retornar; um modelo que emite as duas chamadas no mesmo turno coloca a transferência e o resumo em uma corrida. Com essa instrução, em nossos testes o atributo estava no contato cerca de um segundo após a solicitação do agente, três segundos antes de o Amazon Connect retomar o fluxo. 3. Na ramificação `Escalate` do fluxo de contato, adicione um bloco **Definir fluxo de sussurro** antes de **Transferir para fila** que aponte para um fluxo de sussurro para atendente cujo **Reproduzir prompt** leia `$.Attributes.handoff_summary`. O Amazon Connect o reproduz para o atendente humano enquanto a pessoa que ligou ouve o tratamento da fila e, em seguida, conecta os dois. Não defina `handoff_summary` novamente em um bloco posterior do fluxo: um valor vazio ali substitui o que o endpoint gravou. O mesmo atributo está disponível para um bloco **Verificar atributos de contato** para decisões de roteamento. O webhook pós-chamada é disparado depois que o fluxo já continuou, portanto é adequado para atualizações no CRM, não para decisões de roteamento. ## Rastreamentos O Amazon Connect [exige que agentes externos enviem dados de rastreamento](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html) para cada colaboração. Quando o Amazon Connect assina o rastreamento da sessão, o ElevenLabs envia um rastreamento OpenTelemetry para cada turno do agente contendo a transcrição de quem ligou, a resposta do agente, cada chamada de ferramenta com seu resultado e o tempo de cada span. O Amazon Connect armazena esses rastreamentos com o contato; consulte [rastreamentos de agentes de IA](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html) para saber como visualizá-los. As transcrições e os resultados de ferramentas nesses rastreamentos estão sujeitos às mesmas configurações de remoção de dados que o restante dos dados de contato no Amazon Connect, portanto analise seus requisitos de tratamento de dados antes de ativar a integração. Assim como os [webhooks pós-chamada](/docs/pt/eleven-agents/workflows/post-call-webhooks), os rastreamentos são enviados para seus próprios sistemas: agentes no [modo de retenção zero](/docs/pt/eleven-agents/customization/privacy/zrm) ainda os enviam, porque a retenção zero controla o que o ElevenLabs armazena, e não o que sua instância do Amazon Connect recebe. ## Áudio O Amazon Connect propõe PCM linear mono de 16 bits a 8, 16 ou 24 kHz em cada sessão, e o ElevenLabs adota a proposta; portanto, os formatos de áudio configurados para o agente não são usados nas sessões do Amazon Connect. A interrupção por fala de quem ligou é detectada pelo ElevenLabs e informada ao Amazon Connect para que a reprodução em buffer seja interrompida imediatamente. A entrada pelo teclado coletada pelo Amazon Connect é entregue ao agente como dígitos DTMF. O marcador de silêncio do próprio Amazon Connect é ignorado; use o tempo limite de turno do agente para perguntar novamente a uma pessoa que ligou e está em silêncio. ## Limitações e recursos não compatíveis * Ferramentas de cliente e a ferramenta de sistema **Reproduzir tom de tecla** não são compatíveis. **Transferir para número** funciona apenas por meio de uma regra de transferência do Amazon Connect: o agente não pode discar para um número de telefone ou URI SIP a partir de uma chamada do Amazon Connect, e o fluxo decide qual fila recebe uma pessoa que ligou escalada. * Os resultados da coleta de dados não são retornados ao fluxo, e o Amazon Connect decide quais dados de contato compartilha. Use o webhook de início de conversa associado a `amazon_connect_contact_id` para obter contexto adicional, uma ferramenta de webhook que chama `UpdateContactAttributes` para dados de roteamento e o webhook pós-chamada para todo o restante. * Substituições de configuração, como `system__override_first_message`, não podem ser passadas pelo fluxo. Em vez disso, retorne-as pelo webhook de início de conversa. * As sessões de voz exigem transferência imediata. O canal de chat do Amazon Connect, o streaming de texto e a colaboração em segundo plano (`delegateAgentConfiguration`) não são compatíveis. * Os rastreamentos enviados ao Amazon Connect abrangem a transcrição de quem ligou, as respostas do agente, chamadas de ferramentas com seus resultados e o tempo. Os parâmetros de chamadas de ferramentas não são incluídos. * O suporte do Amazon Connect a agentes de terceiros está disponível somente onde a AWS o habilitou e pode gerar cobranças adicionais da AWS. ## Solução de problemas #### O fluxo falha com 'A2A WebSocket upgrade ... failed (HTTP 403)' * O erro é gerado dentro da AWS antes que qualquer solicitação chegue ao ElevenLabs. Verifique o CloudTrail em busca de `AccessDenied` em `wisdom:SendMessage` da função de serviço do Lex: a função anexada ao bot precisa de `wisdom:CreateSession`, `wisdom:GetAssistant`, `wisdom:SendMessage` e `wisdom:GetNextMessage` no assistente e em suas sessões. * Confirme que o perfil de segurança permite o aplicativo e está associado à versão publicada do agente de orquestração referenciada pelo fluxo. * Confirme que a chave KMS e a política de recursos do segredo concedem acesso a `connect.amazonaws.com`. #### O fluxo falha com 'the hand-off to the target agent could not be completed' * O Amazon Connect dá à conexão WebSocket cerca de 20 segundos para ser estabelecida. Confirme que a `AccessUrl` está acessível pela AWS: `wss://`, o ID correto do agente e nenhuma lista de permissão de rede bloqueando o acesso. * Se você direciona a conexão por proxy pela sua própria infraestrutura, mantenha esse proxy ativo. Uma instância serverless iniciada a frio pode levar mais tempo do que a janela de transferência, e o Amazon Connect desiste antes que o ElevenLabs sequer veja a solicitação. #### O bloco Lex segue pela ramificação Error e quem ligou não ouve nada * Confirme que ambos os atributos de sessão estão definidos no bloco **Obter entrada do cliente**: `x-amz-lex:q-in-connect:ai-agent-arn` com o ARN do agente publicado e versionado, e `x-amz-lex:qic-audio-passthrough` definido como `true`. * Confirme que o perfil de segurança que permite o aplicativo está anexado àquela versão do agente. * Leia a entrada do bloco no log do fluxo; ela contém o erro encontrado pelo Amazon Connect. #### A sessão termina imediatamente após a conexão * Confirme que a `AccessUrl` usa `wss://`, contém o ID correto do agente e aponta para a região em que seu workspace está localizado. * Confirme que a chave de API está ativa, pertence ao workspace do agente e não tem restrições de IP. * Confirme que o transporte do Amazon Connect está habilitado para seu workspace. #### Quem ligou ouve o prompt de erro do fluxo depois que o agente termina No bloco Lex, certifique-se de que a saída **Padrão** leva ao bloco que compara `$.Lex.SessionAttributes.Tool` e compare com os valores em caixa de título `Escalate` e `Complete`. #### O agente nunca fala e a sessão termina após alguns segundos Confirme que o colaborador está configurado com `audioStreamingEnabled` definido como true. Com o streaming de texto, o Amazon Connect envia turnos de texto e espera respostas de texto, algo que o ElevenLabs não oferece suporte; os logs do ElevenLabs mostram `INIT_SESSION carries no audio configuration`. #### Variáveis dinâmicas estão ausentes O Amazon Connect fornece os atributos e identificadores de sistema de contato listados acima. Atributos de contato personalizados definidos no fluxo não chegam ao agente; passe-os pelo webhook de início de conversa. Se a primeira mensagem ou o prompt do agente fizer referência a uma variável que nunca é fornecida, a sessão falhará na inicialização.