Agents for Amazon Bedrock Runtime

2025/02/27 - Agents for Amazon Bedrock Runtime - 14 new api methods

Changes  Introduces Sessions (preview) to enable stateful conversations in GenAI applications.

ListInvocations (new) Link ¶

Lists all invocations associated with a specific session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.list_invocations(
    maxResults=123,
    nextToken='string',
    sessionIdentifier='string'
)
type maxResults:

integer

param maxResults:

The maximum number of results to return in the response. If the total number of results is greater than this value, use the token returned in the response in the nextToken field when making another request to return the next batch of results.

type nextToken:

string

param nextToken:

If the total number of results is greater than the maxResults value provided in the request, enter the token returned in the nextToken field in the response in this field to return the next batch of results.

type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the session to list invocations for. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'invocationSummaries': [
        {
            'createdAt': datetime(2015, 1, 1),
            'invocationId': 'string',
            'sessionId': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • invocationSummaries (list) --

      A list of invocation summaries associated with the session.

      • (dict) --

        Contains details about an invocation in a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

        • createdAt (datetime) --

          The timestamp for when the invocation was created.

        • invocationId (string) --

          A unique identifier for the invocation in UUID format.

        • sessionId (string) --

          The unique identifier for the session associated with the invocation.

    • nextToken (string) --

      If the total number of results is greater than the maxResults value provided in the request, use this token when making another request in the nextToken field to return the next batch of results.

ListSessions (new) Link ¶

Lists all sessions in your Amazon Web Services account. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.list_sessions(
    maxResults=123,
    nextToken='string'
)
type maxResults:

integer

param maxResults:

The maximum number of results to return in the response. If the total number of results is greater than this value, use the token returned in the response in the nextToken field when making another request to return the next batch of results.

type nextToken:

string

param nextToken:

If the total number of results is greater than the maxResults value provided in the request, enter the token returned in the nextToken field in the response in this field to return the next batch of results.

rtype:

dict

returns:

Response Syntax

{
    'nextToken': 'string',
    'sessionSummaries': [
        {
            'createdAt': datetime(2015, 1, 1),
            'lastUpdatedAt': datetime(2015, 1, 1),
            'sessionArn': 'string',
            'sessionId': 'string',
            'sessionStatus': 'ACTIVE'|'EXPIRED'|'ENDED'
        },
    ]
}

Response Structure

  • (dict) --

    • nextToken (string) --

      If the total number of results is greater than the maxResults value provided in the request, use this token when making another request in the nextToken field to return the next batch of results.

    • sessionSummaries (list) --

      A list of summaries for each session in your Amazon Web Services account.

      • (dict) --

        Contains details about a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

        • createdAt (datetime) --

          The timestamp for when the session was created.

        • lastUpdatedAt (datetime) --

          The timestamp for when the session was last modified.

        • sessionArn (string) --

          The Amazon Resource Name (ARN) of the session.

        • sessionId (string) --

          The unique identifier for the session.

        • sessionStatus (string) --

          The current status of the session.

DeleteSession (new) Link ¶

Deletes a session that you ended. You can't delete a session with an ACTIVE status. To delete an active session, you must first end it with the EndSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.delete_session(
    sessionIdentifier='string'
)
type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the session to be deleted. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --

PutInvocationStep (new) Link ¶

Add an invocation step to an invocation in a session. An invocation step stores fine-grained state checkpoints, including text and images, for each interaction. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

Related APIs:

See also: AWS API Documentation

Request Syntax

client.put_invocation_step(
    invocationIdentifier='string',
    invocationStepId='string',
    invocationStepTime=datetime(2015, 1, 1),
    payload={
        'contentBlocks': [
            {
                'image': {
                    'format': 'png'|'jpeg'|'gif'|'webp',
                    'source': {
                        'bytes': b'bytes',
                        's3Location': {
                            'uri': 'string'
                        }
                    }
                },
                'text': 'string'
            },
        ]
    },
    sessionIdentifier='string'
)
type invocationIdentifier:

string

param invocationIdentifier:

[REQUIRED]

The unique identifier (in UUID format) of the invocation to add the invocation step to.

type invocationStepId:

string

param invocationStepId:

The unique identifier of the invocation step in UUID format.

type invocationStepTime:

datetime

param invocationStepTime:

[REQUIRED]

The timestamp for when the invocation step occurred.

type payload:

dict

param payload:

[REQUIRED]

The payload for the invocation step, including text and images for the interaction.

  • contentBlocks (list) --

    The content for the invocation step.

    • (dict) --

      A block of content that you pass to, or receive from, a Amazon Bedrock session in an invocation step. You pass the content to a session in the payLoad of the PutInvocationStep API operation. You retrieve the content with the GetInvocationStep API operation.

      For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

      • image (dict) --

        The image in the invocation step.

        • format (string) -- [REQUIRED]

          The format of the image.

        • source (dict) -- [REQUIRED]

          The source for the image.

          • bytes (bytes) --

            The raw image bytes for the image. If you use an Amazon Web Services SDK, you don't need to encode the image bytes in base64.

          • s3Location (dict) --

            The path to the Amazon S3 bucket where the image is stored.

            • uri (string) -- [REQUIRED]

              The path to the Amazon S3 bucket where the image is stored.

      • text (string) --

        The text in the invocation step.

type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the session to add the invocation step to. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'invocationStepId': 'string'
}

