2026/04/06 - Amazon Q Connect - 2 updated api methods
Changes Added optional originRequestId parameter to SendMessageRequest and ListSpans response in Amazon Q in Connect to support request tracing across service boundaries.
{'spans': {'originRequestId': 'string'}}
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',
'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'
}
},
]
},
],
'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'
}
},
]
},
],
'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'
}
},
],
'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
}
},
],
'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
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)
(dict) --
Message content value - can be text, tool invocation, or tool result
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
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)
(dict) --
Message content value - can be text, tool invocation, or tool result
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
systemInstructions (list) --
System prompt instructions
(dict) --
Message content value - can be text, tool invocation, or tool result
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
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
nextToken (string) --
Pagination token for retrieving additional results
{'originRequestId': 'string'}
Submits a message to the Amazon Q in Connect session.
See also: AWS API Documentation
Request Syntax
client.send_message(
assistantId='string',
sessionId='string',
type='TEXT'|'TOOL_USE_RESULT',
message={
'value': {
'text': {
'value': 'string',
'citations': [
{
'contentId': 'string',
'title': 'string',
'knowledgeBaseId': 'string',
'citationSpan': {
'beginOffsetInclusive': 123,
'endOffsetExclusive': 123
},
'sourceURL': 'string',
'referenceType': 'WEB_CRAWLER'|'KNOWLEDGE_BASE'|'BEDROCK_KB_S3'|'BEDROCK_KB_WEB'|'BEDROCK_KB_CONFLUENCE'|'BEDROCK_KB_SALESFORCE'|'BEDROCK_KB_SHAREPOINT'|'BEDROCK_KB_KENDRA'|'BEDROCK_KB_CUSTOM_DOCUMENT'|'BEDROCK_KB_SQL'
},
],
'aiGuardrailAssessment': {
'blocked': True|False
}
},
'toolUseResult': {
'toolUseId': 'string',
'toolName': 'string',
'toolResult': {...}|[...]|123|123.4|'string'|True|None,
'inputSchema': {...}|[...]|123|123.4|'string'|True|None
}
}
},
aiAgentId='string',
conversationContext={
'selfServiceConversationHistory': [
{
'turnNumber': 123,
'inputTranscript': 'string',
'botResponse': 'string',
'timestamp': datetime(2015, 1, 1)
},
]
},
configuration={
'generateFillerMessage': True|False,
'generateChunkedMessage': True|False
},
clientToken='string',
orchestratorUseCase='string',
metadata={
'string': 'string'
},
originRequestId='string'
)
string
[REQUIRED]
The identifier of the Amazon Q in Connect assistant.
string
[REQUIRED]
The identifier of the Amazon Q in Connect session.
string
[REQUIRED]
The message type.
dict
[REQUIRED]
The message data to submit to the Amazon Q in Connect session.
value (dict) -- [REQUIRED]
The message input value.
text (dict) --
The message data in text type.
value (string) --
The value of the message data in text type.
citations (list) --
The citations associated with the text message.
(dict) --
A citation that references source content.
contentId (string) --
The identifier of the content being cited.
title (string) --
The title of the cited content.
knowledgeBaseId (string) --
The identifier of the knowledge base containing the cited content.
citationSpan (dict) -- [REQUIRED]
Contains information about where the text with a citation begins and ends in the generated output.
beginOffsetInclusive (integer) --
Where the text with a citation starts in the generated output.
endOffsetExclusive (integer) --
Where the text with a citation ends in the generated output.
sourceURL (string) --
The source URL for the citation.
referenceType (string) -- [REQUIRED]
A type to define the KB origin of a cited content
aiGuardrailAssessment (dict) --
The AI Guardrail assessment for the text message.
blocked (boolean) -- [REQUIRED]
Indicates whether the AI Guardrail blocked the content.
toolUseResult (dict) --
The result of tool usage in the message.
toolUseId (string) -- [REQUIRED]
The identifier of the tool use instance.
toolName (string) -- [REQUIRED]
The name of the tool that was used.
toolResult (:ref:`document<document>`) -- [REQUIRED]
The result of the tool usage.
inputSchema (:ref:`document<document>`) --
The input schema for the tool use result.
string
The identifier of the AI Agent to use for processing the message.
dict
The conversation context before the Amazon Q in Connect session.
selfServiceConversationHistory (list) -- [REQUIRED]
The self service conversation history before the Amazon Q in Connect session.
(dict) --
The conversation history data to included in conversation context data before the Amazon Q in Connect session.
turnNumber (integer) --
The number of turn of the conversation history data.
inputTranscript (string) --
The input transcript of the conversation history data.
botResponse (string) --
The bot response of the conversation history data.
timestamp (datetime) --
The timestamp of the conversation history entry.
dict
The configuration of the SendMessage request.
generateFillerMessage (boolean) --
Generates a filler response when tool selection is QUESTION.
generateChunkedMessage (boolean) --
Configuration for generating chunked messages.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If not provided, the AWS SDK populates this field.For more information about idempotency, see Making retries safe with idempotent APIs.
This field is autopopulated if not provided.
string
The orchestrator use case for message processing.
dict
Additional metadata for the message.
(string) --
(string) --
string
Request identifier from the origin system, used for end-to-end tracing across spans.
dict
Response Syntax
{
'requestMessageId': 'string',
'configuration': {
'generateFillerMessage': True|False,
'generateChunkedMessage': True|False
},
'nextMessageToken': 'string'
}
Response Structure
(dict) --
requestMessageId (string) --
The identifier of the submitted message.
configuration (dict) --
The configuration of the SendMessage request.
generateFillerMessage (boolean) --
Generates a filler response when tool selection is QUESTION.
generateChunkedMessage (boolean) --
Configuration for generating chunked messages.
nextMessageToken (string) --
The token for the next message, used by GetNextMessage.