Amazon Connect

概要

Amazon Connectインテグレーションでは、Amazon Connectのコンタクトフローを、オープンな A2Aプロトコルを拡張したAmazon ConnectのサードパーティAIエージェントプロトコルを介して、 ElevenAgentsのエージェントに直接接続します。Amazon Connectがテレフォニー、ルーティング、キューを管理し、 ElevenAgentsが会話を管理します。SIPトランク、Twilio番号、ミドルウェアは不要です。AWSではこの機能を エージェント間コラボレーションとして文書化しています。 このガイドでは、ElevenLabs固有の内容と、ElevenLabsエージェントに接続するために必要なAWSの手順を説明します。

同じフローで、StartOutboundVoiceContactを使用して開始される着信通話と発信コンタクトに対応します。 ElevenLabsエージェントが終了すると、Amazon Connectはコンタクトフローを継続し、受信した 結果に基づいて分岐します。

インテグレーションの仕組み

1. コンタクトフローが、AMAZON.QInConnectIntentインテントを使用するAmazon Lex V2ボットを呼び出すGet customer inputブロックに到達します。
2. Amazon ConnectのオーケストレーションAIエージェントが、会話を直ちにElevenLabs用に登録したサードパーティアプリケーションへ引き継ぎます。
3. Amazon Connectが、AWS Secrets Managerに保存されたAPIキーで認証し、アプリケーションのAccessUrlにあるElevenLabsエンドポイントへのWebSocketを開きます。
4. Amazon Connectが発信者のチャネルが接続中であることを通知すると、Amazon ConnectとElevenLabsがA2Aメッセージとして16ビットリニアPCMオーディオを交換します。Amazon Connectがサンプルレートを提示し、ElevenLabsがそれを採用するため、エージェント側でオーディオ形式を変更する必要はありません。
5. エージェントが通話を終了すると、ElevenLabsはComplete結果でセッションを完了し、フローはLexブロックから続行されます。発信者を有人キューへルーティングするEscalate結果は通信上サポートされており、転送ツールで公開される予定です。詳しくは有人対応への転送をご覧ください。

要件

始める前に、以下を用意してください。

1. アカウントとリージョンでサードパーティAIエージェントのサポートが有効になっている、Connect CustomerティアのAmazon Connectインスタンス。
2. インスタンスに関連付けられたAmazon Q in Connectアシスタント。
3. KMSキー、Secrets Managerシークレット、AppIntegrationsアプリケーション、Connectセキュリティプロファイル、Amazon Q in Connect AIエージェント、Lex V2ボット、コンタクトフローを作成するためのAWS権限。
4. Amazon Connectトランスポートが有効なElevenLabsワークスペース。
5. ElevenLabsエージェントと専用APIキー。
6. AWS CLI v2と、リリース済みのCLIバージョンにリクエスト形式がまだ含まれていない呼び出し用のawscurl（pip install awscurl）。

ElevenLabsを設定する

AWSにElevenLabsアプリケーションを登録する

このセクションの操作はすべてAPI呼び出しです。再利用する値を一度設定します。

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

コンタクトフローを構築する

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

インテグレーションをテストする

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

動的変数

Amazon Connectは、すべてのセッションでコンタクトのシステム属性を送信します。ElevenLabsでは、 これらをセッション識別子とともに動的変数として公開します：

Amazon Connectセッションでは、受信・発信コンタクトのどちらでも、system__caller_idは常に顧客、system__called_number は常にAmazon Connectの番号です。

Amazon Connectが送信するコンタクトコンテキストのその他すべてのメンバーも同様に公開されます。ネストされた 名前はアンダースコアで結合され、amazon_connect_プレフィックスの下でスネークケースに変換されます。 フロー内でSet contact attributesを使って設定したカスタムコンタクト属性は、AIエージェントのセキュリティプロファイルでコンタクト 属性を表示できる場合でも、Amazon Connectが現在送信するコンテキストには含まれません。AWSがこれらを含めるようになった場合は、同じプレフィックスの下に自動的に表示されます。Amazon Connectが共有するコンタクトデータを選択することはできません。AWSは固定のコンテキストセットを渡します。