Response Structure

  • (dict) --

    • invocationStepId (string) --

      The unique identifier of the invocation step in UUID format.

GetSession (new) Link ¶

Retrieves details about a specific session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.get_session(
    sessionIdentifier='string'
)
type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

A unique identifier for the session to retrieve. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'encryptionKeyArn': 'string',
    'lastUpdatedAt': datetime(2015, 1, 1),
    'sessionArn': 'string',
    'sessionId': 'string',
    'sessionMetadata': {
        'string': 'string'
    },
    'sessionStatus': 'ACTIVE'|'EXPIRED'|'ENDED'
}

Response Structure

  • (dict) --

    • createdAt (datetime) --

      The timestamp for when the session was created.

    • encryptionKeyArn (string) --

      The Amazon Resource Name (ARN) of the Key Management Service key used to encrypt the session data. For more information, see Amazon Bedrock session encryption.

    • lastUpdatedAt (datetime) --

      The timestamp for when the session was last modified.

    • sessionArn (string) --

      The Amazon Resource Name (ARN) of the session.

    • sessionId (string) --

      The unique identifier for the session in UUID format.

    • sessionMetadata (dict) --

      A map of key-value pairs containing attributes persisted across the session.

      • (string) --

        • (string) --

    • sessionStatus (string) --

      The current status of the session.

TagResource (new) Link ¶

Associate tags with a resource. For more information, see Tagging resources in the Amazon Bedrock User Guide.

See also: AWS API Documentation

Request Syntax

client.tag_resource(
    resourceArn='string',
    tags={
        'string': 'string'
    }
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the resource to tag.

type tags:

dict

param tags:

[REQUIRED]

An object containing key-value pairs that define the tags to attach to the resource.

  • (string) --

    Key of a tag

    • (string) --

      Value of a tag

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --

EndSession (new) Link ¶

Ends the session. After you end a session, you can still access its content but you can’t add to it. To delete the session and it's content, you use the DeleteSession API operation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.end_session(
    sessionIdentifier='string'
)
type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the session to end. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'sessionArn': 'string',
    'sessionId': 'string',
    'sessionStatus': 'ACTIVE'|'EXPIRED'|'ENDED'
}

Response Structure

  • (dict) --

    • sessionArn (string) --

      The Amazon Resource Name (ARN) of the session you ended.

    • sessionId (string) --

      The unique identifier of the session you ended.

    • sessionStatus (string) --

      The current status of the session you ended.

ListTagsForResource (new) Link ¶

List all the tags for the resource you specify.

See also: AWS API Documentation

Request Syntax

