Amazon Connect

Resumen

La integración con Amazon Connect conecta un flujo de contactos de Amazon Connect directamente con un agente de ElevenAgents mediante el protocolo de agentes de IA de terceros de Amazon Connect, una extensión del protocolo A2A abierto. Amazon Connect gestiona la telefonía, el enrutamiento y la cola; ElevenAgents gestiona la conversación. No se necesita ningún troncal SIP, número de Twilio ni middleware. AWS documenta esta función en Colaboración entre agentes; esta guía cubre los aspectos específicos de ElevenLabs y los pasos de AWS necesarios para llegar a un agente de ElevenLabs.

El mismo flujo sirve para llamadas entrantes y contactos salientes iniciados con StartOutboundVoiceContact. Cuando el agente de ElevenLabs termina, Amazon Connect continúa con tu flujo de contactos y se bifurca según el resultado recibido.

Cómo funciona la integración

1. Un flujo de contactos llega a un bloque Obtener información del cliente que invoca un bot de Amazon Lex V2 con la intención AMAZON.QInConnectIntent.
2. El agente de IA de orquestación de Amazon Connect transfiere la conversación inmediatamente a la aplicación de terceros que registraste para ElevenLabs.
3. Amazon Connect abre un WebSocket al endpoint de ElevenLabs en el AccessUrl de la aplicación, autenticándose con la clave de API almacenada en AWS Secrets Manager.
4. Amazon Connect indica que el canal de la persona que llama está activo; después, Amazon Connect y ElevenLabs intercambian audio PCM lineal de 16 bits como mensajes A2A. Amazon Connect propone la frecuencia de muestreo y ElevenLabs la adopta, por lo que el agente no necesita cambios de formato de audio.
5. Cuando el agente finaliza la llamada, ElevenLabs termina la sesión con el resultado Complete y el flujo continúa desde el bloque de Lex. El resultado Escalate, que dirige a la persona que llama a una cola humana, es compatible a nivel de protocolo y se expondrá mediante la herramienta de transferencia; consulta Transferir a una persona.

Requisitos

Antes de empezar, asegúrate de tener:

1. Una instancia de Amazon Connect en el nivel Connect Customer con la compatibilidad con agentes de IA de terceros habilitada para la cuenta y la región.
2. Un asistente de Amazon Q in Connect asociado a la instancia.
3. Permisos de AWS para crear claves KMS, secretos de Secrets Manager, aplicaciones de AppIntegrations, perfiles de seguridad de Connect, agentes de IA de Amazon Q in Connect, bots de Lex V2 y flujos de contactos.
4. Un espacio de trabajo de ElevenLabs con el transporte de Amazon Connect habilitado.
5. Un agente de ElevenLabs y una clave de API dedicada.
6. AWS CLI v2 y awscurl (pip install awscurl) para las llamadas cuyas estructuras de solicitud aún no están en las versiones publicadas de la CLI.

Configura ElevenLabs

Registra la aplicación de ElevenLabs en AWS

Todo lo que hay en esta sección es una llamada a la API. Define una vez los valores que reutilizarás:

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

Crea el flujo de contactos

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

Prueba la integración

aws logs filter-log-events --log-group-name /aws/connect/<INSTANCE_ALIAS> \
  --start-time $(( $(date +%s) - 600 ))000 --region $AWS_REGION \
  --query 'events[].message' --output text | tr '\t' '\n' | grep -o '"Results": *"[A-Za-z_]*"'

Variables dinámicas

Amazon Connect envía los atributos del sistema del contacto en cada sesión. ElevenLabs los expone, junto con los identificadores de sesión, como variables dinámicas:

En las sesiones de Amazon Connect, system__caller_id siempre corresponde al cliente y system__called_number siempre corresponde al número de Amazon Connect, tanto para contactos entrantes como salientes.

Todos los demás elementos del contexto de contacto que envía Amazon Connect se exponen del mismo modo: los nombres anidados se unen con guiones bajos y se convierten a snake case con el prefijo amazon_connect_. Los atributos de contacto personalizados que configures en tu flujo con Establecer atributos de contacto no forman parte del contexto que Amazon Connect envía actualmente, aunque el perfil de seguridad del agente de IA pueda ver los atributos de contacto; si AWS empieza a incluirlos, aparecerán automáticamente con el mismo prefijo. No puedes elegir qué datos de contacto comparte Amazon Connect; AWS transmite un conjunto fijo de contexto.

