> 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** > > Die Amazon-Connect-Integration ist nur eingeschränkt verfügbar. Die Unterstützung für KI-Drittanbieter-Agenten > von Amazon Connect muss für Ihr AWS-Konto aktiviert sein, und der ElevenLabs-Transport wird pro > Workspace aktiviert. Wenden Sie sich an Ihren ElevenLabs-Ansprechpartner, bevor Sie Kundenverkehr weiterleiten. ## Übersicht Die Amazon-Connect-Integration verbindet einen Amazon-Connect-Kontaktfluss direkt mit einem Agenten in ElevenAgents über das Protokoll für KI-Drittanbieter-Agenten von Amazon Connect, eine Erweiterung des offenen [A2A-Protokolls](https://a2a-protocol.org/). Amazon Connect übernimmt Telefonie, Routing und Warteschlange; ElevenAgents übernimmt das Gespräch. Sie benötigen keinen SIP-Trunk, keine Twilio-Nummer und keine Middleware. AWS dokumentiert die Funktion unter [Agent-to-Agent-Zusammenarbeit](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html); dieser Leitfaden behandelt die ElevenLabs-spezifischen Details und die AWS-Schritte, um einen ElevenLabs-Agenten zu erreichen. Derselbe Ablauf dient eingehenden Anrufen und ausgehenden Kontakten, die mit `StartOutboundVoiceContact` gestartet werden. Wenn der ElevenLabs-Agent fertig ist, setzt Amazon Connect Ihren Kontaktfluss fort und verzweigt anhand des erhaltenen Ergebnisses. ## So funktioniert die Integration 1. Ein Kontaktfluss erreicht einen Block **Kundeneingabe abrufen**, der einen Amazon-Lex-V2-Bot mit dem Intent `AMAZON.QInConnectIntent` aufruft. 2. Der Orchestrierungs-KI-Agent von Amazon Connect übergibt das Gespräch sofort an die Drittanbieter-Anwendung, die Sie für ElevenLabs registriert haben. 3. Amazon Connect öffnet einen WebSocket zum ElevenLabs-Endpunkt in der `AccessUrl` der Anwendung und authentifiziert sich mit dem in AWS Secrets Manager gespeicherten API-Schlüssel. 4. Amazon Connect signalisiert, dass der Kanal des Anrufers aktiv ist. Anschließend tauschen Amazon Connect und ElevenLabs 16-Bit-lineares-PCM-Audio als A2A-Nachrichten aus. Amazon Connect schlägt die Sample-Rate vor und ElevenLabs übernimmt sie, sodass beim Agenten keine Audioformatänderungen nötig sind. 5. Wenn der Agent den Anruf beendet oder den Anrufer an einen Menschen übergibt, beendet ElevenLabs die Sitzung mit dem Ergebnis `Complete` oder `Escalate`, und der Ablauf wird ab dem Lex-Block fortgesetzt; siehe [An einen Menschen übergeben](#transferring-to-a-human). ## Voraussetzungen Stellen Sie vor Beginn Folgendes sicher: 1. Eine Amazon-Connect-Instance im Connect-Customer-Tarif mit aktivierter Unterstützung für KI-Drittanbieter-Agenten für Konto und Region. 2. Einen mit der Instance verknüpften Amazon-Q-in-Connect-Assistenten. 3. AWS-Berechtigungen zum Erstellen von KMS-Schlüsseln, Secrets in Secrets Manager, AppIntegrations-Anwendungen, Connect-Sicherheitsprofilen, Amazon-Q-in-Connect-KI-Agenten, Lex-V2-Bots und Kontaktflüssen. 4. Einen ElevenLabs-Workspace mit aktiviertem Amazon-Connect-Transport. 5. Einen ElevenLabs-Agenten und einen dedizierten API-Schlüssel. 6. AWS CLI v2 und [awscurl](https://github.com/okigan/awscurl) (`pip install awscurl`) für Aufrufe, deren Request-Strukturen noch nicht in veröffentlichten CLI-Versionen enthalten sind. > **Note** > > Halten Sie alle AWS-Ressourcen im selben Konto und derselben Region wie die Amazon-Connect-Instance. Die folgenden Schritte > verwenden die AWS CLI, sofern sie den Aufruf unterstützt, und `awscurl` (eine mit SigV4 signierte HTTP-Anfrage), sofern > nicht. Sie folgen der AWS-Anleitung [Zusammenarbeit mit einem externen KI-Agenten einrichten](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html) und ergänzen die > ElevenLabs-spezifischen Werte. ## ElevenLabs konfigurieren #### Agenten erstellen oder auswählen Erstellen Sie den Agenten in ElevenAgents. Geben Sie ihm eine erste Nachricht, wenn er sprechen soll, sobald die Übergabe abgeschlossen ist; Amazon Connect spielt während der Sitzung selbst nichts ab. #### Anruf beenden aktivieren Aktivieren Sie unter **Agent → Tools → Systemtools** die Option **Anruf beenden**, damit der Agent die Sitzung beenden kann, wenn die Anfrage des Anrufers gelöst ist. Amazon Connect setzt Ihren Ablauf dann mit dem Ergebnis `Complete` fort. #### Amazon-Connect-Weiterleitungsregel hinzufügen (optional) Damit der Agent den Anrufer an einen Menschen übergeben kann, geben Sie ihm das Systemtool **An Nummer weiterleiten** mit einer Weiterleitungsregel, deren Anbieterkonfiguration `amazon_connect` lautet. Die Regel hat kein Ziel: Die Sitzung endet mit dem Ergebnis `Escalate`, und Ihr Kontaktfluss wählt die Warteschlange aus. Weiterleitungsregeln werden über die API konfiguriert. Fügen Sie das Tool mit einem `PATCH` für den Agenten hinzu: ```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"}} ] }] } } }}}} }' ``` Senden Sie das vollständige `built_in_tools`-Objekt des Agenten, einschließlich bereits vorhandener Tools wie `end_call`. Der Agent wählt die Regel anhand ihrer `condition`; die zurückgemeldete Option ist das feste Token `amazon_connect`, sodass eine Amazon-Connect-Regel pro Tool genügt. Telefonnummern und SIP-URIs, die für andere Anbieter konfiguriert sind, werden bei Amazon-Connect-Anrufen nicht angeboten. > **Note** > > Weiterleitungsregeln sind eine API-verwaltete Einstellung. Konfigurieren und aktualisieren Sie das Tool **An Nummer weiterleiten** > eines Agenten, der diese nutzt, wie oben beschrieben über die API; der Tool-Editor im Dashboard arbeitet mit der > Weiterleitungsliste pro Nummer. #### Dedizierten API-Schlüssel erstellen Erstellen Sie einen API-Schlüssel im selben Workspace wie der Agent und beschränken Sie ihn auf ElevenAgents. Sie speichern ihn im nächsten Abschnitt in AWS Secrets Manager; fügen Sie ihn nirgendwo anders ein. #### WebSocket-URL notieren Amazon Connect stellt eine Verbindung zu einer URL her, die Ihre Agenten-ID enthält: | Umgebung | AccessUrl | | ------------- | --------------------------------------------------------------------------------------------------------------------- | | Standard | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Datenresidenz | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > Wenn Ihr ElevenLabs-Konto in einer isolierten Residenzumgebung ist, ersetzen Sie `` durch Ihren > Regionscode. Verfügbare Regionen finden Sie unter [Datenresidenz](/docs/de/overview/administration/data-residency). ## ElevenLabs-Anwendung in AWS registrieren Alles in diesem Abschnitt ist ein API-Aufruf. Legen Sie die Werte, die Sie wiederverwenden, einmal fest: ```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 ``` #### Amazon-Q-in-Connect-Assistenten erstellen Überspringen Sie diesen Schritt, wenn die Instance bereits einen Assistenten hat. Erstellen Sie andernfalls einen und verknüpfen Sie ihn mit der Instance: ```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 ``` Notieren Sie die Assistenten-ID und den ARN. #### API-Schlüssel speichern Amazon Connect liest den Schlüssel mit seinem eigenen Service-Principal aus Secrets Manager. Das Secret muss daher mit einem kundenverwalteten KMS-Schlüssel verschlüsselt werden, der `connect.amazonaws.com` Zugriff zum Entschlüsseln gewährt. Der Standardschlüssel `aws/secretsmanager` kann nicht verwendet werden. **`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": "*" } ] } ``` Speichern Sie den ElevenLabs-API-Schlüssel in einer Datei, damit er nie in Ihrer Shell-Historie erscheint. Erstellen Sie dann den Schlüssel und das Secret: ```bash KMS_KEY_ID=$(aws kms create-key --description "ElevenLabs agent API key" \ --policy file://kms-key-policy.json --region $AWS_REGION \ --query KeyMetadata.KeyId --output text) SECRET_ARN=$(aws secretsmanager create-secret --name elevenlabs/agent-api-key \ --kms-key-id "$KMS_KEY_ID" --secret-string file://elevenlabs-api-key.txt \ --region $AWS_REGION --query ARN --output text) rm elevenlabs-api-key.txt ``` Gewähren Sie Amazon Connect Lesezugriff auf das Secret: **`secret-resource-policy.json`** ```json title="secret-resource-policy.json" { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowConnectRead", "Effect": "Allow", "Principal": { "Service": "connect.amazonaws.com" }, "Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], "Resource": "" } ] } ``` ```bash aws secretsmanager put-resource-policy --secret-id "$SECRET_ARN" \ --resource-policy file://secret-resource-policy.json --region $AWS_REGION ``` ![Mit dem kundenverwalteten Schlüssel verschlüsseltes Secrets-Manager-Secret und seine Ressourcenrichtlinie für connect.amazonaws.com](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### Drittanbieter-Anwendung erstellen Registrieren Sie die ElevenLabs-WebSocket-URL als AppIntegrations-Anwendung vom Typ `A2A_SERVER`. `AuthConfig` ist für diesen Typ erforderlich. **`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" ``` Die Antwort enthält die `Id` und den `Arn` der Anwendung; exportieren Sie sie als `APPLICATION_ID` und `APPLICATION_ARN`. Die Amazon-Connect-Konsole listet `A2A_SERVER`-Anwendungen nicht auf. Prüfen Sie daher über die API: ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### Anwendung mit Ihrer Instance verknüpfen ```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 ``` #### Anwendung in einem Sicherheitsprofil erlauben Das dem Orchestrierungs-KI-Agenten zugewiesene Sicherheitsprofil muss die Anwendung unter den zulässigen KI-Agenten aufführen, andernfalls schlägt die Übergabe zur Laufzeit fehl. ```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" ``` Die Admin-Website zeigt das Profil und seine Berechtigungen, aber nicht die zulässigen KI-Agenten; diese sind nur über die API sichtbar. ![Dediziertes Sicherheitsprofil auf der Amazon-Connect-Admin-Website mit Berechtigungen zum Anzeigen von KI-Agenten ](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### Orchestrierungs-KI-Agenten erstellen und veröffentlichen Der Orchestrierungsagent übergibt jede Sprachunterhaltung sofort an die Anwendung, wobei Audio- Streaming aktiviert ist. Sprachsitzungen erfordern eine sofortige Übergabe; Text-Streaming (`audioStreamingEnabled` auf false gesetzt) und `delegateAgentConfiguration` werden von ElevenLabs nicht unterstützt. Ein Orchestrator mit sofortiger Audioübergabe muss außerdem das reservierte Tool `Complete` vom Typ `RETURN_TO_CONTROL` in `toolConfigurations` deklarieren. Andernfalls schlägt die Erstellungsanfrage fehl mit `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 ``` Die Veröffentlichung gibt einen versionierten ARN zurück (`:1`); der Kontaktfluss referenziert ihn. Weisen Sie das Sicherheitsprofil sowohl dem nicht versionierten als auch dem versionierten Agenten zu: ```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 ``` ![Orchestrierungs-KI-Agent im KI-Agent-Designer mit zugewiesenem dediziertem Sicherheitsprofil ](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## Kontaktfluss erstellen #### Lex-Bot erstellen 1. Erstellen Sie einen Lex-V2-Bot, dessen einziger Intent der integrierte `AMAZON.QInConnectIntent` ist und der mit Ihrem Assistenten-ARN konfiguriert ist. Fügen Sie keine weiteren Intents hinzu. 2. Aktivieren Sie Speech-to-Speech für das Bot-Gebietsschema. Bidirektionales Audio-Streaming funktioniert nur mit Sonic-Speech-to-Speech-Bots. 3. Erlauben Sie der IAM-Rolle des Bots, den Assistenten zu verwenden. Andernfalls schlägt die Übergabe innerhalb von AWS mit `HTTP 403` fehl, bevor eine Anfrage ElevenLabs erreicht. Fügen Sie eine Richtlinie wie diese an: **`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. Erstellen Sie den Bot, erstellen Sie eine Version und einen Alias und verknüpfen Sie den Alias mit der Instance: ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Intent-Liste eines Lex-V2-Bots mit dem Q-in-Connect-Übergabe-Intent und dem integrierten Fallback- Intent](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### Assistenten und Lex-Block hinzufügen Fügen Sie im Ablauf-Designer diese Blöcke in dieser Reihenfolge hinzu: 1. **Protokollierungsverhalten festlegen**: aktiviert. Über das Ablaufprotokoll prüfen Sie die unten beschriebene Übergabe. 2. **Assistent verbinden**: Wählen Sie Ihren Amazon-Q-in-Connect-Assistenten aus. 3. **Kundeneingabe abrufen**: Wählen Sie auf der Registerkarte **Amazon Lex** **ARN eingeben** und fügen Sie den Bot- Alias-ARN ein. Lassen Sie den Text-to-Speech-Prompt als einzelnes Leerzeichen, damit Amazon Connect vor der Übergabe nichts abspielt. Fügen Sie unter **Sitzungsattribute** zwei manuell gesetzte Attribute hinzu: | Zielschlüssel | Wert | | ------------------------------------- | ---------------------------------------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | Der versionierte Orchestrierungsagent-ARN (`...:1`). | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Sitzungsattribute des Blocks „Kundeneingabe abrufen“: der versionierte KI-Agenten-ARN und das Audio- Passthrough-Flag](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` steuert den Sprachpfad für Drittanbieter während der Prelaunch-Phase von AWS. > Laut AWS wird das Attribut nicht mehr benötigt, sobald die Funktion öffentlich verfügbar ist; es kann jedoch problemlos > beibehalten werden. #### Nach Ergebnis verzweigen Amazon Connect stellt das ElevenLabs-Ergebnis dem Ablauf als Attribut `$.Lex.SessionAttributes.Tool` bereit. Fügen Sie nach dem Lex-Block einen Block **Kontaktattribute prüfen** hinzu, setzen Sie **Namespace** auf **Lex**, **Schlüssel** auf **Sitzungsattribute** und **Sitzungsattributschlüssel** auf `Tool`. Fügen Sie dann pro Ergebnis eine Bedingung **Gleich** hinzu und leiten Sie **Keine Übereinstimmung** an einen Fehler-Prompt weiter: | Verzweigung | Bedeutung | Vorgeschlagene Route | | --------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `Complete` | Der Agent hat den Anruf beendet, beispielsweise mit dem Tool **Anruf beenden**. | Trennen | | `Escalate` | Der Agent hat um einen Menschen gebeten (siehe [An einen Menschen übergeben](#transferring-to-a-human)). | Arbeitswarteschlange festlegen → An Warteschlange weiterleiten | | Keine Übereinstimmung | Jeder andere Wert. | Prompt abspielen → Trennen | ![Block „Kontaktattribute prüfen“, konfiguriert für das Lex-Sitzungsattribut Tool mit Gleich- Bedingungen für jedes Ergebnis](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connect schreibt das Ergebnis in Titelschreibweise (`Escalate`, `Complete`), nicht als großgeschriebenen > Abschlusstyp, der über die Verbindung gesendet wird. Daher benötigt der Block nur diese beiden Bedingungen. Eine Sitzung, die > nach der Übergabe fehlschlägt, endet mit dem Typ `COMPLETE_WITH_ERROR`; der Lex-Block nimmt dann seinen > Output **Fehler**, oder der Vergleich fällt auf **Keine Übereinstimmung** zurück. Leiten Sie daher beides an den Fehler- > Prompt weiter. In einem exportierten Ablauf ist der Output **Standard** des Lex-Blocks sein Übergang `NoMatchingCondition`; > stellen Sie sicher, dass er zum Vergleichsblock und nicht zu einer Fehlermeldung führt. ![Kontaktfluss, bei dem der Block „Kundeneingabe abrufen“ zu einem Block „Kontaktattribute prüfen“ führt, der Escalate an eine Warteschlange, Complete an eine Trennung und Keine Übereinstimmung an einen Fehler- Prompt weiterleitet](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### Veröffentlichen und zuweisen Veröffentlichen Sie den Ablauf und verweisen Sie dann eine beanspruchte Telefonnummer darauf: ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` Starten Sie bei ausgehenden Anrufen den Kontakt mit demselben Ablauf; Amazon Connect wählt den Kunden an und übergibt den angenommenen Anruf an ElevenLabs: ```bash aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \ --contact-flow-id --destination-phone-number \ --source-phone-number --region $AWS_REGION ``` ## Integration testen #### Anruf tätigen Rufen Sie die Nummer an. Die erste Nachricht des Agenten wird einige Sekunden abgespielt, nachdem der Ablauf den Lex- Block erreicht hat; die Übergabe innerhalb von AWS dauert etwa drei Sekunden, bevor ElevenLabs kontaktiert wird. Führen Sie ein kurzes Gespräch und verabschieden Sie sich: Der Agent ruft **Anruf beenden** auf, die ElevenLabs-Sitzung endet mit `Complete`, und Ihr Ablauf wird ab dem Lex-Block fortgesetzt. Wenn Sie eine Weiterleitungsregel hinzugefügt haben, bitten Sie stattdessen um einen Menschen: Der Agent ruft **An Nummer weiterleiten** auf, die Sitzung endet mit `Escalate`, und der Ablauf nimmt diese Verzweigung. #### Unterhaltung in ElevenLabs prüfen Öffnen Sie die Unterhaltung unter **Unterhaltungen**. Ihre Quelle ist Amazon Connect, und auf der Registerkarte **Client-Daten** stehen die dynamischen Variablen `amazon_connect_*`, die die Sitzung erhalten hat. ![Registerkarte „Client-Daten“ einer Amazon-Connect-Unterhaltung mit den dynamischen Amazon-Connect- Variablen](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### Ablaufprotokoll in AWS prüfen Bei aktivierter Protokollierung schreibt jeder Block einen Eintrag in die Ablaufprotokollgruppe der Instance. Der Block **Kundeneingabe abrufen** erfasst das von ElevenLabs erhaltene Ergebnis: ```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_]*"' ``` Erwarten Sie für den Lex-Block `"Results": "Complete"` oder nach einer Weiterleitung `"Results": "Escalate"`, gefolgt von den Blöcken dieser Verzweigung. ## Dynamische Variablen Amazon Connect sendet die Systemattribute des Kontakts mit jeder Sitzung. ElevenLabs stellt sie zusammen mit den Sitzungskennungen als dynamische Variablen bereit: | Dynamische Variable | Beschreibung | | ------------------------------------------------------------ | ----------------------------------------------------------------- | | `system__caller_id` | Die Telefonnummer des Kunden (Kundenendpunkt von Amazon Connect). | | `system__called_number` | Die Amazon-Connect-Telefonnummer des Kontakts (Systemendpunkt). | | `system__call_id` | Die Amazon-Connect-Kontakt-ID. | | `amazon_connect_system_attributes_channel` | Der Kontaktkanal, beispielsweise `VOICE`. | | `amazon_connect_system_attributes_customer_endpoint_address` | Die vom Amazon Connect gesendete Kundenendpunktadresse. | | `amazon_connect_system_attributes_system_endpoint_address` | Die von Amazon Connect gesendete Systemendpunktadresse. | | `amazon_connect_interaction_mode` | Der Zusammenarbeitsmodus, beispielsweise `HANDOFF`. | | `amazon_connect_contact_id` | Die Amazon-Connect-Kontakt-ID. | | `amazon_connect_contact_arn` | Der vollständige Kontakt-ARN. | | `amazon_connect_context_id` | Die A2A-Sitzungs-ID (Kontext-ID). | | `amazon_connect_instance_id` | Die Instance-ID. | | `amazon_connect_instance_arn` | Der Instance-ARN. | In Amazon-Connect-Sitzungen ist `system__caller_id` immer der Kunde und `system__called_number` immer die Amazon-Connect-Nummer, sowohl bei eingehenden als auch bei ausgehenden Kontakten. Jedes weitere Mitglied des Kontaktkontexts, das Amazon Connect sendet, wird auf dieselbe Weise bereitgestellt: Verschachtelte Namen werden mit Unterstrichen verbunden und im Snake Case unter dem Präfix `amazon_connect_` konvertiert. Benutzerdefinierte Kontaktattribute, die Sie in Ihrem Ablauf mit **Kontaktattribute festlegen** setzen, sind nicht Teil des Kontexts, den Amazon Connect derzeit sendet – auch dann nicht, wenn das Sicherheitsprofil des KI-Agenten Kontaktattribute anzeigen kann. Falls AWS sie künftig einschließt, erscheinen sie automatisch unter demselben Präfix. Sie können nicht auswählen, welche Kontaktdaten Amazon Connect teilt; AWS übergibt einen festen Kontextsatz. Um zusätzlichen Kontext zu übergeben, verwenden Sie den [Webhook zur Gesprächsinitiierung](/docs/de/eleven-agents/customization/personalization#conversation-initiation-webhooks). Bei Amazon-Connect-Sitzungen wird der Webhook aufgerufen, bevor der Agent spricht, wobei `caller_id` auf die Telefonnummer des Kunden, `called_number` auf die Amazon-Connect-Nummer und `call_id` auf die Amazon-Connect-Kontakt-ID gesetzt wird. Eine Lambda-Funktion in Ihrem Ablauf kann daher Kontaktattribute nach Kontakt-ID speichern, und der Webhook kann sie als dynamische Variablen und Konfigurationsüberschreibungen zurückgeben. ## An einen menschlichen Agenten weiterleiten Geben Sie dem Agenten das Systemtool **Transfer to number** mit einer `amazon_connect`-Weiterleitungsregel, wie unter [ElevenLabs konfigurieren](#configure-elevenlabs) gezeigt. Wenn die Bedingung der Regel erfüllt ist, ruft der Agent das Tool auf und ElevenLabs beendet die Sitzung mit dem Ergebnis `Escalate` und dem vom Agenten angegebenen Grund. Der `Escalate`-Zweig Ihres Flows bearbeitet den Kontakt dann mit **Set working queue** und **Transfer to queue**. Die Regel enthält kein Ziel. Daher wird die Warteschlange im Flow ausgewählt, nicht vom Agenten. Warteschlangenbehandlung, Whisper-Flows und Agentenauswahl bleiben in Amazon Connect. Das Tool **End call** erzeugt das Ergebnis `Complete`. Die Nachbearbeitung und der Post-Call-Webhook werden nach beiden Ergebnissen wie gewohnt ausgeführt. ### Dem menschlichen Agenten eine Zusammenfassung geben Amazon Connect stellt Ihrem Flow nur das Ergebnis bereit: `$.Lex.SessionAttributes.Tool` (und der Lex- Intent-Name) enthalten `Escalate`. Keine weiteren Daten aus der ElevenLabs-Sitzung, auch nicht der Grund für die Weiterleitung, erreichen den Flow. Um den menschlichen Agenten zu informieren, der den Anruf übernimmt, speichern Sie die Zusammenfassung selbst beim Kontakt und lassen Sie sie von einem Agent-Whisper-Flow vorlesen: 1. Stellen Sie einen Endpunkt bereit, der die `UpdateContactAttributes`-API von Amazon Connect aufruft. Eine minimale Lambda hinter einer HTTP-API genügt. Der Aufrufer muss für die Kontakte der Instanz die Berechtigung `connect:UpdateContactAttributes` haben: ```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. Geben Sie dem Agenten ein [Webhook-Tool](/docs/de/eleven-agents/customization/tools/webhook-tools), das per `POST` an diesen Endpunkt sendet. Füllen Sie `contact_id` mit der dynamischen Variable `amazon_connect_contact_id` und `summary` mit einer vom Modell erstellten Zusammenfassung. Speichern Sie das gemeinsame Secret als Workspace-Secret und senden Sie es in einem Request-Header. Weisen Sie den Agenten im System-Prompt an, dieses Tool zuerst aufzurufen und **Transfer to number** erst nach dessen Rückgabe aufzurufen. Ein Modell, das beide Aufrufe in einem Turn ausführt, lässt die Weiterleitung mit der Zusammenfassung konkurrieren. Mit dieser Anweisung befand sich das Attribut in unseren Tests etwa eine Sekunde nach der Anfrage des Agenten auf dem Kontakt, drei Sekunden bevor Amazon Connect den Flow fortsetzte. 3. Fügen Sie im `Escalate`-Zweig des Kontakt-Flows vor **Transfer to queue** einen Block **Set whisper flow** hinzu, der auf einen Agent-Whisper-Flow verweist, dessen **Play prompt** `$.Attributes.handoff_summary` vorliest. Amazon Connect gibt dies dem menschlichen Agenten wieder, während der Anrufer die Warteschlangenbehandlung hört, und verbindet anschließend beide. Setzen Sie `handoff_summary` nicht erneut in einem späteren Block des Flows: Ein leerer Wert dort ersetzt den vom Endpunkt geschriebenen Wert. Dasselbe Attribut ist für einen Block **Check contact attributes** für Routing-Entscheidungen verfügbar. Der Post-Call-Webhook wird ausgelöst, nachdem der Flow bereits fortgesetzt wurde. Er eignet sich daher für CRM- Updates statt für Routing-Entscheidungen. ## Traces Amazon Connect [fordert externe Agenten auf, Trace-Daten zu senden](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html) für jede Zusammenarbeit. Wenn Amazon Connect das Tracing für die Sitzung abonniert, sendet ElevenLabs einen OpenTelemetry-Trace für jeden Agent-Turn. Er enthält das Transkript des Anrufers, die Antwort des Agenten, jeden Tool-Aufruf mit seinem Ergebnis sowie das Timing pro Span. Amazon Connect speichert diese Traces mit dem Kontakt. Informationen zum Anzeigen finden Sie unter [KI-Agent-Traces](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html). Transkripte und Tool-Ergebnisse in diesen Traces unterliegen denselben Einstellungen zur Schwärzung wie Ihre übrigen Kontaktdaten in Amazon Connect. Prüfen Sie daher Ihre Anforderungen an die Datenverarbeitung, bevor Sie die Integration aktivieren. Wie [Post-Call-Webhooks](/docs/de/eleven-agents/workflows/post-call-webhooks) werden Traces an Ihre eigenen Systeme gesendet: Agenten im [Zero-Retention-Modus](/docs/de/eleven-agents/customization/privacy/zrm) senden sie weiterhin, da Zero Retention regelt, was ElevenLabs speichert, nicht was Ihre Amazon-Connect-Instanz empfängt. ## Audio Amazon Connect schlägt für jede Sitzung 16-Bit-Mono-Linear-PCM mit 8, 16 oder 24 kHz vor, und ElevenLabs übernimmt den Vorschlag. Die konfigurierten Audioformate des Agenten werden daher nicht für Amazon-Connect- Sitzungen verwendet. Unterbrechungen durch den Anrufer werden von ElevenLabs erkannt und an Amazon Connect gemeldet, sodass gepufferte Wiedergabe sofort verworfen wird. Von Amazon Connect erfasste Tastatureingaben werden als DTMF-Ziffern an den Agenten übermittelt. Die eigene Stillemarkierung von Amazon Connect wird ignoriert. Verwenden Sie das Turn-Timeout des Agenten, um einen stillen Anrufer erneut anzusprechen. ## Einschränkungen und nicht unterstützte Funktionen * Client-Tools und das Systemtool **Play keypad touch tone** werden nicht unterstützt. **Transfer to number** funktioniert nur über eine Amazon-Connect-Weiterleitungsregel: Der Agent kann aus einem Amazon- Connect-Anruf weder eine Telefonnummer noch eine SIP-URI wählen, und der Flow entscheidet, welche Warteschlange einen eskalierten Anrufer erhält. * Ergebnisse der Datenerfassung werden nicht an den Flow zurückgegeben. Amazon Connect entscheidet, welche Kontaktdaten geteilt werden. Verwenden Sie für zusätzlichen Kontext den Conversation-Initiation-Webhook mit `amazon_connect_contact_id`, für Routing-Daten ein Webhook-Tool, das `UpdateContactAttributes` aufruft, und für alles andere den Post-Call-Webhook. * Konfigurationsüberschreibungen wie `system__override_first_message` können nicht vom Flow übergeben werden. Geben Sie sie stattdessen über den Conversation-Initiation-Webhook zurück. * Voice-Sitzungen erfordern eine sofortige Übergabe. Der Amazon-Connect-Chat-Kanal, Text-Streaming und die Zusammenarbeit im Hintergrund (`delegateAgentConfiguration`) werden nicht unterstützt. * An Amazon Connect gesendete Traces umfassen das Transkript des Anrufers, die Antworten des Agenten, Tool-Aufrufe mit ihren Ergebnissen und Timing-Daten. Tool-Aufrufparameter sind nicht enthalten. * Die Unterstützung von Drittanbieter-Agenten in Amazon Connect ist nur dort verfügbar, wo AWS sie aktiviert hat, und kann zusätzliche AWS-Gebühren verursachen. ## Fehlerbehebung #### Der Flow schlägt mit ‚A2A WebSocket upgrade ... failed (HTTP 403)‘ fehl * Der Fehler wird innerhalb von AWS ausgelöst, bevor eine Anfrage ElevenLabs erreicht. Prüfen Sie CloudTrail auf `AccessDenied` für `wisdom:SendMessage` von der Lex-Service-Rolle: Die an den Bot angehängte Rolle benötigt `wisdom:CreateSession`, `wisdom:GetAssistant`, `wisdom:SendMessage` und `wisdom:GetNextMessage` für den Assistenten und seine Sitzungen. * Bestätigen Sie, dass das Sicherheitsprofil die Anwendung zulässt und der vom Flow referenzierten veröffentlichten Orchestration-Agent-Version zugeordnet ist. * Bestätigen Sie, dass der KMS-Schlüssel und die Ressourcenrichtlinie des Secrets `connect.amazonaws.com` Zugriff gewähren. #### Der Flow schlägt mit ‚the hand-off to the target agent could not be completed‘ fehl * Amazon Connect gibt der WebSocket-Verbindung ungefähr 20 Sekunden Zeit zum Aufbau. Bestätigen Sie, dass die `AccessUrl` von AWS erreichbar ist: `wss://`, die richtige Agent-ID und keine Netzwerk-Allowlist, die im Weg ist. * Wenn Sie die Verbindung über Ihre eigene Infrastruktur proxyen, halten Sie diesen Proxy warm. Eine kalte serverlose Instanz kann länger als das Übergabefenster benötigen. Amazon Connect gibt dann auf, bevor ElevenLabs die Anfrage überhaupt sieht. #### Der Lex-Block nimmt seinen Error-Zweig und der Anrufer hört nichts * Bestätigen Sie, dass beide Sitzungsattribute im Block **Get customer input** gesetzt sind: `x-amz-lex:q-in-connect:ai-agent-arn` mit der veröffentlichten, versionierten Agent-ARN und `x-amz-lex:qic-audio-passthrough` auf `true`. * Bestätigen Sie, dass das Sicherheitsprofil, das die Anwendung zulässt, dieser Agent-Version zugeordnet ist. * Lesen Sie den Eintrag des Blocks im Flow-Log. Er enthält den Fehler, auf den Amazon Connect gestoßen ist. #### Die Sitzung endet unmittelbar nach dem Verbinden * Bestätigen Sie, dass die `AccessUrl` `wss://` verwendet, die richtige Agent-ID enthält und auf die Region verweist, in der sich Ihr Workspace befindet. * Bestätigen Sie, dass der API-Key aktiv ist, zum Workspace des Agenten gehört und keine IP-Einschränkungen hat. * Bestätigen Sie, dass der Amazon-Connect-Transport für Ihren Workspace aktiviert ist. #### Der Anrufer hört die Fehleransage des Flows, nachdem der Agent fertig ist Stellen Sie im Lex-Block sicher, dass der Output **Default** zum Block führt, der `$.Lex.SessionAttributes.Tool` vergleicht, und vergleichen Sie mit den Werten in Titelschreibweise `Escalate` und `Complete`. #### Der Agent spricht nie und die Sitzung endet nach einigen Sekunden Bestätigen Sie, dass der Collaborator mit auf true gesetztem `audioStreamingEnabled` konfiguriert ist. Bei Text- Streaming sendet Amazon Connect Text-Turns und erwartet Textantworten, was ElevenLabs nicht unterstützt. Die ElevenLabs-Logs zeigen `INIT_SESSION carries no audio configuration`. #### Dynamische Variablen fehlen Amazon Connect stellt die oben aufgeführten Kontakt-Systemattribute und Kennungen bereit. Im Flow gesetzte benutzerdefinierte Kontaktattribute erreichen den Agenten nicht. Übergeben Sie sie stattdessen über den Conversation-Initiation-Webhook. Wenn die erste Nachricht oder der Prompt des Agenten auf eine Variable verweist, die nie bereitgestellt wird, schlägt die Sitzung beim Start fehl.