client.list_tags_for_resource(
    resourceArn='string'
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the resource for which to list tags.

rtype:

dict

returns:

Response Syntax

{
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • tags (dict) --

      The key-value pairs for the tags associated with the resource.

      • (string) --

        Key of a tag

        • (string) --

          Value of a tag

GetInvocationStep (new) Link ¶

Retrieves the details of a specific invocation step within an invocation in a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.get_invocation_step(
    invocationIdentifier='string',
    invocationStepId='string',
    sessionIdentifier='string'
)
type invocationIdentifier:

string

param invocationIdentifier:

[REQUIRED]

The unique identifier for the invocation in UUID format.

type invocationStepId:

string

param invocationStepId:

[REQUIRED]

The unique identifier (in UUID format) for the specific invocation step to retrieve.

type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the invocation step's associated session. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'invocationStep': {
        'invocationId': 'string',
        'invocationStepId': 'string',
        'invocationStepTime': datetime(2015, 1, 1),
        'payload': {
            'contentBlocks': [
                {
                    'image': {
                        'format': 'png'|'jpeg'|'gif'|'webp',
                        'source': {
                            'bytes': b'bytes',
                            's3Location': {
                                'uri': 'string'
                            }
                        }
                    },
                    'text': 'string'
                },
            ]
        },
        'sessionId': 'string'
    }
}

Response Structure

  • (dict) --

    • invocationStep (dict) --

      The complete details of the requested invocation step.

      • invocationId (string) --

        The unique identifier (in UUID format) for the invocation that includes the invocation step.

      • invocationStepId (string) --

        The unique identifier (in UUID format) for the invocation step.

      • invocationStepTime (datetime) --

        The timestamp for when the invocation step was created.

      • payload (dict) --

        Payload content, such as text and images, for the invocation step.

        • contentBlocks (list) --

          The content for the invocation step.

          • (dict) --

            A block of content that you pass to, or receive from, a Amazon Bedrock session in an invocation step. You pass the content to a session in the payLoad of the PutInvocationStep API operation. You retrieve the content with the GetInvocationStep API operation.

            For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

            • image (dict) --

              The image in the invocation step.

              • format (string) --

                The format of the image.

              • source (dict) --

                The source for the image.

                • bytes (bytes) --

                  The raw image bytes for the image. If you use an Amazon Web Services SDK, you don't need to encode the image bytes in base64.

                • s3Location (dict) --

                  The path to the Amazon S3 bucket where the image is stored.

                  • uri (string) --

                    The path to the Amazon S3 bucket where the image is stored.

            • text (string) --

              The text in the invocation step.

      • sessionId (string) --

        The unique identifier of the session containing the invocation step.

CreateInvocation (new) Link ¶

Creates a new invocation within a session. An invocation groups the related invocation steps that store the content from a conversation. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

Related APIs

See also: AWS API Documentation

Request Syntax

client.create_invocation(
    description='string',
    invocationId='string',
    sessionIdentifier='string'
)
type description:

string

param description:

A description for the interactions in the invocation. For example, "User asking about weather in Seattle".

type invocationId:

string

param invocationId:

A unique identifier for the invocation in UUID format.

type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the associated session for the invocation. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'invocationId': 'string',
    'sessionId': 'string'
}

Response Structure

  • (dict) --

    • createdAt (datetime) --

      The timestamp for when the invocation was created.

    • invocationId (string) --

      The unique identifier for the invocation.

    • sessionId (string) --

      The unique identifier for the session associated with the invocation.

UpdateSession (new) Link ¶

Updates the metadata or encryption settings of a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.update_session(
    sessionIdentifier='string',
    sessionMetadata={
        'string': 'string'
    }
)
type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier of the session to modify. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

type sessionMetadata:

dict

param sessionMetadata:

A map of key-value pairs containing attributes to be persisted across the session. For example the user's ID, their language preference, and the type of device they are using.

  • (string) --

    • (string) --

rtype:

dict

returns:

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'lastUpdatedAt': datetime(2015, 1, 1),
    'sessionArn': 'string',
    'sessionId': 'string',
    'sessionStatus': 'ACTIVE'|'EXPIRED'|'ENDED'
}

Response Structure

  • (dict) --

    • createdAt (datetime) --

      The timestamp for when the session was created.

    • lastUpdatedAt (datetime) --

      The timestamp for when the session was last modified.

    • sessionArn (string) --

      The Amazon Resource Name (ARN) of the session that was updated.

    • sessionId (string) --

      The unique identifier of the session you updated.

    • sessionStatus (string) --

      The status of the session you updated.

UntagResource (new) Link ¶

Remove tags from a resource.

See also: AWS API Documentation

