Amazon Connect

Überblick

Die Amazon-Connect-Integration verbindet einen Amazon-Connect-Kontaktfluss direkt mit einem Agenten in ElevenAgents über das Protokoll für KI-Agenten von Drittanbietern von Amazon Connect, eine Erweiterung des offenen A2A-Protokolls. Amazon Connect übernimmt Telefonie, Routing und die Warteschlange; ElevenAgents übernimmt die Unterhaltung. Es sind kein SIP-Trunk, keine Twilio-Nummer und keine Middleware erforderlich. AWS dokumentiert die Funktion unter Agent-to-Agent-Zusammenarbeit; dieser Leitfaden behandelt die ElevenLabs-spezifischen Aspekte und die AWS-Schritte, die erforderlich sind, um einen ElevenLabs-Agenten zu erreichen.

Derselbe Ablauf dient für eingehende Anrufe und ausgehende Kontakte, die mit StartOutboundVoiceContact gestartet werden. Wenn der ElevenLabs-Agent fertig ist, setzt Amazon Connect Ihren Kontaktfluss fort und verzweigt anhand des empfangenen 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 die Unterhaltung sofort an die Drittanbieteranwendung, 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 Abtastrate vor und ElevenLabs übernimmt sie, daher sind für den Agenten keine Änderungen am Audioformat erforderlich.
5. Wenn der Agent den Anruf beendet, schließt ElevenLabs die Sitzung mit dem Ergebnis Complete ab und der Fluss wird ab dem Lex-Block fortgesetzt. Das Ergebnis Escalate, das den Anrufer an eine menschliche Warteschlange weiterleitet, wird über das Protokoll unterstützt und über das Übergabetool verfügbar sein; siehe An einen Menschen übergeben.

Voraussetzungen

Stellen Sie vor Beginn sicher, dass Sie über Folgendes verfügen:

1. Eine Amazon Connect-Instance im Tarif Connect Customer mit aktivierter Unterstützung für Drittanbieter-KI-Agenten für das Konto und die Region.
2. Einen Amazon Q in Connect-Assistenten, der mit der Instance verknüpft ist.
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 (pip install awscurl) für Aufrufe, deren Anfrageschemas noch nicht in veröffentlichten CLI-Versionen enthalten sind.

ElevenLabs konfigurieren

ElevenLabs-Anwendung in AWS registrieren

Alles in diesem Abschnitt ist ein API-Aufruf. Legen Sie die Werte, die Sie wiederverwenden, einmalig fest:

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

Kontaktfluss erstellen

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

Integration testen

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

Dynamische Variablen

Amazon Connect sendet die Systemattribute des Kontakts mit jeder Sitzung. ElevenLabs stellt sie zusammen mit den Sitzungskennungen als dynamische Variablen bereit:

In Amazon-Connect-Sitzungen ist system__caller_id immer der Kunde und system__called_number immer die Amazon-Connect-Nummer – sowohl für eingehende als auch für ausgehende Kontakte.

Jedes weitere Element des von Amazon Connect gesendeten Kontaktkontexts wird auf dieselbe Weise bereitgestellt: Verschachtelte Namen werden mit Unterstrichen verbunden und im Snake Case unter dem Präfix amazon_connect_ ausgegeben. Benutzerdefinierte Kontaktattribute, die Sie in Ihrem Flow 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 Kontextsaz.

Um zusätzlichen Kontext zu übergeben, verwenden Sie den Webhook zur Gesprächsinitiierung. Für Amazon-Connect-Sitzungen wird der Webhook aufgerufen, bevor der Agent spricht. Dabei ist caller_id auf die Nummer des Kunden, called_number auf die Amazon-Connect-Nummer und call_id auf die Amazon-Connect-Kontakt-ID gesetzt. So kann eine Lambda-Funktion in Ihrem Flow Kontaktattribute nach Kontakt-ID speichern und der Webhook sie als dynamische Variablen und Konfigurationsüberschreibungen zurückgeben.

An einen Menschen weiterleiten

Amazon Connect leitet einen Kontakt an eine menschliche Warteschlange weiter, wenn die ElevenLabs-Sitzung mit dem Ergebnis Escalate endet. Den Zweig Escalate Ihres Flows verarbeiten Sie mit Arbeitswarteschlange festlegen und **An Warteschlange weiterleiten **. Jede Warteschlangenbehandlung, Whisper-Flow oder Agentenauswahl übernimmt Amazon Connect.

