IoTSiteWise / Client / invoke_assistant

invoke_assistant#

IoTSiteWise.Client.invoke_assistant(**kwargs)#

Invokes SiteWise Assistant to start or continue a conversation.

See also: AWS API Documentation

Request Syntax

response = client.invoke_assistant(
    conversationId='string',
    message='string',
    enableTrace=True|False
)
Parameters:

  • conversationId (string) – The ID assigned to a conversation. IoT SiteWise automatically generates a unique ID for you, and this parameter is never required. However, if you prefer to have your own ID, you must specify it here in UUID format. If you specify your own ID, it must be globally unique.

  • message (string) –

    [REQUIRED]

    A text message sent to the SiteWise Assistant by the user.

  • enableTrace (boolean) – Specifies if to turn trace on or not. It is used to track the SiteWise Assistant’s reasoning, and data access process.

Return type:

dict

Returns:

The response of this operation contains an EventStream member. When iterated the EventStream will yield events based on the structure below, where only one of the top level keys will be present for any given event.

Response Syntax

{
    'body': EventStream({
        'trace': {
            'text': 'string'
        },
        'output': {
            'message': 'string',
            'citations': [
                {
                    'reference': {
                        'dataset': {
                            'datasetArn': 'string',
                            'source': {
                                'arn': 'string',
                                'location': {
                                    'uri': 'string'
                                }
                            }
                        }
                    },
                    'content': {
                        'text': 'string'
                    }
                },
            ]
        },
        'accessDeniedException': {
            'message': 'string'
        },
        'conflictingOperationException': {
            'message': 'string',
            'resourceId': 'string',
            'resourceArn': 'string'
        },
        'internalFailureException': {
            'message': 'string'
        },
        'invalidRequestException': {
            'message': 'string'
        },
        'limitExceededException': {
            'message': 'string'
        },
        'resourceNotFoundException': {
            'message': 'string'
        },
        'throttlingException': {
            'message': 'string'
        }
    }),
    'conversationId': 'string'
}

Response Structure

  • (dict) –

    • body (EventStream) –

      Contains the response, citation, and trace from the SiteWise Assistant.

      • trace (dict) –

        Contains tracing information of the SiteWise Assistant’s reasoning and data access.

        • text (string) –

          The cited text from the data source.

      • output (dict) –

        Contains the SiteWise Assistant’s response.

        • message (string) –

          The text message of the SiteWise Assistant’s response.

        • citations (list) –

          A list of citations, and related information for the SiteWise Assistant’s response.

          • (dict) –

            Contains text content to which the SiteWise Assistant refers to, and generate the final response. It also contains information about the source.

            • reference (dict) –

              Contains information about the data source.

              • dataset (dict) –

                Contains the dataset reference information.

                • datasetArn (string) –

                  The ARN of the dataset. The format is arn:${Partition}:iotsitewise:${Region}:${Account}:dataset/${DatasetId}.

                • source (dict) –

                  The data source for the dataset.

                  • arn (string) –

                    Contains the ARN of the dataset. If the source is Kendra, it’s the ARN of the Kendra index.

                  • location (dict) –

                    Contains the location information where the cited text is originally stored. For example, if the data source is Kendra, and the text synchronized is from an S3 bucket, then the location refers to an S3 object.

                    • uri (string) –

                      The URI of the location.

            • content (dict) –

              Contains the cited text from the data source.

              • text (string) –

                The cited text from the data source.

      • accessDeniedException (dict) –

        Access is denied.

        • message (string) –

      • conflictingOperationException (dict) –

        Your request has conflicting operations. This can occur if you’re trying to perform more than one operation on the same resource at the same time.

        • message (string) –

        • resourceId (string) –

          The ID of the resource that conflicts with this operation.

        • resourceArn (string) –

          The ARN of the resource that conflicts with this operation.

      • internalFailureException (dict) –

        IoT SiteWise can’t process your request right now. Try again later.

        • message (string) –

      • invalidRequestException (dict) –

        The request isn’t valid. This can occur if your request contains malformed JSON or unsupported characters. Check your request and try again.

        • message (string) –

      • limitExceededException (dict) –

        You’ve reached the limit for a resource. For example, this can occur if you’re trying to associate more than the allowed number of child assets or attempting to create more than the allowed number of properties for an asset model.

        For more information, see Quotas in the IoT SiteWise User Guide.

        • message (string) –

      • resourceNotFoundException (dict) –

        The requested resource can’t be found.

        • message (string) –

      • throttlingException (dict) –

        Your request exceeded a rate limit. For example, you might have exceeded the number of IoT SiteWise assets that can be created per second, the allowed number of messages per second, and so on.

        For more information, see Quotas in the IoT SiteWise User Guide.

        • message (string) –

    • conversationId (string) –

      The ID of the conversation, in UUID format. This ID uniquely identifies the conversation within IoT SiteWise.

Exceptions