Request Syntax

client.untag_resource(
    resourceArn='string',
    tagKeys=[
        'string',
    ]
)
type resourceArn:

string

param resourceArn:

[REQUIRED]

The Amazon Resource Name (ARN) of the resource from which to remove tags.

type tagKeys:

list

param tagKeys:

[REQUIRED]

A list of keys of the tags to remove from the resource.

  • (string) --

    Key of a tag

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --

ListInvocationSteps (new) Link ¶

Lists all invocation steps associated with a session and optionally, an invocation within the session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

See also: AWS API Documentation

Request Syntax

client.list_invocation_steps(
    invocationIdentifier='string',
    maxResults=123,
    nextToken='string',
    sessionIdentifier='string'
)
type invocationIdentifier:

string

param invocationIdentifier:

The unique identifier (in UUID format) for the invocation to list invocation steps for.

type maxResults:

integer

param maxResults:

The maximum number of results to return in the response. If the total number of results is greater than this value, use the token returned in the response in the nextToken field when making another request to return the next batch of results.

type nextToken:

string

param nextToken:

If the total number of results is greater than the maxResults value provided in the request, enter the token returned in the nextToken field in the response in this field to return the next batch of results.

type sessionIdentifier:

string

param sessionIdentifier:

[REQUIRED]

The unique identifier for the session associated with the invocation steps. You can specify either the session's sessionId or its Amazon Resource Name (ARN).

rtype:

dict

returns:

Response Syntax

{
    'invocationStepSummaries': [
        {
            'invocationId': 'string',
            'invocationStepId': 'string',
            'invocationStepTime': datetime(2015, 1, 1),
            'sessionId': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • invocationStepSummaries (list) --

      A list of summaries for each invocation step associated with a session and if you specified it, an invocation within the session.

      • (dict) --

        Contains details about an invocation step within an invocation in a session. For more information about sessions, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

        • invocationId (string) --

          A unique identifier for the invocation in UUID format.

        • invocationStepId (string) --

          The unique identifier (in UUID format) for the invocation step.

        • invocationStepTime (datetime) --

          The timestamp for when the invocation step was created.

        • sessionId (string) --

          The unique identifier for the session associated with the invocation step.

    • nextToken (string) --

      If the total number of results is greater than the maxResults value provided in the request, use this token when making another request in the nextToken field to return the next batch of results.

CreateSession (new) Link ¶

Creates a session to temporarily store conversations for generative AI (GenAI) applications built with open-source frameworks such as LangGraph and LlamaIndex. Sessions enable you to save the state of conversations at checkpoints, with the added security and infrastructure of Amazon Web Services. For more information, see Store and retrieve conversation history and context with Amazon Bedrock sessions.

By default, Amazon Bedrock uses Amazon Web Services-managed keys for session encryption, including session metadata, or you can use your own KMS key. For more information, see Amazon Bedrock session encryption.

Related APIs:

See also: AWS API Documentation

Request Syntax

client.create_session(
    encryptionKeyArn='string',
    sessionMetadata={
        'string': 'string'
    },
    tags={
        'string': 'string'
    }
)
type encryptionKeyArn:

string

param encryptionKeyArn:

The Amazon Resource Name (ARN) of the KMS key to use to encrypt the session data. The user or role creating the session must have permission to use the key. For more information, see Amazon Bedrock session encryption.

type sessionMetadata:

dict

param sessionMetadata:

A map of key-value pairs containing attributes to be persisted across the session. For example, the user's ID, their language preference, and the type of device they are using.

  • (string) --

    • (string) --

type tags:

dict

param tags:

Specify the key-value pairs for the tags that you want to attach to the session.

  • (string) --

    Key of a tag

    • (string) --

      Value of a tag

rtype:

dict

returns:

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'sessionArn': 'string',
    'sessionId': 'string',
    'sessionStatus': 'ACTIVE'|'EXPIRED'|'ENDED'
}

Response Structure

  • (dict) --

    • createdAt (datetime) --

      The timestamp for when the session was created.

    • sessionArn (string) --

      The Amazon Resource Name (ARN) of the created session.

    • sessionId (string) --

      The unique identifier for the session.

    • sessionStatus (string) --

      The current status of the session.