AWS connect documentation change
Summary
Restructured troubleshooting guide for Connect AI agents by consolidating sections into linked sub-guides and removing detailed technical logging procedures
Security assessment
The changes focus on content reorganization and simplification rather than addressing security vulnerabilities. Removed detailed logging format examples and moved troubleshooting steps to separate pages without indicating security fixes.
Diff
diff --git a/connect/latest/adminguide/ts-ai-agents-self-service.md b/connect/latest/adminguide/ts-ai-agents-self-service.md index 1e8aef335..4d6f1762d 100644 --- a//connect/latest/adminguide/ts-ai-agents-self-service.md +++ b//connect/latest/adminguide/ts-ai-agents-self-service.md @@ -5 +5 @@ -Enable loggingUnexpected escalationUnexpected termination +# Troubleshoot Connect AI agent issues @@ -7,3 +7 @@ Enable loggingUnexpected escalationUnexpected termination -# Troubleshoot Connect AI agents self-service issues - -Use this topic to help diagnose and resolve common issues with Connect AI agents self-service functionality. +Use this topic to help diagnose and resolve common issues with Connect AI agents. @@ -13,83 +11 @@ Use this topic to help diagnose and resolve common issues with Connect AI agents - * Enable logging for Connect AI agents self-service interactions - - * Customers are unexpectedly receiving "Escalating to agent..." - - * Self-service chat or voice call is unexpectedly terminating - - - - -## Enable logging for Connect AI agents self-service interactions - -To troubleshoot self-service issues effectively, you need to view the logs for Connect AI agents self-service interactions. Use the following instructions to enable CloudWatch Logging, Amazon Lex logging, and Amazon Connect logging. - - * **CloudWatch Logs** : Enable CloudWatch Logging for your Connect AI agents by following the steps in [Monitor Connect AI agents](./monitor-ai-agents.html). - -Self-service interactions generate log entries with the event type `TRANSCRIPT_SELF_SERVICE_MESSAGE` in the following format: - - { - "assistant_id": "{UUID}", - "event_timestamp": 1751414298692, - "event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE", - "session_id": "{UUID}", - "utterance": "[CUSTOMER]...", - "prompt": "{prompt used}", - "prompt_type": "SELF_SERVICE_PRE_PROCESS|SELF_SERVICE_ANSWER_GENERATION", - "completion": "{Response from model}", - "model_id": "{model id e.g.: us.amazon.nova-pro-v1:0}", - "session_message_id": "{UUID}", - "parsed_response": "{model response}" - } - - * **Amazon Lex logging** : Enable Amazon Lex logging by following the steps in [Logging errors with error logs in Amazon Lex V2](https://docs.aws.amazon.com/exv2/latest/dg/monitoring-cloudwatch.html). - - * **Amazon Connect logging** : Enable Amazon Connect logging by adding a [Set logging behavior](./set-logging-behavior.html) flow block in your Amazon Connect flow. - - - - -## Customers are unexpectedly receiving "Escalating to agent..." - -Unexpected agent escalation occurs when there's an error during the self-service bot interaction or when the model doesn't produce a valid `tool_use` response for `SELF_SERVICE_PRE_PROCESS`. - -### Troubleshooting steps - - 1. **Check the Connect AI agent logs** : Examine the `completion` attribute in the associated log entry. - - 2. **Validate the stop reason** : Confirm that the `stop_reason` is `tool_use`. - - 3. **Verify parsed response** : Check if the `parsed_response` field is populated, as this represents the response you'll receive from the model. - - - - -### Known issue with Claude 3 Haiku - -If you're using Claude 3 Haiku for self-service pre-processing, there's a known issue where it generates the `tool_use` JSON as text, resulting in a `stop_reason` of `end_turn` instead of `tool_use`. - -**Solution** : Update your custom prompt to wrap the `tool_use` JSON string inside `<tool>` tags by adding this instruction: - - - You MUST enclose the tool_use JSON in the <tool> tag - -## Self-service chat or voice call is unexpectedly terminating - -This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amazon Nova Pro configuration. These issues are described below. - -### Timeouts from Amazon Lex - - * **Symptoms** : Amazon Connect logs show "Internal Server Error" for the [Get customer input](./get-customer-input.html) block - - * **Cause** : Your self-service bot timed out while providing results within the 10-second limit. Timeout errors won't appear in Connect AI agent logs. - - * **Solution** : Simplify your prompt by removing complex reasoning to reduce processing time. - - - - -### Errors from Amazon Lex - - * **Missing Connect AI agents flow block** : Ensure you've added the [Connect assistant](./connect-assistant-block.html) block to your Amazon Connect flow. A common oversight is missing this block, which results in the following error: - - com.amazonaws.services.lexruntimev2.model.ValidationException: Amazon Lex needs active session for Connect AI agents. - Please provide valid session attribute x-amz-lex:q-in-connect:session-arn + * [Logging and tracing for Connect AI agents](./viewing-logs-for-connect-ai-agents-self-service.html) @@ -97 +13 @@ This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amaz - * **General Amazon Lex errors** : Check Amazon Lex logs for any errors and address them accordingly. + * [Troubleshoot agentic self-service issues](./ts-agentic-self-service.html) @@ -98,0 +15 @@ This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amaz + * [Common issues](./ts-common-self-service-issues.html) @@ -99,0 +17 @@ This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amaz + * [(Legacy) Self-service issues](./ts-non-agentic-self-service.html) @@ -102 +19,0 @@ This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amaz -### Amazon Nova Pro configuration @@ -104 +20,0 @@ This issue can occur due to timeouts or errors from Amazon Lex or incorrect Amaz -If you're using Amazon Nova Pro for your custom AI prompts, ensure that the tool_use examples follow [Python-compatible format](./create-ai-prompts.html#nova-pro-aiprompt). @@ -112 +28 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Use generative AI-powered self-service +(legacy) Use generative AI-powered self-service @@ -114 +30 @@ Use generative AI-powered self-service -Integrate with step-by-step guides +Logging and tracing