list_events¶

BedrockAgentCore.Client.list_events(**kwargs)¶

Lists events in an AgentCore Memory resource based on specified criteria. We recommend using pagination to ensure that the operation returns quickly and successfully.

To use this operation, you must have the bedrock-agentcore:ListEvents permission.

Request Syntax

response = client.list_events(
    memoryId='string',
    sessionId='string',
    actorId='string',
    includePayloads=True|False,
    filter={
        'branch': {
            'name': 'string',
            'includeParentBranches': True|False
        },
        'eventMetadata': [
            {
                'left': {
                    'metadataKey': 'string'
                },
                'operator': 'EQUALS_TO'|'EXISTS'|'NOT_EXISTS',
                'right': {
                    'metadataValue': {
                        'stringValue': 'string'
                    }
                }
            },
        ]
    },
    maxResults=123,
    nextToken='string'
)

Parameters:

memoryId (string) –
[REQUIRED]

The identifier of the AgentCore Memory resource for which to list events.
sessionId (string) –
[REQUIRED]

The identifier of the session for which to list events.
actorId (string) –
[REQUIRED]

The identifier of the actor for which to list events.
includePayloads (boolean) – Specifies whether to include event payloads in the response. Set to true to include payloads, or false to exclude them.
filter (dict) –
Filter criteria to apply when listing events.
- branch (dict) –
  
  The branch filter criteria to apply when listing events.
  - name (string) – [REQUIRED]
    
    The name of the branch to filter by.
  - includeParentBranches (boolean) –
    
    Specifies whether to include parent branches in the results. Set to true to include parent branches, or false to exclude them.
- eventMetadata (list) –
  
  Event metadata filter criteria to apply when retrieving events.
  - (dict) –
    
    Filter expression for retrieving events based on metadata associated with an event.
    - left (dict) – [REQUIRED]
      
      Left operand of the event metadata filter expression.
      
      Note
      This is a Tagged Union structure. Only one of the following top level keys can be set: metadataKey.
      - metadataKey (string) –
        
        Key associated with the metadata in an event.
    - operator (string) – [REQUIRED]
      
      Operator applied to the event metadata filter expression.
    - right (dict) –
      
      Right operand of the event metadata filter expression.
      
      Note
      This is a Tagged Union structure. Only one of the following top level keys can be set: metadataValue.
      - metadataValue (dict) –
        
        Value associated with the key in eventMetadata.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue.
        
        stringValue (string) –
        
        Value associated with the eventMetadata key.
maxResults (integer) – The maximum number of results to return in a single call. The default value is 20.
nextToken (string) – The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

Return type:

dict

Returns:

Response Syntax

{
    'events': [
        {
            'memoryId': 'string',
            'actorId': 'string',
            'sessionId': 'string',
            'eventId': 'string',
            'eventTimestamp': datetime(2015, 1, 1),
            'payload': [
                {
                    'conversational': {
                        'content': {
                            'text': 'string'
                        },
                        'role': 'ASSISTANT'|'USER'|'TOOL'|'OTHER'
                    },
                    'blob': {...}|[...]|123|123.4|'string'|True|None
                },
            ],
            'branch': {
                'rootEventId': 'string',
                'name': 'string'
            },
            'metadata': {
                'string': {
                    'stringValue': 'string'
                }
            }
        },
    ],
    'nextToken': 'string'
}

Response Structure

(dict) –
- events (list) –
  
  The list of events that match the specified criteria.
  - (dict) –
    
    Contains information about an event in an AgentCore Memory resource.
    - memoryId (string) –
      
      The identifier of the AgentCore Memory resource containing the event.
    - actorId (string) –
      
      The identifier of the actor associated with the event.
    - sessionId (string) –
      
      The identifier of the session containing the event.
    - eventId (string) –
      
      The unique identifier of the event.
    - eventTimestamp (datetime) –
      
      The timestamp when the event occurred.
    - payload (list) –
      
      The content payload of the event.
      - (dict) –
        
        Contains the payload content for an event.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: conversational, blob. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        conversational (dict) –
        
        The conversational content of the payload.
        
        content (dict) –
        
        The content of the conversation message.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: text. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        text (string) –
        
        The text content of the memory item.
        
        role (string) –
        
        The role of the participant in the conversation (for example, “user” or “assistant”).
        
        blob (document) –
        
        The binary content of the payload.
    - branch (dict) –
      
      The branch information for the event.
      - rootEventId (string) –
        
        The identifier of the root event for this branch.
      - name (string) –
        
        The name of the branch.
    - metadata (dict) –
      
      Metadata associated with an event.
      - (string) –
        
        (dict) –
        
        Value associated with the eventMetadata key.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: stringValue. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        stringValue (string) –
        
        Value associated with the eventMetadata key.
- nextToken (string) –
  
  The token to use in a subsequent request to get the next set of results. This value is null when there are no more results to return.

Exceptions

BedrockAgentCore.Client.exceptions.ServiceQuotaExceededException
BedrockAgentCore.Client.exceptions.ThrottledException
BedrockAgentCore.Client.exceptions.ServiceException
BedrockAgentCore.Client.exceptions.AccessDeniedException
BedrockAgentCore.Client.exceptions.ValidationException
BedrockAgentCore.Client.exceptions.InvalidInputException
BedrockAgentCore.Client.exceptions.ResourceNotFoundException