Das Tool Anruf beenden erzeugt das Ergebnis Complete. Die Analyse nach dem Anruf und der Webhook nach dem Anruf werden nach beiden Ergebnissen wie gewohnt ausgeführt.

Nur der Ergebnistyp und eine Zeichenfolge mit dem Grund werden an Amazon Connect zurückgegeben. Um Routingdaten an den Flow zu übergeben, geben Sie dem Agenten ein Webhook-Tool, das die UpdateContactAttributes-API von Amazon Connect mit amazon_connect_contact_id und den zu speichernden Werten aufruft. Weisen Sie den Agenten an, es vor dem Beenden des Anrufs aufzurufen. Der Flow kann diese Attribute dann nach dem Lex-Block mit einem Kontaktattribute prüfen-Block lesen. Der Webhook nach dem Anruf wird ausgelöst, nachdem der Flow bereits fortgesetzt wurde. Er eignet sich daher für CRM-Aktualisierungen statt für Routingentscheidungen.

Traces

Amazon Connect verlangt von externen Agenten das Senden von Trace-Daten für jede Kollaboration. Wenn Amazon Connect Trace-Daten für die Sitzung abonniert, sendet ElevenLabs für jeden Agententurn einen OpenTelemetry-Trace mit dem Transkript des Anrufers, der Antwort des Agenten, jedem Tool-Aufruf mit Ergebnis und dem Timing pro Span. Amazon Connect speichert diese Traces mit dem Kontakt. Informationen zum Anzeigen finden Sie unter KI-Agenten-Traces. Transkripte und Tool-Ergebnisse in diesen Traces unterliegen denselben Schwärzungseinstellungen wie Ihre übrigen Kontaktdaten in Amazon Connect. Prüfen Sie daher Ihre Anforderungen zur Datenverarbeitung, bevor Sie die Integration aktivieren. Wie Webhooks nach dem Anruf werden Traces an Ihre eigenen Systeme übermittelt: Agenten im Zero-Retention-Modus senden sie weiterhin, da Zero Retention regelt, was ElevenLabs speichert, nicht was Ihre Amazon-Connect-Instanz empfängt.

Audio

Amazon Connect schlägt in jeder Sitzung lineares 16-Bit-Mono-PCM mit 8, 16 oder 24 kHz vor. ElevenLabs übernimmt den Vorschlag, daher werden die konfigurierten Audioformate des Agenten für Amazon-Connect-Sitzungen nicht verwendet. Unterbrechungen durch Anrufer erkennt ElevenLabs und meldet sie an Amazon Connect, damit gepufferte Wiedergabe sofort geleert wird. Von Amazon Connect erfasste Tastatureingaben werden als DTMF-Ziffern an den Agenten übermittelt. Der eigene Stillemarker 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 Tastenton wiedergeben werden nicht unterstützt. An Nummer weiterleiten unterstützt Amazon Connect noch nicht; die Übergabe an einen Menschen wird in diesem Tool als Amazon-Connect-Übertragungstyp verfügbar sein.
• Ergebnisse der Datenerfassung werden nicht an den Flow zurückgegeben und Amazon Connect entscheidet, welche Kontaktdaten es teilt. Verwenden Sie für zusätzlichen Kontext den nach amazon_connect_contact_id geschlüsselten Webhook zur Gesprächsinitiierung, für Routingdaten ein Webhook-Tool, das UpdateContactAttributes aufruft, und für alles andere den Webhook nach dem Anruf.
• Konfigurationsüberschreibungen wie system__override_first_message können nicht vom Flow übergeben werden. Geben Sie sie stattdessen über den Webhook zur Gesprächsinitiierung zurück.
• Sprachsitzungen erfordern eine sofortige Übergabe. Der Amazon-Connect-Chatkanal, Text-Streaming und Kollaboration im Hintergrund (delegateAgentConfiguration) werden noch nicht unterstützt.
• An Amazon Connect gesendete Traces umfassen das Transkript des Anrufers, Antworten des Agenten, Tool-Aufrufe mit ihren Ergebnissen und Timing. Tool-Aufrufparameter sind nicht enthalten.
• Die Unterstützung von Drittanbieter-Agenten in Amazon Connect ist nur verfügbar, wenn AWS sie aktiviert hat, und kann zusätzliche AWS-Gebühren verursachen.

Fehlerbehebung