AWS connect documentation change
Summary
Added documentation for two new event types (TRANSCRIPT_ORCHESTRATION_MESSAGE and TRANSCRIPT_ORCHESTRATION_ERROR) with detailed field definitions and example log entries for monitoring AI agent orchestration in Amazon Connect.
Security assessment
This change adds monitoring and logging capabilities for AI agent orchestration, which enhances observability but does not directly address a security vulnerability. The addition of a 'guardrail_blocked' field indicates monitoring of AI safety features, but this is about monitoring existing security controls rather than adding new security documentation.
Diff
diff --git a/connect/latest/adminguide/monitor-ai-agents.md b/connect/latest/adminguide/monitor-ai-agents.md index 68db2460f..b832e063d 100644 --- a//connect/latest/adminguide/monitor-ai-agents.md +++ b//connect/latest/adminguide/monitor-ai-agents.md @@ -117,0 +118,2 @@ TRANSCRIPT_UTTERANCE | Logged when a message is sent by any participant in the c +TRANSCRIPT_ORCHESTRATION_MESSAGE | Logged for each step within an orchestration loop, including the initial customer message, bot text responses, reasoning, tool use requests, and tool results. Captures the full detail of multi-turn agentic reasoning performed by an Orchestration Connect AI agent. +TRANSCRIPT_ORCHESTRATION_ERROR | Logged when an error occurs during orchestration, such as exceeding the maximum number of orchestration iterations, system capacity constraints, or a general orchestration failure. @@ -150,0 +153,7 @@ utterance | The actual message text exchanged in the conversation. +orchestration_id | Unique identifier for the orchestration run. Corresponds to the initial customer message ID that triggered orchestration. +orchestration_iteration | The iteration number within the orchestration loop. +ai_agent_orchestration_use_case | The orchestrator use case, such as `CONNECT_AGENT_ASSISTANCE` or `CONNECT_SELF_SERVICE`. +participant | The participant role for the message, such as `CUSTOMER` or `BOT`. +values | JSON-serialized list of message values. Each entry has a type: `text` (with a text value), `tool_use` (with toolUseId, toolId, name, and arguments), `tool_result` (with toolUseId, toolId, name, values, and error), or `reasoning` (with a text value). +guardrail_blocked | Boolean indicating whether the response was blocked by an AI guardrail. +orchestration_error | JSON-serialized error details containing `errorMessage` and an optional `errorDetails` object (with `estimatedInputTokens` and `estimatedOutputTokens`). @@ -359,0 +369,133 @@ Manual Search Generation +#### OrchestrationMessage + +Customer message + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530173612, + "event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "participant": "CUSTOMER", + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa", + "session_message_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "values": "[{\"type\":\"text\",\"value\":\"How do I reset my password?\"}]" + } + + +Bot text response + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530174234, + "event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE", + "guardrail_blocked": false, + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 1, + "participant": "BOT", + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa", + "session_message_id": "mfff1234-5678-4eab-9333-112233445566", + "values": "[{\"type\":\"text\",\"value\":\"I can help you reset your password. Let me look up your account.\"}]" + } + + +Tool use + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530174500, + "event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 1, + "participant": "BOT", + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa", + "session_message_id": "maaa2222-3333-4bbb-cccc-ddddeeeeffff", + "values": "[{\"type\":\"tool_use\",\"toolUseId\":\"toolu_01ABC\",\"toolId\":\"ResetPassword\",\"name\":\"ResetPassword\",\"arguments\":{\"email\":\"[email protected]\"}}]" + } + + +Tool result + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530175100, + "event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 1, + "participant": "BOT", + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa", + "session_message_id": "mbbb3333-4444-5ccc-dddd-eeeeffff0000", + "values": "[{\"type\":\"tool_result\",\"toolUseId\":\"toolu_01ABC\",\"toolId\":\"ResetPassword\",\"name\":\"ResetPassword\",\"values\":[{\"type\":\"text\",\"value\":\"Password reset email sent successfully.\"}],\"error\":null}]" + } + + +Reasoning + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530175200, + "event_type": "TRANSCRIPT_ORCHESTRATION_MESSAGE", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 1, + "participant": "BOT", + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa", + "session_message_id": "mccc4444-5555-6ddd-eeee-ffff00001111", + "values": "[{\"type\":\"reasoning\",\"value\":\"The password reset was successful. I should inform the customer and ask if they need further help.\"}]" + } + + +#### OrchestrationError + +Maximum orchestration iterations exceeded + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530180000, + "event_type": "TRANSCRIPT_ORCHESTRATION_ERROR", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_error": "{\"errorMessage\":\"The orchestration exceeded the maximum number of iterations\"}", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 9, + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa" + } + + +System capacity constraints + + + { + "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab", + "ai_agent_orchestration_use_case": "CONNECT_AGENT_ASSISTANCE", + "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678", + "event_timestamp": 1729530180000, + "event_type": "TRANSCRIPT_ORCHESTRATION_ERROR", + "model_id": "us.anthropic.claude-4-5-sonnet-20250929-v1:0", + "orchestration_error": "{\"errorMessage\":\"System capacity is constrained. We are actively working on scaling system to prevent such failures.\",\"errorDetails\":{\"estimatedInputTokens\":50000,\"estimatedOutputTokens\":2048}}", + "orchestration_id": "m1234567-abcd-4ef0-9876-aabbccddeeff", + "orchestration_iteration": 3, + "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa" + } + +