Amazon Connect

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 agente de IA de terceiros do Amazon Connect, uma extensão do protocolo A2A aberto. O Amazon Connect é responsável pela telefonia, pelo roteamento e pela fila; o ElevenAgents é responsável pela conversa. Não é necessário tronco SIP, número da Twilio nem middleware. A AWS documenta o recurso em Colaboração entre agentes; este guia, abordamos as particularidades da ElevenLabs e as etapas da AWS necessárias para acessar um agente da ElevenLabs.

O mesmo fluxo atende chamadas recebidas e contatos de saída iniciados com StartOutboundVoiceContact. Quando o agente da ElevenLabs finaliza, o Amazon Connect continua seu fluxo de contato e cria ramificações com base no resultado recebido.

Como funciona a integração

1. Um fluxo de contato chega a um bloco Obter entrada 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 imediatamente a conversa 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, em seguida, 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 no agente.
5. Quando o agente encerra a chamada, a ElevenLabs finaliza a sessão com o resultado Complete, e o fluxo continua a partir do bloco Lex. O resultado Escalate, que encaminha o chamador para uma fila humana, é compatível no protocolo e será disponibilizado pela ferramenta de transferência; consulte Transferir para uma pessoa.

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 ativado 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 do AppIntegrations, perfis de segurança do Connect, agentes de IA do Amazon Q in Connect, bots do Lex V2 e fluxos de contato.
4. Um workspace da ElevenLabs com o transporte Amazon Connect ativado.
5. Um agente da ElevenLabs e uma chave de API exclusiva.
6. AWS CLI v2 e awscurl (pip install awscurl) para as chamadas cujos formatos de solicitação ainda não estão nas versões lançadas da CLI.

Configure a ElevenLabs

Registre o aplicativo da ElevenLabs na AWS

Tudo nesta seção é uma chamada de API. Defina uma vez os valores que você reutilizará:

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

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

Crie o fluxo de contato

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

Teste a integração

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

Variáveis dinâmicas

O Amazon Connect envia os atributos do sistema do contato em cada sessão. A ElevenLabs os disponibiliza, junto com os identificadores da sessão, como variáveis dinâmicas:

Em 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 de entrada quanto de saída.

Todos os outros membros do contexto de contato enviados pelo Amazon Connect são disponibilizados da mesma forma: nomes aninhados são unidos com 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 os 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 envia um conjunto fixo de contexto.

Para enviar contexto adicional, use o webhook de início da conversa. Para sessões do Amazon Connect, o webhook é chamado antes que o agente fale, 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. Assim, uma Lambda no seu fluxo pode armazenar atributos de contato usando o ID do contato como chave, e o webhook pode retorná-los como variáveis dinâmicas e substituições de configuração.

Transferência para uma pessoa

O Amazon Connect encaminha um contato para uma fila humana quando a sessão da ElevenLabs termina com um resultado Escalate, que a ramificação Escalate do seu fluxo processa com Definir fila de trabalho e Transferir para fila. Qualquer tratamento de fila, fluxo de sussurro ou seleção de agente é gerenciado pelo 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.

Apenas o tipo de resultado e uma string de motivo retornam ao Amazon Connect. Para passar dados de roteamento ao fluxo, forneça ao agente uma ferramenta de webhook que chame a API UpdateContactAttributes do Amazon Connect com amazon_connect_contact_id e os valores a armazenar, e instrua o agente a chamá-la antes de encerrar a chamada. O fluxo pode então ler esses atributos com um bloco Verificar atributos de contato após o bloco Lex. O webhook pós-chamada é acionado depois que o fluxo já continuou, portanto é mais adequado para atualizações de CRM do que para decisões de roteamento.

Rastreamentos

O Amazon Connect exige que agentes externos enviem dados de rastreamento para cada colaboração. Quando o Amazon Connect assina o rastreamento na sessão, a ElevenLabs envia um rastreamento OpenTelemetry para cada turno do agente contendo a transcrição do chamador, 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 para saber como visualizá-los. As transcrições e os resultados de ferramentas nesses rastreamentos estão sujeitos às mesmas configurações de redação que o restante dos seus dados de contato no Amazon Connect. Portanto, revise seus requisitos de tratamento de dados antes de ativar a integração. Assim como os webhooks pós-chamada, os rastreamentos são entregues aos seus próprios sistemas: agentes no modo de retenção zero ainda os enviam, porque a retenção zero rege o que a 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 a ElevenLabs adota a proposta. Portanto, os formatos de áudio configurados do agente não são usados em sessões do Amazon Connect. A interrupção do chamador é detectada pela 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 próprio marcador de silêncio do Amazon Connect é ignorado; use o tempo limite de turno do agente para solicitar novamente a um chamador silencioso.

Limitações e recursos não compatíveis

• As ferramentas de cliente e a ferramenta do sistema Reproduzir tom de tecla do teclado não são compatíveis. Transferir para número ainda não é compatível com o Amazon Connect; a transferência para uma pessoa chegará como um tipo de transferência do Amazon Connect nessa ferramenta.
• 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 da conversa identificado por amazon_connect_contact_id para contexto adicional, uma ferramenta de webhook que chame UpdateContactAttributes para dados de roteamento e o webhook pós-chamada para todo o resto.
• Substituições de configuração, como system__override_first_message, não podem ser transmitidas pelo fluxo. Em vez disso, retorne-as pelo webhook de início da 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) ainda não são compatíveis.
• Os rastreamentos enviados ao Amazon Connect abrangem a transcrição do chamador, as respostas do agente, chamadas de ferramentas com seus resultados e tempos. Os parâmetros das chamadas de ferramentas não são incluídos.
• O suporte do Amazon Connect a agentes de terceiros está disponível apenas onde a AWS o habilitou e pode gerar cobranças adicionais da AWS.

Solução de problemas