> 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** > > La integración con Amazon Connect tiene disponibilidad limitada. La compatibilidad con agentes de IA > de terceros de Amazon Connect debe estar habilitada para tu cuenta de AWS, y el transporte de > ElevenLabs se habilita por espacio de trabajo. Ponte en contacto con tu representante de ElevenLabs > antes de dirigir tráfico de clientes. ## Descripción general La integración con Amazon Connect conecta un flujo de contacto 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 abierto [A2A](https://a2a-protocol.org/). Amazon Connect se encarga de la telefonía, el enrutamiento y la cola; ElevenAgents se encarga de la conversación. No necesitas un troncal SIP, un número de Twilio ni middleware. AWS documenta esta función en [Colaboración entre agentes](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html); esta guía explica los detalles específicos de ElevenLabs y los pasos de AWS necesarios para llegar a un agente de ElevenLabs. El mismo flujo sirve tanto para llamadas entrantes como para contactos salientes iniciados con `StartOutboundVoiceContact`. Cuando el agente de ElevenLabs termina, Amazon Connect continúa tu flujo de contacto y se ramifica según el resultado recibido. ## Cómo funciona la integración 1. Un flujo de contacto 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 inmediatamente la conversación 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 señala 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 no se necesitan cambios de formato de audio en el agente. 5. Cuando el agente termina la llamada o transfiere a la persona que llama a una persona, ElevenLabs finaliza la sesión con un resultado `Complete` o `Escalate` y el flujo continúa desde el bloque de Lex; consulta [Transferir a una persona](#transferring-to-a-human). ## 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 AppIntegrations, perfiles de seguridad de Connect, agentes de IA de Amazon Q in Connect, bots de Lex V2 y flujos de contacto. 4. Un espacio de trabajo de ElevenLabs con el transporte de Amazon Connect habilitado. 5. Un agente de ElevenLabs y una clave de API exclusiva. 6. AWS CLI v2 y [awscurl](https://github.com/okigan/awscurl) (`pip install awscurl`) para las llamadas cuyas estructuras de solicitud aún no están disponibles en versiones publicadas de la CLI. > **Note** > > Mantén todos los recursos de AWS en la misma cuenta y región que la instancia de Amazon Connect. Los pasos > siguientes usan AWS CLI cuando admite la llamada y `awscurl` (una solicitud HTTP firmada con SigV4) cuando > no la admite. Siguen la guía de AWS [Configurar la colaboración con un agente de IA externo](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html) y añaden los valores > específicos de ElevenLabs. ## Configura ElevenLabs #### Crea o selecciona un agente Crea el agente en ElevenAgents. Dale un primer mensaje si debe hablar en cuanto se complete la transferencia; Amazon Connect no reproduce nada propio durante la sesión. #### Activa Finalizar llamada En **Agente → Herramientas → Herramientas del sistema**, activa **Finalizar llamada** para que el agente pueda terminar la sesión cuando se resuelva la solicitud de la persona que llama. Amazon Connect continuará entonces tu flujo con el resultado `Complete`. #### Añade una regla de transferencia de Amazon Connect (opcional) Para permitir que el agente transfiera a la persona que llama a una persona, asígnale la herramienta del sistema **Transferir a número** con una regla de transferencia cuya configuración de proveedor sea `amazon_connect`. La regla no tiene destino: la sesión termina con el resultado `Escalate` y tu flujo de contacto elige la cola. Las reglas de transferencia se configuran mediante la API. Añade la herramienta con un `PATCH` en el 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"}} ] }] } } }}}} }' ``` Envía el objeto completo `built_in_tools` del agente, incluidas las herramientas que ya tenga, como `end_call`. El agente elige la regla según su `condition`; la opción que devuelve es el token fijo `amazon_connect`, por lo que basta una regla de Amazon Connect por herramienta. Los números de teléfono y los URI SIP configurados para otros proveedores no se ofrecen en llamadas de Amazon Connect. > **Note** > > Las reglas de transferencia son una configuración gestionada mediante API. Configura y actualiza mediante la API, como arriba, > la herramienta **Transferir a número** de un agente que las use; el editor de herramientas del panel funciona con la lista de transferencias > por número. #### Crea una clave de API exclusiva Crea una clave de API en el mismo espacio de trabajo que el agente y limítala a ElevenAgents. La almacenarás en AWS Secrets Manager en la siguiente sección; no la pegues en ningún otro sitio. #### Anota la URL de WebSocket Amazon Connect se conecta a una URL que contiene el ID de tu agente: | Entorno | AccessUrl | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | Predeterminado | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Residencia de datos | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > Si tu cuenta de ElevenLabs está en un entorno aislado de residencia, sustituye `` por el código de tu > región. Consulta [residencia de datos](/docs/es/overview/administration/data-residency) para ver las regiones > disponibles. ## Registra la aplicación de ElevenLabs en AWS Todo lo incluido en esta sección es una llamada a la API. Define una vez los valores que reutilizarás: ```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 asistente de Amazon Q in Connect Omite este paso si la instancia ya tiene un asistente. De lo contrario, crea uno y asócialo con la instancia: ```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 ``` Anota el ID y el ARN del asistente. #### Almacena la clave de API Amazon Connect lee la clave de Secrets Manager con su propio principal de servicio, por lo que el secreto debe cifrarse con una clave KMS gestionada por el cliente que conceda a `connect.amazonaws.com` acceso para descifrar. No se puede usar la clave predeterminada `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": "*" } ] } ``` Guarda la clave de API de ElevenLabs en un archivo para que nunca aparezca en el historial de tu shell y, después, crea la clave y el secreto: ```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 ``` Concede a Amazon Connect acceso de lectura al secreto: **`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 ``` ![Secreto de Secrets Manager cifrado con la clave gestionada por el cliente y su política de recursos para connect.amazonaws.com](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### Crea la aplicación de terceros Registra la URL de WebSocket de ElevenLabs como una aplicación AppIntegrations de tipo `A2A_SERVER`. `AuthConfig` es obligatorio para este 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 respuesta contiene el `Id` y el `Arn` de la aplicación; expórtalos como `APPLICATION_ID` y `APPLICATION_ARN`. La consola de Amazon Connect no muestra las aplicaciones `A2A_SERVER`, así que verifica mediante la API: ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### Asocia la aplicación con tu instancia ```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 ``` #### Permite la aplicación en un perfil de seguridad El perfil de seguridad asociado al agente de IA de orquestación debe incluir la aplicación entre sus agentes de IA permitidos; de lo contrario, la transferencia falla en tiempo de ejecución. ```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" ``` El sitio web de administración muestra el perfil y sus permisos, pero no los agentes de IA permitidos; estos solo son visibles mediante la API. ![Perfil de seguridad exclusivo en el sitio web de administración de Amazon Connect con permisos para ver agentes de IA](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### Crea y publica el agente de IA de orquestación El agente de orquestación transfiere inmediatamente cada conversación de voz a la aplicación, con la transmisión de audio habilitada. Las sesiones de voz requieren una transferencia inmediata; la transmisión de texto (`audioStreamingEnabled` establecido en false) y `delegateAgentConfiguration` no son compatibles con ElevenLabs. Un orquestador de transferencia inmediata de audio también debe declarar la herramienta reservada `Complete` de tipo `RETURN_TO_CONTROL` en `toolConfigurations`; de lo contrario, la solicitud de creación falla 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 publicación devuelve un ARN con versión (`:1`); el flujo de contacto hace referencia a él. Asocia el perfil de seguridad tanto al agente sin versión como al agente con versión: ```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 orquestación en el diseñador de agentes de IA con el perfil de seguridad exclusivo asociado](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## Crea el flujo de contacto #### Crea el bot de Lex 1. Crea un bot de Lex V2 cuya única intención sea la integrada `AMAZON.QInConnectIntent`, configurada con el ARN de tu asistente. No añadas otras intenciones. 2. Activa voz a voz en la configuración regional del bot. La transmisión de audio bidireccional solo funciona con bots de voz a voz Sonic. 3. Permite que el rol IAM del bot use el asistente. Sin esto, la transferencia falla dentro de AWS con `HTTP 403` antes de que ninguna solicitud llegue a ElevenLabs. Asocia una 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. Compila el bot, crea una versión y un alias, y asocia el alias con la instancia: ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Lista de intenciones del bot Lex V2 con la intención de transferencia de Q in Connect y la intención integrada de respaldo](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### Añade el asistente y el bloque de Lex En el diseñador de flujos, añade estos bloques en orden: 1. **Configurar el comportamiento de registro**: activado. El registro del flujo te permite verificar la transferencia más abajo. 2. **Conectar asistente**: selecciona tu asistente de Amazon Q in Connect. 3. **Obtener información del cliente**: en la pestaña **Amazon Lex**, elige **Introducir un ARN** y pega el ARN del alias del bot. Deja el prompt de texto a voz como un único espacio para que Amazon Connect no reproduzca nada antes de la transferencia. En **Atributos de sesión**, añade dos atributos configurados manualmente: | Clave de destino | Valor | | ------------------------------------- | -------------------------------------------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | El ARN del agente de orquestación con versión (`...:1`). | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Atributos de sesión del bloque Obtener información del cliente: el ARN del agente de IA con versión y la marca de transferencia de audio](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` habilita la ruta de voz de terceros durante el periodo de prelanzamiento de AWS. > AWS indica que el atributo deja de ser necesario cuando la función es pública; mantenerlo > no causa problemas. #### Ramifica según el resultado Amazon Connect muestra el resultado de ElevenLabs en el flujo como el atributo `$.Lex.SessionAttributes.Tool`. Añade un bloque **Comprobar atributos de contacto** después del bloque de Lex, configura **Espacio de nombres** como **Lex**, **Clave** como **Atributos de sesión** y **Clave de atributo de sesión** como `Tool`; después añade una condición **Es igual a** por resultado y dirige **Sin coincidencia** a un prompt de error: | Rama | Significado | Ruta sugerida | | ---------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `Complete` | El agente terminó la llamada, por ejemplo, con la herramienta **Finalizar llamada**. | Desconectar | | `Escalate` | El agente solicitó una persona (consulta [Transferir a una persona](#transferring-to-a-human)). | Establecer cola de trabajo → Transferir a cola | | Sin coincidencia | Cualquier otro valor. | Reproducir prompt → Desconectar | ![Bloque Comprobar atributos de contacto configurado en el atributo de sesión Tool de Lex con condiciones Es igual a para cada resultado](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connect escribe el resultado con mayúscula inicial (`Escalate`, `Complete`), no como el tipo de > finalización en mayúsculas enviado por cable, por lo que estas dos condiciones son todo lo que necesita el bloque. Una sesión que > falla después de la transferencia termina con el tipo `COMPLETE_WITH_ERROR`; el bloque de Lex toma entonces > su salida **Error** o la comparación llega a **Sin coincidencia**, así que dirige ambas al prompt de error. En un flujo exportado, > la salida **Predeterminada** del bloque de Lex es su transición `NoMatchingCondition`; asegúrate de que lleve al bloque de comparación > en lugar de a un mensaje de error. ![Flujo de contacto con el bloque Obtener información del cliente que lleva a un bloque Comprobar atributos de contacto que dirige Escalate a una cola, Complete a una desconexión y Sin coincidencia a un prompt de error](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### Publica y asigna Publica el flujo y, después, apunta a él un número de teléfono reclamado: ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` Para llamadas salientes, inicia el contacto con el mismo flujo; Amazon Connect llama al cliente y transfiere la llamada contestada 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 ``` ## Prueba la integración #### Haz una llamada Llama al número. El primer mensaje del agente se reproduce unos segundos después de que el flujo llegue al bloque de Lex; la transferencia dentro de AWS tarda unos tres segundos antes de contactar con ElevenLabs. Mantén una conversación breve y despídete: el agente llama a **Finalizar llamada**, la sesión de ElevenLabs termina con `Complete` y tu flujo continúa desde el bloque de Lex. Si añadiste una regla de transferencia, pide hablar con una persona: el agente llama a **Transferir a número**, la sesión termina con `Escalate` y el flujo toma esa rama. #### Comprueba la conversación en ElevenLabs Abre la conversación en **Conversaciones**. Su origen es Amazon Connect y la pestaña **Datos del cliente** lista las variables dinámicas `amazon_connect_*` que recibió la sesión. ![Pestaña Datos del cliente de una conversación de Amazon Connect que muestra las variables dinámicas de Amazon Connect](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### Comprueba el registro del flujo en AWS Con el registro habilitado, cada bloque escribe una entrada en el grupo de registros de flujo de la instancia. El bloque **Obtener información del cliente** registra el resultado que recibió de 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_]*"' ``` Espera `"Results": "Complete"` o `"Results": "Escalate"` después de una transferencia para el bloque de Lex, seguido de los bloques de esa rama. ## Variables dinámicas Amazon Connect envía los atributos del sistema del contacto con cada sesión. ElevenLabs los expone, junto con los identificadores de sesión, como variables dinámicas: | Variable dinámica | Descripción | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `system__caller_id` | El número de teléfono del cliente (endpoint del cliente de Amazon Connect). | | `system__called_number` | El número de teléfono de Amazon Connect en el que está el contacto (endpoint del sistema). | | `system__call_id` | El ID de contacto de Amazon Connect. | | `amazon_connect_system_attributes_channel` | El canal de contacto, por ejemplo, `VOICE`. | | `amazon_connect_system_attributes_customer_endpoint_address` | La dirección del endpoint del cliente tal como la envía Amazon Connect. | | `amazon_connect_system_attributes_system_endpoint_address` | La dirección del endpoint del sistema tal como la envía Amazon Connect. | | `amazon_connect_interaction_mode` | El modo de colaboración, por ejemplo, `HANDOFF`. | | `amazon_connect_contact_id` | El ID de contacto de Amazon Connect. | | `amazon_connect_contact_arn` | El ARN completo del contacto. | | `amazon_connect_context_id` | El ID de sesión (contexto) A2A. | | `amazon_connect_instance_id` | El ID de la instancia. | | `amazon_connect_instance_arn` | El ARN de la instancia. | En las sesiones de Amazon Connect, `system__caller_id` siempre es el cliente y `system__called_number` siempre es el número de Amazon Connect, tanto para contactos entrantes como salientes. Cualquier otro miembro del contexto de contacto que Amazon Connect envía se expone del mismo modo: los nombres anidados se unen con guiones bajos y se convierten a snake case bajo el prefijo `amazon_connect_`. Los atributos de contacto personalizados configurados en tu flujo con **Establecer atributos de contacto** no forman parte del contexto que Amazon Connect envía actualmente, incluso cuando el perfil de seguridad del agente de IA puede 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 transmitir contexto adicional, usa el [webhook de inicio de conversación](/docs/es/eleven-agents/customization/personalization#conversation-initiation-webhooks). En las sesiones de Amazon Connect, el webhook se llama antes de que el agente hable, con `caller_id` configurado como el número del cliente, `called_number` configurado como el número de Amazon Connect y `call_id` configurado como el ID de contacto de Amazon Connect, por lo que una Lambda en tu flujo puede almacenar atributos de contacto indexados por el ID de contacto y el webhook puede devolverlos como variables dinámicas y anulaciones de configuración. ## Transferencia a una persona Proporciona al agente la herramienta del sistema **Transfer to number** con una regla de transferencia `amazon_connect`, como se muestra en [Configurar ElevenLabs](#configure-elevenlabs). Cuando se cumple la condición de la regla, el agente llama a la herramienta y ElevenLabs finaliza la sesión con el resultado `Escalate` y el motivo que ha indicado el agente. A continuación, la rama `Escalate` de tu flujo gestiona el contacto con **Set working queue** y **Transfer to queue**. La regla no incluye ningún destino, por lo que la cola se elige en el flujo, no por el agente; el tratamiento de la cola, los flujos de susurro y la selección de agentes se mantienen en Amazon Connect. La herramienta **End call** genera un resultado `Complete`. El análisis posterior a la llamada y el webhook posterior a la llamada se ejecutan como de costumbre tras cualquiera de los dos resultados. ### Dar un resumen al agente humano Amazon Connect solo expone el resultado a tu flujo: `$.Lex.SessionAttributes.Tool` (y el nombre de la intención de Lex) contienen `Escalate`, y nada más de la sesión de ElevenLabs, incluido el motivo de la transferencia, llega al flujo. Para informar a la persona que atienda la llamada, guarda tú mismo el resumen en el contacto y deja que un flujo de susurro para agentes lo lea: 1. Expón una ruta que llame a la API `UpdateContactAttributes` de Amazon Connect. Basta con una Lambda mínima detrás de una API HTTP; la persona que llama debe tener permiso `connect:UpdateContactAttributes` en los contactos de la instancia: ```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. Proporciona al agente una [herramienta webhook](/docs/es/eleven-agents/customization/tools/webhook-tools) que haga `POST` a esa ruta con `contact_id` completado mediante la variable dinámica `amazon_connect_contact_id` y un `summary` que escriba el modelo. Guarda el secreto compartido en un secreto del espacio de trabajo y envíalo como encabezado de la solicitud. En el prompt del sistema, indica al agente que llame primero a esta herramienta y que llame a **Transfer to number** solo después de que haya devuelto una respuesta; un modelo que emite ambas llamadas en un mismo turno pone en carrera la transferencia con el resumen. Con esa instrucción, en nuestras pruebas el atributo estaba en el contacto aproximadamente un segundo después de la solicitud del agente, tres segundos antes de que Amazon Connect reanudara el flujo. 3. En la rama `Escalate` del flujo de contacto, añade un bloque **Set whisper flow** antes de **Transfer to queue** que apunte a un flujo de susurro para agentes cuyo **Play prompt** lea `$.Attributes.handoff_summary`. Amazon Connect se lo dice al agente humano mientras la persona que llama escucha el tratamiento de la cola y, después, conecta a ambos. No vuelvas a establecer `handoff_summary` en un bloque posterior del flujo: un valor vacío sustituye al que escribió la ruta. El mismo atributo está disponible para un bloque **Check contact attributes** para tomar decisiones de enrutamiento. El webhook posterior a la llamada se activa después de que el flujo ya haya continuado, por lo que resulta adecuado para actualizar el CRM, no para tomar decisiones de enrutamiento. ## Trazas Amazon Connect [requiere que los agentes externos envíen datos de trazas](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html) 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 la persona que llama, la respuesta del agente, cada llamada a herramienta con su resultado y los tiempos de cada span. Amazon Connect almacena estas trazas junto con el contacto; consulta [Trazas de agentes de IA](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html) 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](/docs/es/eleven-agents/workflows/post-call-webhooks), las trazas se envían a tus propios sistemas: los agentes en [modo de retención cero](/docs/es/eleven-agents/customization/privacy/zrm) 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 adopta la propuesta, por lo que los formatos de audio configurados del agente no se usan en las sesiones de Amazon Connect. ElevenLabs detecta la interrupción por voz de la persona que llama y la comunica a Amazon Connect para que la reproducción 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; utiliza el tiempo de espera de turno del agente para volver a solicitar respuesta a una persona que llama que permanece en silencio. ## Limitaciones y funciones no compatibles * Las herramientas de cliente y la herramienta del sistema **Play keypad touch tone** no son compatibles. **Transfer to number** solo funciona mediante una regla de transferencia de Amazon Connect: el agente no puede marcar un número de teléfono ni una URI SIP desde una llamada de Amazon Connect, y el flujo decide qué cola recibe a una persona que llama escalada. * Los resultados de recopilación de datos no se devuelven al flujo, y Amazon Connect decide qué datos del contacto comparte. Usa el webhook de inicio de conversación con la clave `amazon_connect_contact_id` para contexto adicional, una herramienta 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 una transferencia inmediata. El canal de chat de Amazon Connect, el streaming de texto y la colaboración en segundo plano (`delegateAgentConfiguration`) no son compatibles. * Las trazas enviadas a Amazon Connect incluyen la transcripción de la persona que llama, las respuestas del agente, las llamadas a herramientas con sus resultados y los tiempos. Los parámetros de las llamadas a herramientas no se incluyen. * La compatibilidad de Amazon Connect con agentes de terceros solo está disponible donde AWS la haya habilitado y puede conllevar cargos adicionales de AWS. ## Solución de problemas #### El flujo falla con 'A2A WebSocket upgrade ... failed (HTTP 403)' * El error se genera dentro de AWS antes de que ninguna solicitud llegue a ElevenLabs. Consulta CloudTrail para comprobar si hay `AccessDenied` en `wisdom:SendMessage` desde el rol de servicio de Lex: el rol asociado al bot necesita `wisdom:CreateSession`, `wisdom:GetAssistant`, `wisdom:SendMessage` y `wisdom:GetNextMessage` en el asistente y sus sesiones. * Confirma que el perfil de seguridad permite la aplicación y está asociado a la versión publicada del agente de orquestación a la que hace referencia el flujo. * Confirma que la clave KMS y la política de recursos del secreto conceden acceso a `connect.amazonaws.com`. #### El flujo falla con 'the hand-off to the target agent could not be completed' * Amazon Connect da a la conexión WebSocket aproximadamente 20 segundos para establecerse. Confirma que se puede acceder a `AccessUrl` desde AWS: `wss://`, el ID de agente correcto y ninguna lista de permitidos de red que interfiera. * Si enrutas la conexión mediante tu propia infraestructura, mantén ese proxy activo. Una instancia serverless en frío puede tardar más que la ventana de transferencia, y Amazon Connect abandona antes de que ElevenLabs llegue siquiera a recibir la solicitud. #### El bloque de Lex toma su rama Error y la persona que llama no oye nada * Confirma que ambos atributos de sesión están establecidos en el bloque **Get customer input**: `x-amz-lex:q-in-connect:ai-agent-arn` con el ARN del agente publicado y versionado, y `x-amz-lex:qic-audio-passthrough` establecido en `true`. * Confirma que el perfil de seguridad que permite la aplicación está asociado a esa versión del agente. * Consulta la entrada del bloque en el registro del flujo; incluye el error que encontró Amazon Connect. #### La sesión termina inmediatamente después de conectarse * Confirma que `AccessUrl` usa `wss://`, contiene el ID de agente correcto y apunta a la región donde se encuentra tu espacio de trabajo. * Confirma que la clave de API está activa, pertenece al espacio de trabajo del agente y no tiene restricciones de IP. * Confirma que el transporte de Amazon Connect está habilitado para tu espacio de trabajo. #### La persona que llama escucha el mensaje de error del flujo después de que el agente termine En el bloque de Lex, asegúrate de que la salida **Default** lleve al bloque que compara `$.Lex.SessionAttributes.Tool`, y compara con los valores en mayúscula inicial `Escalate` y `Complete`. #### El agente nunca habla y la sesión termina después de unos segundos Confirma que el colaborador está configurado con `audioStreamingEnabled` en true. Con el streaming de texto, Amazon Connect envía turnos de texto y espera respuestas de texto, algo que ElevenLabs no admite; los registros de ElevenLabs muestran `INIT_SESSION carries no audio configuration`. #### Faltan variables dinámicas Amazon Connect proporciona los atributos e identificadores de sistema del contacto indicados anteriormente. Los atributos personalizados del contacto establecidos en el flujo no llegan al agente; pásalos mediante el webhook de inicio de conversación. Si el primer mensaje o el prompt del agente hace referencia a una variable que nunca se proporciona, la sesión falla al iniciarse.