> 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** > > Amazon Connectインテグレーションは限定提供中です。AWSアカウントでAmazon ConnectのサードパーティAIエージェント > サポートを有効にし、ワークスペースごとにElevenLabsトランスポートを有効化する必要があります。顧客トラフィックを > ルーティングする前に、ElevenLabsの担当者にお問い合わせください。 ## 概要 Amazon Connectインテグレーションでは、オープンな [A2Aプロトコル](https://a2a-protocol.org/)の拡張であるAmazon ConnectのサードパーティAIエージェントプロトコルを介して、Amazon Connectのコンタクトフローを ElevenAgentsのエージェントに直接接続します。電話、ルーティング、キューはAmazon Connectが管理し、 会話はElevenAgentsが管理します。SIPトランク、Twilio番号、ミドルウェアは不要です。AWSではこの機能を [エージェント間コラボレーション](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html)として文書化しています。 このガイドでは、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`または`Escalate`の結果で セッションを終了し、Lexブロックからフローが続行されます。詳細は [担当者への転送](#transferring-to-a-human)をご覧ください。 ## 要件 開始する前に、以下を用意してください。 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](https://github.com/okigan/awscurl)（`pip install awscurl`）。 > **Note** > > すべてのAWSリソースは、Amazon Connectインスタンスと同じアカウントおよびリージョンに配置してください。以下の手順では、 > 呼び出しをサポートする場合はAWS CLIを、サポートしない場合は`awscurl`（SigV4署名付きHTTPリクエスト）を使用します。 > AWSの[外部AIエージェントとのコラボレーションを設定する](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html)手順に従い、 > ElevenLabs固有の値を追加しています。 ## ElevenLabsを設定する #### エージェントを作成または選択する ElevenAgentsでエージェントを作成します。引き渡し完了後すぐに話し始める必要がある場合は、最初のメッセージを設定してください。 セッション中、Amazon Connect自体は何も再生しません。 #### End callを有効にする **Agent → Tools → System tools**で、**End call**を有効にします。これにより、発信者のリクエストが解決したときに エージェントがセッションを終了できます。Amazon Connectはその後、`Complete` 結果でフローを続行します。 #### Amazon Connect転送ルールを追加する（任意） エージェントが発信者を担当者に引き継げるようにするには、プロバイダー設定が`amazon_connect`である 転送ルールを含む**Transfer to number**システムツールを設定します。このルールには宛先がありません。セッションは `Escalate`結果で終了し、コンタクトフローでキューを選択します。転送ルールはAPIで設定します。 エージェントに`PATCH`してツールを追加します。 ```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"}} ] }] } } }}}} }' ``` すでに存在する`end_call`などのツールを含め、エージェントの完全な`built_in_tools`オブジェクトを送信してください。 エージェントは`condition`によりルールを選択します。返されるオプションは固定トークン `amazon_connect`であるため、ツールごとにAmazon Connectルールは1つで十分です。ほかのプロバイダー用に設定した電話番号やSIP URIは、 Amazon Connect通話では提供されません。 > **Note** > > 転送ルールはAPI管理の設定です。これらを使用するエージェントの**Transfer to number**ツールは、上記のようにAPIから > 設定・更新してください。ダッシュボードのツールエディターは、番号ごとの転送リストに対応しています。 #### 専用APIキーを作成する エージェントと同じワークスペースでAPIキーを作成し、ElevenAgentsにスコープを限定します。次のセクションでAWS Secrets Managerに保存します。 それ以外の場所には貼り付けないでください。 #### WebSocket URLを確認する Amazon Connectは、エージェントIDを含むURLに接続します。 | 環境 | AccessUrl | | --------- | --------------------------------------------------------------------------------------------------------------------- | | デフォルト | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | データレジデンシー | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > ElevenLabsアカウントが分離されたレジデンシー環境にある場合は、``をリージョンコードに置き換えてください。 > 利用可能なリージョンについては、[データレジデンシー](/docs/ja/overview/administration/data-residency)をご覧ください。 ## AWSでElevenLabsアプリケーションを登録する このセクションの操作はすべてAPI呼び出しです。再利用する値を一度設定します。 ```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アシスタントを作成する インスタンスにすでにアシスタントがある場合は、この手順をスキップしてください。ない場合は作成して、インスタンスに関連付けます。 ```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 ``` アシスタントIDとARNを記録します。 #### APIキーを保存する Amazon Connectは独自のサービスプリンシパルでSecrets Managerからキーを読み取るため、シークレットは `connect.amazonaws.com`に復号アクセスを許可するカスタマー管理KMSキーで暗号化する必要があります。 デフォルトの`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": "*" } ] } ``` ElevenLabs APIキーがシェル履歴に残らないようファイルに保存してから、キーとシークレットを作成します。 ```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 ``` Amazon Connectにシークレットへの読み取りアクセスを許可します。 **`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 ``` ![カスタマー管理キーで暗号化されたSecrets Managerシークレットと、connect.amazonaws.com用のリソースポリシー](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### サードパーティアプリケーションを作成する ElevenLabs WebSocket URLを、タイプ`A2A_SERVER`のAppIntegrationsアプリケーションとして登録します。 このタイプでは`AuthConfig`が必須です。 **`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" ``` レスポンスにはアプリケーションの`Id`と`Arn`が含まれます。`APPLICATION_ID`と `APPLICATION_ARN`としてエクスポートします。Amazon Connectコンソールには`A2A_SERVER`アプリケーションが表示されないため、 APIで確認してください。 ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### アプリケーションをインスタンスに関連付ける ```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 ``` #### セキュリティプロファイルでアプリケーションを許可する オーケストレーションAIエージェントにアタッチするセキュリティプロファイルには、許可されたAIエージェントとしてアプリケーションを リストする必要があります。そうしないと、実行時に引き渡しが失敗します。 ```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" ``` 管理ウェブサイトではプロファイルとその権限は表示されますが、許可されたAIエージェントは表示されません。これらは APIからのみ確認できます。 ![AIエージェントの表示権限を持つ、Amazon Connect管理ウェブサイト内の専用セキュリティプロファイル](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### オーケストレーションAIエージェントを作成して公開する オーケストレーションエージェントは、オーディオストリーミングを有効にして、すべての音声会話を直ちにアプリケーションへ引き渡します。 音声セッションには即時引き渡しが必要です。テキストストリーミング （`audioStreamingEnabled`をfalseに設定）および`delegateAgentConfiguration`は ElevenLabsではサポートされません。オーディオ即時引き渡しオーケストレーターでは、`toolConfigurations`に `RETURN_TO_CONTROL`タイプの予約済み`Complete`ツールも宣言する必要があります。これがないと、作成リクエストは `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 ``` 公開すると、バージョン付きARN（`:1`）が返されます。コンタクトフローはこれを参照します。 バージョンなしとバージョン付きの両方のエージェントにセキュリティプロファイルをアタッチします。 ```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 ``` ![専用セキュリティプロファイルがアタッチされた、AIエージェントデザイナー内のオーケストレーションAIエージェント](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## コンタクトフローを作成する #### Lexボットを作成する 1. 唯一のインテントが組み込みの`AMAZON.QInConnectIntent`であり、アシスタントARNを設定したLex V2ボットを作成します。 ほかのインテントは追加しないでください。 2. ボットロケールでスピーチtoスピーチを有効にします。双方向オーディオストリーミングは、 Sonicスピーチtoスピーチボットでのみ機能します。 3. ボットのIAMロールにアシスタントを使用する権限を付与します。これがないと、ElevenLabsにリクエストが到達する前に AWS内で`HTTP 403`となり、引き渡しが失敗します。次のようなポリシーをアタッチします。 **`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. ボットをビルドし、バージョンとエイリアスを作成して、エイリアスをインスタンスに関連付けます。 ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Q in Connect引き渡しインテントと組み込みフォールバックインテントが表示されたLex V2ボットのインテント一覧](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### アシスタントとLexブロックを追加する フローデザイナーで、以下のブロックを順に追加します。 1. **Set logging behavior**：有効。以下で引き渡しを確認するにはフローログを使用します。 2. **Connect assistant**：Amazon Q in Connectアシスタントを選択します。 3. **Get customer input**：**Amazon Lex**タブで**Enter an ARN**を選択し、ボット エイリアスARNを貼り付けます。引き渡し前にAmazon Connectが何も再生しないよう、テキスト読み上げプロンプトは半角スペース1つのままにします。 **Session attributes**で、手動設定の属性を2つ追加します。 | Destination key | 値 | | ------------------------------------- | ------------------------------------ | | `x-amz-lex:q-in-connect:ai-agent-arn` | バージョン付きオーケストレーションエージェントARN（`...:1`）。 | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Get customer inputブロックのセッション属性：バージョン付きAIエージェントARNとオーディオパススルーフラグ](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough`は、AWSのプレローンチ期間中にサードパーティ音声パスを有効にします。 > AWSによると、この機能が一般公開されると属性は不要になります。残しておいても問題ありません。 #### 結果に応じて分岐する Amazon ConnectはElevenLabsの結果を`$.Lex.SessionAttributes.Tool` 属性としてフローに渡します。Lexブロックの後に**Check contact attributes**ブロックを追加し、**Namespace**を **Lex**、**Key**を**Session attributes**、**Session Attribute Key**を`Tool`に設定します。次に、結果ごとに **Equals**条件を1つ追加し、**No Match**をエラープロンプトへルーティングします。 | 分岐 | 意味 | 推奨ルート | | ---------- | ---------------------------------------------------------- | ----------------- | | `Complete` | たとえば**End call**ツールにより、エージェントが通話を終了しました。 | 切断 | | `Escalate` | エージェントが担当者を要求しました（[担当者への転送](#transferring-to-a-human)を参照）。 | 作業キューを設定 → キューに転送 | | No Match | その他の値。 | プロンプトを再生 → 切断 | ![Lexセッション属性Toolに設定され、各結果のEquals条件を持つCheck contact attributesブロック](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connectは結果を、通信で送信される大文字の終了タイプではなくタイトルケース（`Escalate`、`Complete`）で書き込むため、 > このブロックにはこの2つの条件だけで十分です。引き渡し後に失敗したセッションは`COMPLETE_WITH_ERROR`タイプで終了します。 > その場合、Lexブロックは**Error**出力に進むか、比較が**No Match**にフォールスルーします。どちらもエラープロンプトにルーティングしてください。 > エクスポートしたフローでは、Lexブロックの**Default**出力は`NoMatchingCondition` > 遷移です。エラーメッセージではなく比較ブロックにつながることを確認してください。 ![Get customer inputブロックからCheck contact attributesブロックへ進み、Escalateをキューへ、Completeを切断へ、No Matchをエラープロンプトへルーティングするコンタクトフロー](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### 公開して割り当てる フローを公開してから、取得済みの電話番号に割り当てます。 ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` 発信通話では、同じフローでコンタクトを開始します。Amazon Connectが顧客に発信し、応答された通話をElevenLabsに 引き渡します。 ```bash aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \ --contact-flow-id --destination-phone-number \ --source-phone-number --region $AWS_REGION ``` ## インテグレーションをテストする #### 電話をかける 電話番号に発信します。フローがLexブロックに到達してから数秒後にエージェントの最初のメッセージが再生されます。 AWS内の引き渡しには、ElevenLabsに接続されるまで約3秒かかります。短い会話をしてから別れの挨拶をしてください。 エージェントが**End call**を呼び出し、ElevenLabsセッションが`Complete`で終了すると、フローはLexブロックから続行します。 転送ルールを追加した場合は、代わりに担当者を求めてください。エージェントが**Transfer to number**を呼び出し、セッションが`Escalate`で終了して、 フローはその分岐に進みます。 #### ElevenLabsで会話を確認する **Conversations**で会話を開きます。ソースはAmazon Connectであり、**Client data** タブには、セッションが受け取った`amazon_connect_*`動的変数が表示されます。 ![Amazon Connect動的変数が一覧表示されたAmazon Connect会話のClient dataタブ](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### AWSでフローログを確認する ロギングを有効にすると、各ブロックがインスタンスのフローロググループにエントリーを書き込みます。**Get customer input**ブロックには、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_]*"' ``` Lexブロックには`"Results": "Complete"`、または転送後は`"Results": "Escalate"`が表示され、その後に該当する分岐のブロックが続きます。 ## 動的変数 Amazon Connectは、すべてのセッションでコンタクトのシステム属性を送信します。ElevenLabsでは、 セッション識別子とともに、これらを動的変数として公開します。 | 動的変数 | 説明 | | ------------------------------------------------------------ | -------------------------------------------- | | `system__caller_id` | 顧客の電話番号（Amazon Connectの顧客エンドポイント）。 | | `system__called_number` | コンタクトで使用しているAmazon Connect電話番号（システムエンドポイント）。 | | `system__call_id` | Amazon ConnectコンタクトID。 | | `amazon_connect_system_attributes_channel` | コンタクトチャネル（例：`VOICE`）。 | | `amazon_connect_system_attributes_customer_endpoint_address` | Amazon Connectから送信された顧客エンドポイントアドレス。 | | `amazon_connect_system_attributes_system_endpoint_address` | Amazon Connectから送信されたシステムエンドポイントアドレス。 | | `amazon_connect_interaction_mode` | コラボレーションモード（例：`HANDOFF`）。 | | `amazon_connect_contact_id` | Amazon ConnectコンタクトID。 | | `amazon_connect_contact_arn` | 完全なコンタクトARN。 | | `amazon_connect_context_id` | A2Aセッション（コンテキスト）ID。 | | `amazon_connect_instance_id` | インスタンスID。 | | `amazon_connect_instance_arn` | インスタンスARN。 | 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](/docs/ja/eleven-agents/customization/personalization#conversation-initiation-webhooks)を使用します。 Amazon Connectセッションでは、エージェントが話し始める前にWebhookが呼び出されます。このとき`caller_id`には 顧客の番号、`called_number`にはAmazon Connect番号、`call_id`にはAmazon ConnectコンタクトIDが設定されます。そのため、フロー内のLambdaで コンタクトIDをキーにコンタクト属性を保存し、Webhookから動的変数および設定オーバーライドとして返すことができます。 ## 人間の担当者への転送 [ElevenLabsの設定](#configure-elevenlabs) で示すように、`amazon_connect` 転送ルールを設定した **Transfer to number** システムツールをエージェントに付与します。ルールの条件が満たされると、エージェントがこのツールを呼び出し、ElevenLabsは `Escalate` の結果とエージェントが指定した理由をもってセッションを終了します。フローの `Escalate` 分岐では、**Set working queue** と **Transfer to queue** でコンタクトを処理します。このルールには転送先が含まれないため、キューはエージェントではなくフローで選択されます。キュー処理、ウィスパーフロー、担当者の選択はAmazon Connect側で維持されます。 **End call** ツールは `Complete` の結果を生成します。いずれの結果の後も、通常どおり通話後分析と通話後Webhookが実行されます。 ### 人間の担当者に概要を渡す Amazon Connectがフローに公開するのは結果のみです。`$.Lex.SessionAttributes.Tool`（およびLexインテント名）には `Escalate` が含まれますが、転送理由を含め、ElevenLabsセッションのそれ以外の情報はフローに届きません。通話を引き継ぐ人間の担当者に概要を伝えるには、概要をコンタクトに保存し、担当者用ウィスパーフローで読み上げます。 1. Amazon Connectの `UpdateContactAttributes` APIを呼び出すエンドポイントを公開します。HTTP APIの背後に最小限のLambdaを置けば十分です。呼び出し元には、インスタンスのコンタクトに対する `connect:UpdateContactAttributes` が許可されている必要があります。 ```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. [Webhookツール](/docs/ja/eleven-agents/customization/tools/webhook-tools) をエージェントに付与し、`amazon_connect_contact_id` 動的変数から設定した `contact_id` と、モデルが作成する `summary` を含めて、そのエンドポイントに `POST` します。共有シークレットはワークスペースシークレットに保存し、リクエストヘッダーとして送信します。システムプロンプトでは、まずこのツールを呼び出し、返却後にのみ **Transfer to number** を呼び出すようエージェントに指示します。モデルが1ターンで両方の呼び出しを出力すると、転送と概要の保存が競合します。この指示をした場合、テストではエージェントのリクエストから約1秒後、Amazon Connectがフローを再開する3秒前に、属性がコンタクトに保存されました。 3. コンタクトフローの `Escalate` 分岐で、**Transfer to queue** の前に **Set whisper flow** ブロックを追加します。このブロックは、**Play prompt** で `$.Attributes.handoff_summary` を読み上げる担当者用ウィスパーフローを指定します。発信者にはキュー処理が聞こえている間に、Amazon Connectが人間の担当者に概要を読み上げ、その後両者を接続します。フローの後続ブロックで `handoff_summary` を再設定しないでください。空の値を設定すると、エンドポイントが書き込んだ値が置き換えられます。 同じ属性は、ルーティングの判断に **Check contact attributes** ブロックでも利用できます。通話後Webhookはフローがすでに進行した後に実行されるため、ルーティング判断ではなくCRMの更新に適しています。 ## トレース Amazon Connectでは、すべてのコラボレーションで[外部エージェントによるトレースデータの送信が必要です](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html)。Amazon Connectがセッションのトレースをサブスクライブすると、ElevenLabsはエージェントの各ターンについて、発信者のトランスクリプト、エージェントの応答、各ツール呼び出しとその結果、スパンごとのタイミングを含むOpenTelemetryトレースを送信します。Amazon Connectはこれらのトレースをコンタクトとともに保存します。表示方法については、[AIエージェントトレース](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html) を参照してください。これらのトレース内のトランスクリプトとツール結果には、Amazon Connect内の他のコンタクトデータと同じマスキング設定が適用されます。インテグレーションを有効にする前に、データ処理要件を確認してください。[通話後Webhook](/docs/ja/eleven-agents/workflows/post-call-webhooks) と同様に、トレースは独自のシステムに配信されます。[ゼロ保持モード](/docs/ja/eleven-agents/customization/privacy/zrm) のエージェントもトレースを送信します。ゼロ保持は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通話から電話番号やSIP URIに発信できず、エスカレーションされた発信者を受け取るキューはフローが決定します。 * データ収集の結果はフローに返されず、共有するコンタクトデータはAmazon Connectが決定します。追加のコンテキストには `amazon_connect_contact_id` をキーとする会話開始Webhookを、ルーティングデータには `UpdateContactAttributes` を呼び出すWebhookツールを、それ以外には通話後Webhookを使用してください。 * `system__override_first_message` などの設定オーバーライドは、フローから渡すことはできません。代わりに会話開始Webhookから返してください。 * 音声セッションでは即時の引き継ぎが必要です。Amazon Connectのチャットチャネル、テキストストリーミング、バックグラウンド（`delegateAgentConfiguration`）コラボレーションはサポートされていません。 * Amazon Connectに送信されるトレースには、発信者のトランスクリプト、エージェントの応答、結果を含むツール呼び出し、タイミングが含まれます。ツール呼び出しのパラメーターは含まれません。 * Amazon Connectのサードパーティエージェントサポートは、AWSが有効化したリージョンでのみ利用可能で、AWSの追加料金が発生する場合があります。 ## トラブルシューティング #### フローが「A2A WebSocket upgrade ... failed （HTTP 403）」で失敗する * このエラーは、リクエストがElevenLabsに到達する前にAWS内で発生します。Lexサービスロールからの `wisdom:SendMessage` に対する `AccessDenied` がCloudTrailにないか確認してください。ボットにアタッチされたロールには、アシスタントとそのセッションに対する `wisdom:CreateSession`、`wisdom:GetAssistant`、`wisdom:SendMessage`、`wisdom:GetNextMessage` が必要です。 * セキュリティプロファイルでアプリケーションが許可されており、フローで参照している公開済みオーケストレーションエージェントバージョンに関連付けられていることを確認してください。 * シークレットのKMSキーとリソースポリシーで `connect.amazonaws.com` にアクセスが許可されていることを確認してください。 #### フローが「the hand-off to the target agent could not be completed」で失敗する * Amazon Connectでは、WebSocket接続の確立に約20秒の猶予があります。`AccessUrl` にAWSから到達できることを確認してください。`wss://` を使用していること、エージェントIDが正しいこと、ネットワークの許可リストが妨げていないことを確認します。 * 接続を独自のインフラストラクチャ経由でプロキシする場合は、そのプロキシをウォーム状態に保ってください。コールドスタートしたサーバーレスインスタンスでは引き継ぎの猶予時間を超えることがあり、ElevenLabsがリクエストを受信する前にAmazon Connectが中断します。 #### LexブロックがError分岐に進み、発信者に何も聞こえない * **Get customer input** ブロックで、両方のセッション属性が設定されていることを確認してください。公開済みかつバージョン指定されたエージェントARNを含む `x-amz-lex:q-in-connect:ai-agent-arn` と、`true` に設定された `x-amz-lex:qic-audio-passthrough` が必要です。 * アプリケーションを許可するセキュリティプロファイルが、そのエージェントバージョンにアタッチされていることを確認してください。 * フローログでブロックのエントリーを確認してください。Amazon Connectで発生したエラーが記録されています。 #### 接続直後にセッションが終了する * `AccessUrl` が `wss://` を使用し、正しいエージェントIDを含み、ワークスペースが存在するリージョンを指していることを確認してください。 * APIキーが有効であり、エージェントのワークスペースに属し、IP制限が設定されていないことを確認してください。 * ワークスペースでAmazon Connectトランスポートが有効になっていることを確認してください。 #### エージェント終了後に発信者にフローのエラープロンプトが聞こえる Lexブロックで、**Default** 出力が `$.Lex.SessionAttributes.Tool` を比較するブロックにつながっていることを確認し、タイトルケースの値 `Escalate` および `Complete` と比較してください。 #### エージェントがまったく話さず、数秒後にセッションが終了する コラボレーターで `audioStreamingEnabled` がtrueに設定されていることを確認してください。テキストストリーミングでは、Amazon Connectはテキストターンを送信し、テキスト応答を期待しますが、ElevenLabsはこれをサポートしていません。ElevenLabsのログには `INIT_SESSION carries no audio configuration` と表示されます。 #### 動的変数がない Amazon Connectは、上記のコンタクトシステム属性と識別子を提供します。フローで設定したカスタムコンタクト属性はエージェントには届きません。代わりに会話開始Webhook経由で渡してください。エージェントの最初のメッセージまたはプロンプトが一度も提供されない変数を参照している場合、セッションは開始時に失敗します。