追加のコンテキストを渡すには、 会話開始Webhookを使用してください。 Amazon Connectセッションでは、エージェントが話し始める前にWebhookが呼び出され、caller_idには顧客の番号、 called_numberにはAmazon Connectの番号、call_idにはAmazon ConnectコンタクトIDが設定されます。そのため、フロー内のLambdaでコンタクトIDをキーにコンタクト属性を保存し、Webhookから動的変数と設定オーバーライドとして返せます。

担当者への転送

ElevenLabsセッションがEscalate結果で終了すると、Amazon Connectはコンタクトを担当者キューにルーティングします。フローのEscalateブランチでは、Set working queueとTransfer to queueでこれを処理します。キュー処理、ウィスパーフロー、エージェント選択はすべてAmazon Connectが処理します。

End callツールはComplete結果を生成します。どちらの結果の後も、通話後分析と通話後Webhookは通常どおり実行されます。

Amazon Connectに戻されるのは、結果タイプと理由文字列のみです。ルーティングデータをフローに渡すには、amazon_connect_contact_idと保存する値を使用してAmazon ConnectのUpdateContactAttributes APIを呼び出すWebhookツールをエージェントに付与し、通話を終了する前に呼び出すよう指示してください。フローでは、Lexブロックの後にあるCheck contact attributesブロックでこれらの属性を読み取れます。通話後Webhookはフローがすでに続行された後に発火するため、ルーティングの判断ではなくCRMの更新に適しています。

トレース

Amazon Connectでは、すべてのコラボレーションについて外部エージェントによるトレースデータの送信が必要です。 Amazon Connectがセッションのトレーシングをサブスクライブすると、ElevenLabsはエージェントの各ターンについて、発信者の文字起こし、エージェントの応答、結果を含む各ツール呼び出し、スパンごとのタイミングを含むOpenTelemetryトレースを送信します。Amazon Connectはこれらのトレースをコンタクトとともに保存します。表示方法については、 AIエージェントトレースを参照してください。これらのトレース内の文字起こしとツール結果には、Amazon Connect内の他のコンタクトデータと同じ秘匿化設定が適用されるため、インテグレーションを有効にする前にデータ取り扱い要件を確認してください。通話後Webhookと同様に、トレースは独自のシステムに配信されます。ゼロ保持モードのエージェントもトレースを送信します。ゼロ保持はElevenLabsが保存するデータに適用され、Amazon Connectインスタンスが受信するデータには適用されないためです。

オーディオ

Amazon Connectは各セッションで8、16、または24kHzの16ビット・モノラル・リニアPCMを提案し、ElevenLabsはその提案を採用します。そのため、Amazon Connectセッションではエージェントに設定されたオーディオ形式は使用されません。発信者による割り込みはElevenLabsが検出し、Amazon Connectに報告するため、バッファリングされた再生は即座にフラッシュされます。Amazon Connectが収集したキーパッド入力は、DTMF数字としてエージェントに配信されます。Amazon Connect独自の無音マーカーは無視されます。無言の発信者に再度プロンプトを出すには、エージェントのターンタイムアウトを使用してください。

制限事項と未対応の機能

• クライアントツールとPlay keypad touch toneシステムツールはサポートされていません。Transfer to numberはまだAmazon Connectをサポートしていません。担当者への引き継ぎは、このツールのAmazon Connect転送タイプとして提供されます。
• データ収集結果はフローに返されず、Amazon Connectが共有するコンタクトデータを決定します。追加のコンテキストにはamazon_connect_contact_idをキーにした会話開始Webhookを、ルーティングデータにはUpdateContactAttributesを呼び出すWebhookツールを、それ以外には通話後Webhookを使用してください。
• system__override_first_messageなどの設定オーバーライドはフローから渡せません。代わりに会話開始Webhookから返してください。
• 音声セッションでは即時の引き継ぎが必要です。Amazon Connectチャットチャネル、テキストストリーミング、バックグラウンド（delegateAgentConfiguration）コラボレーションはまだサポートされていません。
• Amazon Connectに送信されるトレースには、発信者の文字起こし、エージェントの応答、結果を含むツール呼び出し、タイミングが含まれます。ツール呼び出しパラメータは含まれません。
• Amazon Connectのサードパーティエージェントサポートは、AWSが有効化している場所でのみ利用でき、AWSから追加料金が発生する場合があります。

トラブルシューティング