2026/05/22 - Amazon Q Connect - 1 updated api methods
Changes Added guardrail assessment results to inference spans in the ListSpans API. You can now see which AI Guardrail policies were evaluated, whether content was blocked or masked, and per-policy details for each Bedrock Converse call
{'spans': {'attributes': {'guardrailAssessments': [{'action': 'NONE | BLOCKED '
'| MASKED',
'guardrailId': 'string',
'guardrailName': 'string',
'policies': [{'action': 'NONE '
'| '
'BLOCKED '
'| '
'MASKED',
'details': 'string',
'policyType': 'CONTENT_FILTER '
'| '
'TOPIC '
'| '
'WORD '
'| '
'SENSITIVE_INFORMATION_PII '
'| '
'SENSITIVE_INFORMATION_REGEX '
'| '
'CONTEXTUAL_GROUNDING'}],
'source': 'INPUT | '
'OUTPUT'}]}}}
Retrieves AI agent execution traces for a session, providing granular visibility into agent orchestration flows, LLM interactions, and tool invocations.
See also: AWS API Documentation
Request Syntax
client.list_spans(
assistantId='string',
sessionId='string',
nextToken='string',
maxResults=123
)
string
[REQUIRED]
UUID or ARN of the Connect AI Assistant resource
string
[REQUIRED]
UUID or ARN of the Connect AI Session resource
string
Pagination token for retrieving the next page of results
integer
Maximum number of spans to return per page
dict
Response Syntax
{
'spans': [
{
'spanId': 'string',
'assistantId': 'string',
'sessionId': 'string',
'parentSpanId': 'string',
'spanName': 'string',
'spanType': 'CLIENT'|'SERVER'|'INTERNAL',
'startTimestamp': datetime(2015, 1, 1),
'endTimestamp': datetime(2015, 1, 1),
'status': 'OK'|'ERROR'|'TIMEOUT',
'statusDescription': 'string',
'requestId': 'string',
'originRequestId': 'string',
'attributes': {
'operationName': 'string',
'providerName': 'string',
'errorType': 'string',
'agentId': 'string',
'instanceArn': 'string',
'contactId': 'string',
'initialContactId': 'string',
'sessionName': 'string',
'aiAgentArn': 'string',
'aiAgentType': 'MANUAL_SEARCH'|'ANSWER_RECOMMENDATION'|'SELF_SERVICE'|'EMAIL_RESPONSE'|'EMAIL_OVERVIEW'|'EMAIL_GENERATIVE_ANSWER'|'ORCHESTRATION'|'NOTE_TAKING'|'CASE_SUMMARIZATION',
'aiAgentName': 'string',
'aiAgentId': 'string',
'aiAgentVersion': 123,
'aiAgentInvoker': 'string',
'aiAgentOrchestratorUseCase': 'string',
'requestModel': 'string',
'requestMaxTokens': 123,
'temperature': ...,
'topP': ...,
'responseModel': 'string',
'responseFinishReasons': [
'string',
],
'usageInputTokens': 123,
'usageOutputTokens': 123,
'usageTotalTokens': 123,
'cacheReadInputTokens': 123,
'cacheWriteInputTokens': 123,
'inputMessages': [
{
'messageId': 'string',
'participant': 'CUSTOMER'|'AGENT'|'BOT',
'timestamp': datetime(2015, 1, 1),
'values': [
{
'text': {
'value': 'string',
'citations': [
{
'contentId': 'string',
'title': 'string',
'knowledgeBaseId': 'string',
'knowledgeBaseArn': 'string'
},
],
'aiGuardrailAssessment': {
'blocked': True|False
}
},
'toolUse': {
'toolUseId': 'string',
'name': 'string',
'arguments': {...}|[...]|123|123.4|'string'|True|None
},
'toolResult': {
'toolUseId': 'string',
'values': {'... recursive ...'},
'error': 'string'
},
'reasoning': {
'value': 'string'
}
},
]
},
],
'outputMessages': [
{
'messageId': 'string',
'participant': 'CUSTOMER'|'AGENT'|'BOT',
'timestamp': datetime(2015, 1, 1),
'values': [
{
'text': {
'value': 'string',
'citations': [
{
'contentId': 'string',
'title': 'string',
'knowledgeBaseId': 'string',
'knowledgeBaseArn': 'string'
},
],
'aiGuardrailAssessment': {
'blocked': True|False
}
},
'toolUse': {
'toolUseId': 'string',
'name': 'string',
'arguments': {...}|[...]|123|123.4|'string'|True|None
},
'toolResult': {
'toolUseId': 'string',
'values': {'... recursive ...'},
'error': 'string'
},
'reasoning': {
'value': 'string'
}
},
]
},
],
'systemInstructions': [
{
'text': {
'value': 'string',
'citations': [
{
'contentId': 'string',
'title': 'string',
'knowledgeBaseId': 'string',
'knowledgeBaseArn': 'string'
},
],
'aiGuardrailAssessment': {
'blocked': True|False
}
},
'toolUse': {
'toolUseId': 'string',
'name': 'string',
'arguments': {...}|[...]|123|123.4|'string'|True|None
},
'toolResult': {
'toolUseId': 'string',
'values': {'... recursive ...'},
'error': 'string'
},
'reasoning': {
'value': 'string'
}
},
],
'promptArn': 'string',
'promptId': 'string',
'promptType': 'ANSWER_GENERATION'|'INTENT_LABELING_GENERATION'|'QUERY_REFORMULATION'|'SELF_SERVICE_PRE_PROCESSING'|'SELF_SERVICE_ANSWER_GENERATION'|'EMAIL_RESPONSE'|'EMAIL_OVERVIEW'|'EMAIL_GENERATIVE_ANSWER'|'EMAIL_QUERY_REFORMULATION'|'ORCHESTRATION'|'NOTE_TAKING'|'CASE_SUMMARIZATION',
'promptName': 'string',
'promptVersion': 123,
'timeToFirstTokenMs': 123,
'guardrailAssessments': [
{
'guardrailId': 'string',
'guardrailName': 'string',
'source': 'INPUT'|'OUTPUT',
'action': 'NONE'|'BLOCKED'|'MASKED',
'policies': [
{
'policyType': 'CONTENT_FILTER'|'TOPIC'|'WORD'|'SENSITIVE_INFORMATION_PII'|'SENSITIVE_INFORMATION_REGEX'|'CONTEXTUAL_GROUNDING',
'action': 'NONE'|'BLOCKED'|'MASKED',
'details': 'string'
},
]
},
]
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
spans (list) --
Array of span objects for the session
(dict) --
A span represents a unit of work during AI agent execution, capturing timing, status, and contextual attributes.
spanId (string) --
Unique span identifier
assistantId (string) --
UUID of the Connect AI Assistant resource
sessionId (string) --
UUID of the Connect AI Session resource
parentSpanId (string) --
Parent span identifier for hierarchy. Null for root spans.
spanName (string) --
Service-defined operation name
spanType (string) --
Operation relationship type
startTimestamp (datetime) --
Operation start time in milliseconds since epoch
endTimestamp (datetime) --
Operation end time in milliseconds since epoch
status (string) --
Span completion status
statusDescription (string) --
Human-readable error description when status is ERROR or TIMEOUT
requestId (string) --
The service request ID that initiated the operation
originRequestId (string) --
The origin request identifier for end-to-end tracing.
attributes (dict) --
Span-specific contextual attributes
operationName (string) --
Action being performed
providerName (string) --
Model provider identifier (e.g., aws.bedrock)
errorType (string) --
Error classification if span failed (e.g., throttle, timeout)
agentId (string) --
Amazon Connect agent ID
instanceArn (string) --
Amazon Connect instance ARN
contactId (string) --
Amazon Connect contact identifier
initialContactId (string) --
Amazon Connect contact identifier
sessionName (string) --
Session name
aiAgentArn (string) --
AI agent ARN
aiAgentType (string) --
AI agent type
aiAgentName (string) --
AI agent name
aiAgentId (string) --
AI agent identifier
aiAgentVersion (integer) --
AI agent version number
aiAgentInvoker (string) --
Entity that invoked the AI agent
aiAgentOrchestratorUseCase (string) --
AI agent orchestrator use case
requestModel (string) --
LLM model ID for request (e.g., anthropic.claude-3-sonnet)
requestMaxTokens (integer) --
Maximum tokens configured for generation
temperature (float) --
Sampling temperature for generation
topP (float) --
Top-p sampling parameter for generation
responseModel (string) --
Actual model used for response (usually matches requestModel)
responseFinishReasons (list) --
Generation termination reasons (e.g., stop, max_tokens)
(string) --
usageInputTokens (integer) --
Number of input tokens in prompt
usageOutputTokens (integer) --
Number of output tokens in response
usageTotalTokens (integer) --
Total tokens consumed (input + output)
cacheReadInputTokens (integer) --
Number of input tokens that were retrieved from cache
cacheWriteInputTokens (integer) --
Number of input tokens that were written to cache in this request
inputMessages (list) --
Input message collection sent to LLM
(dict) --
A message in the conversation history with participant role and content values
messageId (string) --
Unique message identifier
participant (string) --
Message source role
timestamp (datetime) --
Message timestamp
values (list) --
Message content values (text, tool use, tool result, reasoning)
(dict) --
Message content value - can be text, tool invocation, tool result, or reasoning
text (dict) --
Text message content
value (string) --
String content of the message text
citations (list) --
The citations associated with the span text.
(dict) --
A citation that spans a specific range of text.
contentId (string) --
The identifier of the content being cited in the span.
title (string) --
The title of the content being cited in the span.
knowledgeBaseId (string) --
The identifier of the knowledge base containing the cited content.
knowledgeBaseArn (string) --
The Amazon Resource Name (ARN) of the knowledge base containing the cited content.
aiGuardrailAssessment (dict) --
The AI Guardrail assessment for the span text.
blocked (boolean) --
Indicates whether the AI Guardrail blocked the content.
toolUse (dict) --
Tool invocation message content
toolUseId (string) --
Unique ID for this tool invocation
name (string) --
The tool name
arguments (:ref:`document<document>`) --
The tool input arguments
toolResult (dict) --
Tool result message content
toolUseId (string) --
Relates this result back to the tool invocation
values (list) --
The tool results
error (string) --
The tool invocation error if failed
reasoning (dict) --
Model reasoning and it's internal decision making process
value (string) --
The reasoning text content
outputMessages (list) --
Output message collection received from LLM
(dict) --
A message in the conversation history with participant role and content values
messageId (string) --
Unique message identifier
participant (string) --
Message source role
timestamp (datetime) --
Message timestamp
values (list) --
Message content values (text, tool use, tool result, reasoning)
(dict) --
Message content value - can be text, tool invocation, tool result, or reasoning
text (dict) --
Text message content
value (string) --
String content of the message text
citations (list) --
The citations associated with the span text.
(dict) --
A citation that spans a specific range of text.
contentId (string) --
The identifier of the content being cited in the span.
title (string) --
The title of the content being cited in the span.
knowledgeBaseId (string) --
The identifier of the knowledge base containing the cited content.
knowledgeBaseArn (string) --
The Amazon Resource Name (ARN) of the knowledge base containing the cited content.
aiGuardrailAssessment (dict) --
The AI Guardrail assessment for the span text.
blocked (boolean) --
Indicates whether the AI Guardrail blocked the content.
toolUse (dict) --
Tool invocation message content
toolUseId (string) --
Unique ID for this tool invocation
name (string) --
The tool name
arguments (:ref:`document<document>`) --
The tool input arguments
toolResult (dict) --
Tool result message content
toolUseId (string) --
Relates this result back to the tool invocation
values (list) --
The tool results
error (string) --
The tool invocation error if failed
reasoning (dict) --
Model reasoning and it's internal decision making process
value (string) --
The reasoning text content
systemInstructions (list) --
System prompt instructions
(dict) --
Message content value - can be text, tool invocation, tool result, or reasoning
text (dict) --
Text message content
value (string) --
String content of the message text
citations (list) --
The citations associated with the span text.
(dict) --
A citation that spans a specific range of text.
contentId (string) --
The identifier of the content being cited in the span.
title (string) --
The title of the content being cited in the span.
knowledgeBaseId (string) --
The identifier of the knowledge base containing the cited content.
knowledgeBaseArn (string) --
The Amazon Resource Name (ARN) of the knowledge base containing the cited content.
aiGuardrailAssessment (dict) --
The AI Guardrail assessment for the span text.
blocked (boolean) --
Indicates whether the AI Guardrail blocked the content.
toolUse (dict) --
Tool invocation message content
toolUseId (string) --
Unique ID for this tool invocation
name (string) --
The tool name
arguments (:ref:`document<document>`) --
The tool input arguments
toolResult (dict) --
Tool result message content
toolUseId (string) --
Relates this result back to the tool invocation
values (list) --
The tool results
error (string) --
The tool invocation error if failed
reasoning (dict) --
Model reasoning and it's internal decision making process
value (string) --
The reasoning text content
promptArn (string) --
AI prompt ARN
promptId (string) --
AI prompt identifier
promptType (string) --
AI prompt type
promptName (string) --
AI prompt name
promptVersion (integer) --
AI prompt version number
timeToFirstTokenMs (integer) --
Time to first token in milliseconds, measured from when Amazon Bedrock was invoked to when the first token was returned
guardrailAssessments (list) --
Guardrail assessments for the inference span. Absent on other span types and when no AI Guardrail is attached to the AI Agent.
(dict) --
Result of a single guardrail assessment, covering either the input (customer/user message) or the output (LLM response) of a Bedrock Converse call.
guardrailId (string) --
Unique AI Guardrail identifier.
guardrailName (string) --
Customer-defined display name of the AI Guardrail resource.
source (string) --
Content source the guardrail was evaluated against.
action (string) --
Outcome of the guardrail assessment.
policies (list) --
Per-policy assessment results. Absent or empty when action is NONE.
(dict) --
Per-policy guardrail assessment result. Captures which policy triggered, its outcome, and a policy-specific detail string.
policyType (string) --
The type of guardrail policy that was evaluated.
action (string) --
Outcome of this specific policy.
details (string) --
Policy-specific detail.
nextToken (string) --
Pagination token for retrieving additional results