Para pasar contexto adicional, usa el webhook de inicio de conversación. En las sesiones de Amazon Connect, el webhook se llama antes de que el agente hable con caller_id establecido en el número del cliente, called_number en el número de Amazon Connect y call_id en el ID de contacto de Amazon Connect, de modo que una Lambda en tu flujo puede almacenar atributos de contacto indexados por ID de contacto y el webhook puede devolverlos como variables dinámicas y anulaciones de configuración.

Transferencia a una persona

Amazon Connect enruta un contacto a una cola humana cuando la sesión de ElevenLabs termina con un resultado Escalate, que la rama Escalate de tu flujo gestiona con Establecer cola de trabajo y Transferir a cola. Amazon Connect gestiona cualquier tratamiento de cola, flujo de susurro o selección de agente.

La herramienta Finalizar llamada genera un resultado Complete. El análisis posterior a la llamada y el webhook posterior a la llamada se ejecutan como siempre tras cualquiera de los dos resultados.

Solo el tipo de resultado y una cadena con el motivo se transmiten de vuelta a Amazon Connect. Para entregar datos de enrutamiento al flujo, proporciona al agente una herramienta de webhook que llame a la API UpdateContactAttributes de Amazon Connect con amazon_connect_contact_id y los valores que quieres almacenar, e indica al agente que la llame antes de finalizar la llamada. Después, el flujo puede leer esos atributos con un bloque Comprobar atributos de contacto después del bloque de Lex. El webhook posterior a la llamada se activa después de que el flujo ya haya continuado, por lo que es adecuado para actualizaciones de CRM en lugar de decisiones de enrutamiento.

Trazas

Amazon Connect requiere que los agentes externos envíen datos de trazas para cada colaboración. Cuando Amazon Connect se suscribe al trazado de la sesión, ElevenLabs envía una traza de OpenTelemetry para cada turno del agente que contiene la transcripción de quien llama, la respuesta del agente, cada llamada de herramienta con su resultado y el tiempo por span. Amazon Connect almacena estas trazas con el contacto; consulta trazas de agentes de IA para saber cómo verlas. Las transcripciones y los resultados de herramientas de estas trazas están sujetos a la misma configuración de redacción que el resto de los datos de contacto en Amazon Connect, así que revisa tus requisitos de tratamiento de datos antes de activar la integración. Al igual que los webhooks posteriores a la llamada, las trazas se entregan a tus propios sistemas: los agentes en modo de retención cero siguen enviándolas, porque la retención cero regula lo que almacena ElevenLabs, no lo que recibe tu instancia de Amazon Connect.

Audio

Amazon Connect propone PCM lineal mono de 16 bits a 8, 16 o 24 kHz en cada sesión y ElevenLabs acepta la propuesta, por lo que los formatos de audio configurados para el agente no se utilizan en las sesiones de Amazon Connect. ElevenLabs detecta la interrupción por parte de quien llama y la comunica a Amazon Connect para que la reproducción almacenada en búfer se vacíe de inmediato. La entrada de teclado recopilada por Amazon Connect se entrega al agente como dígitos DTMF. Se ignora el marcador de silencio propio de Amazon Connect; usa el tiempo de espera de turno del agente para volver a preguntar a quien llama si permanece en silencio.

Limitaciones y funciones no compatibles

• Las herramientas de cliente y la herramienta de sistema Reproducir tono de teclas no son compatibles. Transferir a número aún no es compatible con Amazon Connect; la derivación a una persona llegará como un tipo de transferencia de Amazon Connect en esa herramienta.
• Los resultados de recopilación de datos no se devuelven al flujo, y Amazon Connect decide qué datos de contacto comparte. Usa el webhook de inicio de conversación con amazon_connect_contact_id como clave para contexto adicional, una herramienta de webhook que llame a UpdateContactAttributes para datos de enrutamiento y el webhook posterior a la llamada para todo lo demás.
• Las anulaciones de configuración como system__override_first_message no se pueden pasar desde el flujo. Devuélvelas desde el webhook de inicio de conversación.
• Las sesiones de voz requieren derivación inmediata. El canal de chat de Amazon Connect, el streaming de texto y la colaboración en segundo plano (delegateAgentConfiguration) aún no son compatibles.
• Las trazas enviadas a Amazon Connect incluyen la transcripción de quien llama, las respuestas del agente, las llamadas a herramientas con sus resultados y el tiempo. No se incluyen los parámetros de las llamadas a herramientas.
• La compatibilidad de Amazon Connect con agentes de terceros solo está disponible donde AWS la haya activado y puede conllevar cargos adicionales de AWS.

Solución de problemas