> 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** > > Integracja z Amazon Connect jest dostępna w ograniczonym zakresie. Obsługa agentów AI innych firm > w Amazon Connect musi być włączona dla twojego konta AWS, a transport ElevenLabs jest włączany dla każdego > obszaru roboczego. Skontaktuj się z przedstawicielem ElevenLabs, zanim skierujesz ruch klientów. ## Omówienie Integracja z Amazon Connect łączy przepływ kontaktu Amazon Connect bezpośrednio z agentem w ElevenAgents przez protokół agentów AI innych firm Amazon Connect, będący rozszerzeniem otwartego [protokołu A2A](https://a2a-protocol.org/). Amazon Connect obsługuje telefonię, routing i kolejkę; ElevenAgents obsługuje rozmowę. Nie potrzebujesz SIP trunk, numeru Twilio ani oprogramowania pośredniczącego. AWS opisuje tę funkcję w sekcji [Współpraca agent-agent](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-collaboration.html); ten przewodnik omawia szczegóły ElevenLabs i kroki AWS wymagane do połączenia z agentem ElevenLabs. Ten sam przepływ obsługuje połączenia przychodzące i kontakty wychodzące uruchamiane za pomocą `StartOutboundVoiceContact`. Gdy agent ElevenLabs zakończy pracę, Amazon Connect kontynuuje przepływ kontaktu i rozgałęzia go na podstawie otrzymanego wyniku. ## Jak działa integracja 1. Przepływ kontaktu dociera do bloku **Get customer input**, który wywołuje bota Amazon Lex V2 z intencją `AMAZON.QInConnectIntent`. 2. Agent AI orkiestrujący Amazon Connect natychmiast przekazuje rozmowę do aplikacji innej firmy zarejestrowanej dla ElevenLabs. 3. Amazon Connect otwiera WebSocket do punktu końcowego ElevenLabs w `AccessUrl` aplikacji, uwierzytelniając się kluczem API przechowywanym w AWS Secrets Manager. 4. Amazon Connect sygnalizuje, że kanał dzwoniącego jest aktywny, a następnie Amazon Connect i ElevenLabs wymieniają 16-bitowe liniowe audio PCM jako wiadomości A2A. Amazon Connect proponuje częstotliwość próbkowania, a ElevenLabs ją przyjmuje, więc agent nie wymaga zmian formatu audio. 5. Gdy agent zakończy połączenie lub przekaże dzwoniącego do człowieka, ElevenLabs kończy sesję z wynikiem `Complete` lub `Escalate`, a przepływ jest kontynuowany od bloku Lex; zobacz [Przekazywanie do człowieka](#transferring-to-a-human). ## Wymagania Przed rozpoczęciem upewnij się, że masz: 1. Instancję Amazon Connect w warstwie Connect Customer z obsługą agentów AI innych firm włączoną dla konta i regionu. 2. Asystenta Amazon Q in Connect powiązanego z instancją. 3. Uprawnienia AWS do tworzenia kluczy KMS, sekretów Secrets Manager, aplikacji AppIntegrations, profili bezpieczeństwa Connect, agentów AI Amazon Q in Connect, botów Lex V2 i przepływów kontaktu. 4. Obszar roboczy ElevenLabs z włączonym transportem Amazon Connect. 5. Agenta ElevenLabs i dedykowany klucz API. 6. AWS CLI v2 i [awscurl](https://github.com/okigan/awscurl) (`pip install awscurl`) dla wywołań, których struktury żądań nie są jeszcze dostępne w wydanych wersjach CLI. > **Note** > > Zachowaj wszystkie zasoby AWS na tym samym koncie i w tym samym regionie co instancja Amazon Connect. Poniższe kroki > używają AWS CLI tam, gdzie obsługuje ono dane wywołanie, oraz `awscurl` (żądania HTTP podpisanego SigV4) tam, > gdzie go nie obsługuje. Są zgodne z instrukcją AWS [Skonfiguruj współpracę z zewnętrznym agentem AI ](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-setup-external.html) i dodają wartości specyficzne dla > ElevenLabs. ## Skonfiguruj ElevenLabs #### Utwórz lub wybierz agenta Utwórz agenta w ElevenAgents. Dodaj mu pierwszą wiadomość, jeśli ma mówić zaraz po zakończeniu przekazania; Amazon Connect nie odtwarza niczego własnego podczas sesji. #### Włącz End call W **Agent → Tools → System tools** włącz **End call**, aby agent mógł zakończyć sesję, gdy prośba dzwoniącego zostanie obsłużona. Amazon Connect kontynuuje wtedy przepływ z wynikiem `Complete`. #### Dodaj regułę przekazania Amazon Connect (opcjonalnie) Aby agent mógł przekazać dzwoniącego do człowieka, dodaj mu narzędzie systemowe **Transfer to number** z regułą przekazania, której konfiguracja dostawcy to `amazon_connect`. Reguła nie ma miejsca docelowego: sesja kończy się wynikiem `Escalate`, a kolejkę wybiera twój przepływ kontaktu. Reguły przekazania konfiguruje się przez API. Dodaj narzędzie przez `PATCH` do agenta: ```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"}} ] }] } } }}}} }' ``` Wyślij pełny obiekt `built_in_tools` agenta, wraz z narzędziami, które już ma, takimi jak `end_call`. Agent wybiera regułę według jej `condition`; opcja, którą zwraca, to stały token `amazon_connect`, więc wystarczy jedna reguła Amazon Connect na narzędzie. Numery telefonów i identyfikatory URI SIP skonfigurowane dla innych dostawców nie są oferowane podczas połączeń Amazon Connect. > **Note** > > Reguły przekazania są ustawieniem zarządzanym przez API. Narzędzie **Transfer to number** agenta, który z nich korzysta, > konfiguruj i aktualizuj przez API, jak powyżej; edytor narzędzi w panelu działa z > listą przekazań dla poszczególnych numerów. #### Utwórz dedykowany klucz API Utwórz klucz API w tym samym obszarze roboczym co agent i ogranicz jego zakres do ElevenAgents. W następnej sekcji zapiszesz go w AWS Secrets Manager; nie wklejaj go nigdzie indziej. #### Zanotuj adres URL WebSocket Amazon Connect łączy się z adresem URL zawierającym identyfikator agenta: | Środowisko | AccessUrl | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | | Domyślne | `wss://api.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Rezydencja danych | `wss://api..residency.elevenlabs.io/v1/convai/conversation/amazon-connect/agent_7101k5zvyjhmfg983brhmhkd98n6` | > **Info** > > Jeśli twoje konto ElevenLabs działa w izolowanym środowisku rezydencji danych, zastąp `` > kodem regionu. Dostępne regiony znajdziesz w [rezydencji danych](/docs/pl/overview/administration/data-residency). ## Zarejestruj aplikację ElevenLabs w AWS Wszystko w tej sekcji to wywołanie API. Ustaw wartości, których użyjesz ponownie: ```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 ``` #### Utwórz asystenta Amazon Q in Connect Pomiń ten krok, jeśli instancja ma już asystenta. W przeciwnym razie utwórz go i powiąż z instancją: ```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 ``` Zapisz identyfikator i ARN asystenta. #### Zapisz klucz API Amazon Connect odczytuje klucz z Secrets Manager przez własny podmiot usługi, więc sekret musi być zaszyfrowany kluczem KMS zarządzanym przez klienta, który przyznaje `connect.amazonaws.com` dostęp do odszyfrowania. Nie można użyć domyślnego klucza `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": "*" } ] } ``` Zapisz klucz API ElevenLabs w pliku, aby nigdy nie pojawił się w historii powłoki, a potem utwórz klucz i sekret: ```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 ``` Przyznaj Amazon Connect dostęp do odczytu sekretu: **`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 ``` ![Sekret Secrets Manager zaszyfrowany kluczem zarządzanym przez klienta oraz jego polityka zasobów dla connect.amazonaws.com](/docs/_fern-img/3fc91a773575a547f3ac6d3a24d14cffac4535227057e4e8e4eb3ccfc71f27a0.webp) #### Utwórz aplikację zewnętrzną Zarejestruj adres URL WebSocket ElevenLabs jako aplikację AppIntegrations typu `A2A_SERVER`. `AuthConfig` jest wymagane dla tego typu. **`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" ``` Odpowiedź zawiera `Id` i `Arn` aplikacji; wyeksportuj je jako `APPLICATION_ID` oraz `APPLICATION_ARN`. Konsola Amazon Connect nie wyświetla aplikacji `A2A_SERVER`, więc sprawdź je przez API: ```bash aws appintegrations get-application --arn "$APPLICATION_ARN" --region $AWS_REGION ``` #### Powiąż aplikację ze swoją instancją ```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 ``` #### Zezwól na aplikację w profilu zabezpieczeń Profil zabezpieczeń przypisany do agenta AI orkiestracji musi zawierać aplikację na liście dozwolonych agentów AI, inaczej przekazanie nie powiedzie się w trakcie działania. ```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" ``` Witryna administratora pokazuje profil i jego uprawnienia, ale nie dozwolonych agentów AI; są one widoczne tylko przez API. ![Dedykowany profil zabezpieczeń w witrynie administratora Amazon Connect z uprawnieniami do wyświetlania agentów AI](/docs/_fern-img/2d9c7dd52c77bfeefd3c4f5beb99681d578014c407cf37dbc7d2e2f457c40ee8.webp) #### Utwórz i opublikuj agenta AI orkiestracji Agent orkiestracji natychmiast przekazuje każdą rozmowę głosową do aplikacji z włączonym strumieniowaniem audio. Sesje głosowe wymagają natychmiastowego przekazania; strumieniowanie tekstu (`audioStreamingEnabled` ustawione na false) i `delegateAgentConfiguration` nie są obsługiwane przez ElevenLabs. Orkiestrator z natychmiastowym przekazaniem audio musi też zadeklarować zarezerwowane narzędzie `Complete` typu `RETURN_TO_CONTROL` w `toolConfigurations`; bez niego żądanie utworzenia zakończy się błędem `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 ``` Publikacja zwraca wersjonowany ARN (`:1`); odwołuje się do niego przepływ kontaktu. Przypisz profil zabezpieczeń zarówno do agenta bez wersji, jak i do wersjonowanego: ```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 ``` ![Agent AI orkiestracji w projektancie agentów AI z przypisanym dedykowanym profilem zabezpieczeń ](/docs/_fern-img/3ade9397b18d3af79fc4f3ae63fef06cec9e17d59109e5c226d403339c32f052.webp) ## Zbuduj przepływ kontaktu #### Utwórz bota Lex 1. Utwórz bota Lex V2, którego jedyną intencją jest wbudowana `AMAZON.QInConnectIntent`, skonfigurowana z ARN asystenta. Nie dodawaj innych intencji. 2. Włącz mowę-mowę w ustawieniach regionalnych bota. Dwukierunkowe strumieniowanie audio działa tylko z botami Sonic obsługującymi mowę-mowę. 3. Zezwól roli IAM bota na używanie asystenta. Bez tego przekazanie kończy się w AWS błędem `HTTP 403`, zanim jakiekolwiek żądanie dotrze do ElevenLabs. Dołącz politykę podobną do tej: **`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. Zbuduj bota, utwórz wersję i alias, a następnie powiąż alias z instancją: ```bash aws connect associate-bot --instance-id $INSTANCE_ID \ --lex-v2-bot AliasArn= --region $AWS_REGION ``` ![Lista intencji bota Lex V2 z intencją przekazania do Q in Connect i wbudowaną intencją awaryjną](/docs/_fern-img/6d857b4a57a6289c26249b80bad8181b68af5b7654db9ae0adbf0ea830091ca4.webp) #### Dodaj asystenta i blok Lex W projektancie przepływu dodaj te bloki w tej kolejności: 1. **Set logging behavior**: włączone. Dziennik przepływu pozwala sprawdzić opisane niżej przekazanie. 2. **Connect assistant**: wybierz swojego asystenta Amazon Q in Connect. 3. **Get customer input**: na karcie **Amazon Lex** wybierz **Enter an ARN** i wklej ARN aliasu bota. Zostaw w prompcie zamiany tekstu na mowę pojedynczą spację, aby Amazon Connect nic nie odtworzył przed przekazaniem. W sekcji **Session attributes** dodaj dwa atrybuty ustawione ręcznie: | Klucz docelowy | Wartość | | ------------------------------------- | ----------------------------------------------- | | `x-amz-lex:q-in-connect:ai-agent-arn` | Wersjonowany ARN agenta orkiestracji (`...:1`). | | `x-amz-lex:qic-audio-passthrough` | `true` | ![Atrybuty sesji bloku Get customer input: wersjonowany ARN agenta AI oraz flaga przekazywania audio](/docs/_fern-img/812e85e379bcf3eb422497d27fe7740da8e3482222ca858089ad1b4de2f92e4b.webp) > **Note** > > `x-amz-lex:qic-audio-passthrough` kontroluje ścieżkę głosową innej firmy w okresie przedpremierowym AWS. > AWS podaje, że atrybut nie będzie już potrzebny, gdy funkcja stanie się publiczna; pozostawienie go > nie szkodzi. #### Rozgałęź przepływ według wyniku Amazon Connect przekazuje wynik ElevenLabs do przepływu jako atrybut `$.Lex.SessionAttributes.Tool`. Dodaj blok **Check contact attributes** po bloku Lex, ustaw **Namespace** na **Lex**, **Key** na **Session attributes** i **Session Attribute Key** na `Tool`, a następnie dodaj po jednym warunku **Equals** dla każdego wyniku oraz skieruj **No Match** do promptu błędu: | Gałąź | Znaczenie | Sugerowana trasa | | ---------- | ----------------------------------------------------------------------------------------- | ------------------------------------------ | | `Complete` | Agent zakończył rozmowę, np. narzędziem **End call**. | Rozłącz | | `Escalate` | Agent poprosił o człowieka (zobacz [Przekazanie do człowieka](#transferring-to-a-human)). | Ustaw kolejkę roboczą → Przekaż do kolejki | | No Match | Dowolna inna wartość. | Odtwórz prompt → Rozłącz | ![Blok Check contact attributes skonfigurowany dla atrybutu sesji Lex Tool z warunkami Equals dla każdego wyniku](/docs/_fern-img/e73068b736d4023417602a17c480112a3d7f5617694390fc8a88f03c4b7855e1.webp) > **Warning** > > Amazon Connect zapisuje wynik wielkością tytułową (`Escalate`, `Complete`), a nie wielkimi literami > typu zakończenia wysyłanego przez połączenie, więc blok potrzebuje tylko tych dwóch warunków. Sesja, > która nie powiedzie się po przekazaniu, kończy się typem `COMPLETE_WITH_ERROR`; blok Lex przechodzi wtedy > na wyjście **Error** albo porównanie trafia do **No Match**, więc skieruj oba do promptu błędu. W wyeksportowanym > przepływie wyjście **Default** bloku Lex to przejście `NoMatchingCondition`; upewnij się, że prowadzi ono do > bloku porównania, a nie komunikatu błędu. ![Przepływ kontaktu, w którym blok Get customer input prowadzi do bloku Check contact attributes, kierującego Escalate do kolejki, Complete do rozłączenia, a No Match do promptu błędu](/docs/_fern-img/71e5a3ec507c431ff692545db58376e07db0605efb8bb42f4e17e709a1a0dedf.webp) #### Opublikuj i przypisz Opublikuj przepływ, a potem skieruj na niego zarezerwowany numer telefonu: ```bash aws connect associate-phone-number-contact-flow --instance-id $INSTANCE_ID \ --phone-number-id --contact-flow-id --region $AWS_REGION ``` W przypadku połączeń wychodzących rozpocznij kontakt tym samym przepływem; Amazon Connect zadzwoni do klienta i przekaże odebrane połączenie do ElevenLabs: ```bash aws connect start-outbound-voice-contact --instance-id $INSTANCE_ID \ --contact-flow-id --destination-phone-number \ --source-phone-number --region $AWS_REGION ``` ## Przetestuj integrację #### Wykonaj połączenie Zadzwoń na numer. Pierwsza wiadomość agenta zostanie odtworzona kilka sekund po dotarciu przepływu do bloku Lex; przekazanie wewnątrz AWS trwa około trzech sekund, zanim nastąpi kontakt z ElevenLabs. Przeprowadź krótką rozmowę i pożegnaj się: agent wywoła **End call**, sesja ElevenLabs zakończy się `Complete`, a przepływ będzie kontynuowany od bloku Lex. Jeśli dodałeś regułę przekazania, poproś zamiast tego o człowieka: agent wywoła **Transfer to number**, sesja zakończy się `Escalate`, a przepływ wybierze tę gałąź. #### Sprawdź rozmowę w ElevenLabs Otwórz rozmowę w **Conversations**. Jej źródłem jest Amazon Connect, a karta **Client data** zawiera dynamiczne zmienne `amazon_connect_*`, które otrzymała sesja. ![Karta Client data rozmowy Amazon Connect z dynamicznymi zmiennymi Amazon Connect ](/docs/_fern-img/ced3be27e366822341940e3fa5f96c2cd7376b1e63e86ace2dac31d778039417.webp) #### Sprawdź dziennik przepływu w AWS Przy włączonym logowaniu każdy blok zapisuje wpis w grupie dzienników przepływu instancji. Blok **Get customer input** rejestruje wynik otrzymany od 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_]*"' ``` Dla bloku Lex oczekuj `"Results": "Complete"` lub po przekazaniu `"Results": "Escalate"`, a następnie bloków z danej gałęzi. ## Zmienne dynamiczne Amazon Connect wysyła atrybuty systemowe kontaktu przy każdej sesji. ElevenLabs udostępnia je wraz z identyfikatorami sesji jako zmienne dynamiczne: | Zmienna dynamiczna | Opis | | ------------------------------------------------------------ | ---------------------------------------------------------------------- | | `system__caller_id` | Numer telefonu klienta (punkt końcowy klienta Amazon Connect). | | `system__called_number` | Numer Amazon Connect, na który trafił kontakt (punkt końcowy systemu). | | `system__call_id` | Identyfikator kontaktu Amazon Connect. | | `amazon_connect_system_attributes_channel` | Kanał kontaktu, np. `VOICE`. | | `amazon_connect_system_attributes_customer_endpoint_address` | Adres punktu końcowego klienta wysłany przez Amazon Connect. | | `amazon_connect_system_attributes_system_endpoint_address` | Adres punktu końcowego systemu wysłany przez Amazon Connect. | | `amazon_connect_interaction_mode` | Tryb współpracy, np. `HANDOFF`. | | `amazon_connect_contact_id` | Identyfikator kontaktu Amazon Connect. | | `amazon_connect_contact_arn` | Pełny ARN kontaktu. | | `amazon_connect_context_id` | Identyfikator sesji A2A (kontekstu). | | `amazon_connect_instance_id` | Identyfikator instancji. | | `amazon_connect_instance_arn` | ARN instancji. | W sesjach Amazon Connect `system__caller_id` zawsze oznacza klienta, a `system__called_number` zawsze oznacza numer Amazon Connect — zarówno dla kontaktów przychodzących, jak i wychodzących. Każdy inny element kontekstu kontaktu wysyłany przez Amazon Connect jest udostępniany tak samo: nazwy zagnieżdżone są łączone podkreśleniami i konwertowane do snake case z prefiksem `amazon_connect_`. Niestandardowe atrybuty kontaktu ustawione w przepływie za pomocą **Set contact attributes** nie należą obecnie do kontekstu wysyłanego przez Amazon Connect, nawet jeśli profil zabezpieczeń agenta AI może wyświetlać atrybuty kontaktu; jeśli AWS zacznie je uwzględniać, pojawią się automatycznie pod tym samym prefiksem. Nie możesz wybrać, które dane kontaktu udostępnia Amazon Connect; AWS przekazuje stały zestaw kontekstu. Aby przekazać dodatkowy kontekst, użyj [webhooka inicjującego rozmowę](/docs/pl/eleven-agents/customization/personalization#conversation-initiation-webhooks). W sesjach Amazon Connect webhook jest wywoływany przed odezwaniem się agenta, z `caller_id` ustawionym na numer klienta, `called_number` na numer Amazon Connect, a `call_id` na identyfikator kontaktu Amazon Connect, dzięki czemu funkcja Lambda w przepływie może przechowywać atrybuty kontaktu z kluczem identyfikatora kontaktu, a webhook może zwracać je jako zmienne dynamiczne i nadpisania konfiguracji. ## Przekazanie do człowieka Daj agentowi narzędzie systemowe **Transfer to number** z regułą przekazania `amazon_connect`, jak pokazano w sekcji [Skonfiguruj ElevenLabs](#configure-elevenlabs). Gdy warunek reguły zostanie spełniony, agent wywołuje narzędzie, a ElevenLabs kończy sesję wynikiem `Escalate` i powodem podanym przez agenta. Gałąź `Escalate` w przepływie obsługuje wtedy kontakt przez **Set working queue** i **Transfer to queue**. Reguła nie zawiera miejsca docelowego, więc kolejka jest wybierana w przepływie, a nie przez agenta; obsługa kolejki, przepływy szeptane i wybór agenta pozostają w Amazon Connect. Narzędzie **End call** zwraca wynik `Complete`. Analiza po rozmowie i webhook po rozmowie działają jak zwykle po każdym z tych wyników. ### Przekazywanie podsumowania agentowi Amazon Connect udostępnia przepływowi tylko wynik: `$.Lex.SessionAttributes.Tool` (oraz nazwa intencji Lex) zawierają `Escalate`, a nic innego z sesji ElevenLabs, w tym powód przekazania, nie trafia do przepływu. Aby przekazać informacje człowiekowi odbierającemu rozmowę, samodzielnie zapisz podsumowanie przy kontakcie oraz pozwól, by odczytał je przepływ szeptany agenta: 1. Udostępnij endpoint wywołujący API `UpdateContactAttributes` Amazon Connect. Wystarczy minimalna funkcja Lambda za HTTP API; wywołujący musi mieć uprawnienie `connect:UpdateContactAttributes` do kontaktów instancji: ```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. Daj agentowi [narzędzie webhook](/docs/pl/eleven-agents/customization/tools/webhook-tools), które wysyła `POST` do tego endpointu z `contact_id` wypełnionym dynamiczną zmienną `amazon_connect_contact_id` oraz `summary` napisanym przez model. Zachowaj wspólny sekret w sekrecie obszaru roboczego i wyślij go jako nagłówek żądania. W prompcie systemowym poleć agentowi, by najpierw wywołał to narzędzie, a **Transfer to number** dopiero po jego zwróceniu; model, który emituje oba wywołania w jednej turze, powoduje wyścig między przekazaniem a podsumowaniem. W naszych testach, przy tej instrukcji, atrybut pojawiał się przy kontakcie około sekundę po żądaniu agenta, trzy sekundy przed wznowieniem przepływu przez Amazon Connect. 3. W gałęzi `Escalate` przepływu kontaktu dodaj blok **Set whisper flow** przed \*\*Transfer to queue \*\*, wskazujący przepływ szeptany agenta, którego **Play prompt** odczytuje `$.Attributes.handoff_summary`. Amazon Connect odtwarza go agentowi podczas gdy dzwoniący słyszy obsługę kolejki, a potem łączy ich ze sobą. Nie ustawiaj ponownie `handoff_summary` w późniejszym bloku przepływu: pusta wartość zastąpi wtedy wartość zapisaną przez endpoint. Ten sam atrybut jest dostępny w bloku **Check contact attributes** przy podejmowaniu decyzji o trasowaniu. Webhook po rozmowie uruchamia się dopiero po kontynuowaniu przepływu, więc nadaje się do aktualizacji CRM, a nie do decyzji o trasowaniu. ## Ślady Amazon Connect [wymaga od agentów zewnętrznych wysyłania danych śledzenia](https://docs.aws.amazon.com/connect/latest/adminguide/a2a-trace-enforcement.html) dla każdej współpracy. Gdy Amazon Connect subskrybuje śledzenie w sesji, ElevenLabs wysyła ślad OpenTelemetry dla każdej tury agenta, zawierający transkrypcję rozmówcy, odpowiedź agenta, każde wywołanie narzędzia wraz z wynikiem oraz czas dla każdego zakresu. Amazon Connect przechowuje te ślady przy kontakcie; zobacz [Ślady agenta AI](https://docs.aws.amazon.com/connect/latest/adminguide/ai-agent-traces.html), aby dowiedzieć się, jak je wyświetlić. Transkrypcje i wyniki narzędzi w tych śladach podlegają tym samym ustawieniom redakcji co pozostałe dane kontaktu w Amazon Connect, więc przed włączeniem integracji sprawdź wymagania dotyczące przetwarzania danych. Podobnie jak [webhooki po rozmowie](/docs/pl/eleven-agents/workflows/post-call-webhooks), ślady są dostarczane do własnych systemów: agenci w [trybie zerowego przechowywania](/docs/pl/eleven-agents/customization/privacy/zrm) nadal je wysyłają, ponieważ zerowe przechowywanie określa, co przechowuje ElevenLabs, a nie to, co otrzymuje instancja Amazon Connect. ## Audio Amazon Connect proponuje dla każdej sesji 16-bitowy, monofoniczny liniowy PCM z częstotliwością 8, 16 lub 24 kHz, a ElevenLabs przyjmuje tę propozycję, więc skonfigurowane formaty audio agenta nie są używane w sesjach Amazon Connect. Przerywanie wypowiedzi rozmówcy jest wykrywane przez ElevenLabs i zgłaszane do Amazon Connect, dzięki czemu buforowane odtwarzanie jest natychmiast czyszczone. Dane wejściowe z klawiatury zebrane przez Amazon Connect są przekazywane agentowi jako cyfry DTMF. Własny znacznik ciszy Amazon Connect jest ignorowany; użyj limitu czasu tury agenta, aby ponownie zachęcić milczącego rozmówcę do odpowiedzi. ## Ograniczenia i nieobsługiwane funkcje * Narzędzia klienta oraz narzędzie systemowe **Play keypad touch tone** nie są obsługiwane. **Transfer to number** działa tylko przez regułę przekazania Amazon Connect: agent nie może wybrać numeru telefonu ani identyfikatora URI SIP w rozmowie Amazon Connect, a przepływ decyduje, która kolejka otrzyma eskalowanego rozmówcę. * Wyniki zbierania danych nie są zwracane do przepływu, a Amazon Connect decyduje, które dane kontaktu udostępnia. Użyj webhooka inicjującego rozmowę z kluczem `amazon_connect_contact_id` do przekazywania dodatkowego kontekstu, narzędzia webhook wywołującego `UpdateContactAttributes` do danych trasowania oraz webhooka po rozmowie do wszystkiego innego. * Nadpisania konfiguracji, takie jak `system__override_first_message`, nie mogą być przekazywane z przepływu. Zwróć je zamiast tego z webhooka inicjującego rozmowę. * Sesje głosowe wymagają natychmiastowego przekazania. Kanał czatu Amazon Connect, strumieniowanie tekstu i współpraca w tle (`delegateAgentConfiguration`) nie są obsługiwane. * Ślady wysyłane do Amazon Connect obejmują transkrypcję rozmówcy, odpowiedzi agenta, wywołania narzędzi z ich wynikami oraz czas. Parametry wywołań narzędzi nie są uwzględniane. * Obsługa agentów innych firm w Amazon Connect jest dostępna tylko tam, gdzie AWS ją włączyło, i może wiązać się z dodatkowymi opłatami AWS. ## Rozwiązywanie problemów #### Flow kończy się błędem „A2A WebSocket upgrade ... failed (HTTP 403)” * Błąd pojawia się w AWS, zanim jakiekolwiek żądanie dotrze do ElevenLabs. Sprawdź CloudTrail pod kątem `AccessDenied` dla `wisdom:SendMessage` z roli usługi Lex: rola przypisana do bota potrzebuje uprawnień `wisdom:CreateSession`, `wisdom:GetAssistant`, `wisdom:SendMessage` i `wisdom:GetNextMessage` dla asystenta oraz jego sesji. * Sprawdź, czy profil zabezpieczeń zezwala na aplikację i jest powiązany z opublikowaną wersją agenta orkiestracji wskazaną w flow. * Sprawdź, czy klucz KMS sekretu i polityka zasobów przyznają dostęp `connect.amazonaws.com`. #### Flow kończy się błędem „the hand-off to the target agent could not be completed” * Amazon Connect daje połączeniu WebSocket około 20 sekund na uruchomienie. Sprawdź, czy `AccessUrl` jest dostępny z AWS: `wss://`, właściwy identyfikator agenta, brak listy dozwolonych sieci blokującej połączenie. * Jeśli kierujesz połączenie przez własną infrastrukturę, utrzymuj proxy w gotowości. Zimna instancja serverless może uruchamiać się dłużej niż trwa okno przekazania, a Amazon Connect rezygnuje, zanim ElevenLabs w ogóle zobaczy żądanie. #### Blok Lex przechodzi do gałęzi Error, a dzwoniący nic nie słyszy * Sprawdź, czy oba atrybuty sesji są ustawione w bloku **Get customer input**: `x-amz-lex:q-in-connect:ai-agent-arn` z opublikowanym, wersjonowanym ARN agenta oraz `x-amz-lex:qic-audio-passthrough` ustawiony na `true`. * Sprawdź, czy profil zabezpieczeń zezwalający na aplikację jest przypisany do tej wersji agenta. * Sprawdź wpis bloku w logu flow — zawiera błąd napotkany przez Amazon Connect. #### Sesja kończy się od razu po połączeniu * Sprawdź, czy `AccessUrl` używa `wss://`, zawiera właściwy identyfikator agenta i wskazuje region, w którym znajduje się twój workspace. * Sprawdź, czy klucz API jest aktywny, należy do workspace agenta i nie ma ograniczeń IP. * Sprawdź, czy transport Amazon Connect jest włączony w twoim workspace. #### Dzwoniący słyszy komunikat błędu flow po zakończeniu pracy agenta W bloku Lex upewnij się, że wyjście **Default** prowadzi do bloku porównującego `$.Lex.SessionAttributes.Tool`, a porównanie używa wartości zapisanych wielką literą: `Escalate` i `Complete`. #### Agent nigdy nie mówi, a sesja kończy się po kilku sekundach Sprawdź, czy współpracownik ma ustawione `audioStreamingEnabled` na true. Przy streamingu tekstu Amazon Connect wysyła tury tekstowe i oczekuje odpowiedzi tekstowych, których ElevenLabs nie obsługuje; w logach ElevenLabs pojawia się `INIT_SESSION carries no audio configuration`. #### Brakuje zmiennych dynamicznych Amazon Connect udostępnia wymienione wyżej atrybuty systemowe kontaktu i identyfikatory. Niestandardowe atrybuty kontaktu ustawione w flow nie trafiają do agenta; przekaż je przez webhook inicjujący rozmowę. Jeśli pierwsza wiadomość lub prompt agenta odwołuje się do zmiennej, której nigdy nie przekazano, sesja kończy się błędem podczas uruchamiania.