BedrockRuntime / Client / apply_guardrail

apply_guardrail

BedrockRuntime.Client.apply_guardrail(**kwargs)

The action to apply a guardrail.

For troubleshooting some of the common errors you might encounter when using the ApplyGuardrail API, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide

See also: AWS API Documentation

Request Syntax

response = client.apply_guardrail(
    guardrailIdentifier='string',
    guardrailVersion='string',
    source='INPUT'|'OUTPUT',
    content=[
        {
            'text': {
                'text': 'string',
                'qualifiers': [
                    'grounding_source'|'query'|'guard_content',
                ]
            },
            'image': {
                'format': 'png'|'jpeg',
                'source': {
                    'bytes': b'bytes'
                }
            }
        },
    ],
    outputScope='INTERVENTIONS'|'FULL'
)
Parameters:

  • guardrailIdentifier (string) –

    [REQUIRED]

    The guardrail identifier used in the request to apply the guardrail.

  • guardrailVersion (string) –

    [REQUIRED]

    The guardrail version used in the request to apply the guardrail.

  • source (string) –

    [REQUIRED]

    The source of data used in the request to apply the guardrail.

  • content (list) –

    [REQUIRED]

    The content details used in the request to apply the guardrail.

    • (dict) –

      The content block to be evaluated by the guardrail.

      Note

      This is a Tagged Union structure. Only one of the following top level keys can be set: text, image.

      • text (dict) –

        Text within content block to be evaluated by the guardrail.

        • text (string) – [REQUIRED]

          The input text details to be evaluated by the guardrail.

        • qualifiers (list) –

          The qualifiers describing the text block.

          • (string) –

      • image (dict) –

        Image within guardrail content block to be evaluated by the guardrail.

        • format (string) – [REQUIRED]

          The format details for the file type of the image blocked by the guardrail.

        • source (dict) – [REQUIRED]

          The image source (image bytes) details of the image blocked by the guardrail.

          Note

          This is a Tagged Union structure. Only one of the following top level keys can be set: bytes.

          • bytes (bytes) –

            The bytes details of the guardrail image source. Object used in independent api.

  • outputScope (string) –

    Specifies the scope of the output that you get in the response. Set to FULL to return the entire output, including any detected and non-detected entries in the response for enhanced debugging.

    Note that the full output scope doesn’t apply to word filters or regex in sensitive information filters. It does apply to all other filtering policies, including sensitive information with filters that can detect personally identifiable information (PII).

Return type:

dict

Returns:

Response Syntax

{
    'usage': {
        'topicPolicyUnits': 123,
        'contentPolicyUnits': 123,
        'wordPolicyUnits': 123,
        'sensitiveInformationPolicyUnits': 123,
        'sensitiveInformationPolicyFreeUnits': 123,
        'contextualGroundingPolicyUnits': 123,
        'contentPolicyImageUnits': 123
    },
    'action': 'NONE'|'GUARDRAIL_INTERVENED',
    'actionReason': 'string',
    'outputs': [
        {
            'text': 'string'
        },
    ],
    'assessments': [
        {
            'topicPolicy': {
                'topics': [
                    {
                        'name': 'string',
                        'type': 'DENY',
                        'action': 'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ]
            },
            'contentPolicy': {
                'filters': [
                    {
                        'type': 'INSULTS'|'HATE'|'SEXUAL'|'VIOLENCE'|'MISCONDUCT'|'PROMPT_ATTACK',
                        'confidence': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'filterStrength': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'action': 'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ]
            },
            'wordPolicy': {
                'customWords': [
                    {
                        'match': 'string',
                        'action': 'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ],
                'managedWordLists': [
                    {
                        'match': 'string',
                        'type': 'PROFANITY',
                        'action': 'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ]
            },
            'sensitiveInformationPolicy': {
                'piiEntities': [
                    {
                        'match': 'string',
                        'type': 'ADDRESS'|'AGE'|'AWS_ACCESS_KEY'|'AWS_SECRET_KEY'|'CA_HEALTH_NUMBER'|'CA_SOCIAL_INSURANCE_NUMBER'|'CREDIT_DEBIT_CARD_CVV'|'CREDIT_DEBIT_CARD_EXPIRY'|'CREDIT_DEBIT_CARD_NUMBER'|'DRIVER_ID'|'EMAIL'|'INTERNATIONAL_BANK_ACCOUNT_NUMBER'|'IP_ADDRESS'|'LICENSE_PLATE'|'MAC_ADDRESS'|'NAME'|'PASSWORD'|'PHONE'|'PIN'|'SWIFT_CODE'|'UK_NATIONAL_HEALTH_SERVICE_NUMBER'|'UK_NATIONAL_INSURANCE_NUMBER'|'UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER'|'URL'|'USERNAME'|'US_BANK_ACCOUNT_NUMBER'|'US_BANK_ROUTING_NUMBER'|'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER'|'US_PASSPORT_NUMBER'|'US_SOCIAL_SECURITY_NUMBER'|'VEHICLE_IDENTIFICATION_NUMBER',
                        'action': 'ANONYMIZED'|'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ],
                'regexes': [
                    {
                        'name': 'string',
                        'match': 'string',
                        'regex': 'string',
                        'action': 'ANONYMIZED'|'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ]
            },
            'contextualGroundingPolicy': {
                'filters': [
                    {
                        'type': 'GROUNDING'|'RELEVANCE',
                        'threshold': 123.0,
                        'score': 123.0,
                        'action': 'BLOCKED'|'NONE',
                        'detected': True|False
                    },
                ]
            },
            'invocationMetrics': {
                'guardrailProcessingLatency': 123,
                'usage': {
                    'topicPolicyUnits': 123,
                    'contentPolicyUnits': 123,
                    'wordPolicyUnits': 123,
                    'sensitiveInformationPolicyUnits': 123,
                    'sensitiveInformationPolicyFreeUnits': 123,
                    'contextualGroundingPolicyUnits': 123,
                    'contentPolicyImageUnits': 123
                },
                'guardrailCoverage': {
                    'textCharacters': {
                        'guarded': 123,
                        'total': 123
                    },
                    'images': {
                        'guarded': 123,
                        'total': 123
                    }
                }
            }
        },
    ],
    'guardrailCoverage': {
        'textCharacters': {
            'guarded': 123,
            'total': 123
        },
        'images': {
            'guarded': 123,
            'total': 123
        }
    }
}

Response Structure

  • (dict) –

    • usage (dict) –

      The usage details in the response from the guardrail.

      • topicPolicyUnits (integer) –

        The topic policy units processed by the guardrail.

      • contentPolicyUnits (integer) –

        The content policy units processed by the guardrail.

      • wordPolicyUnits (integer) –

        The word policy units processed by the guardrail.

      • sensitiveInformationPolicyUnits (integer) –

        The sensitive information policy units processed by the guardrail.

      • sensitiveInformationPolicyFreeUnits (integer) –

        The sensitive information policy free units processed by the guardrail.

      • contextualGroundingPolicyUnits (integer) –

        The contextual grounding policy units processed by the guardrail.

      • contentPolicyImageUnits (integer) –

        The content policy image units processed by the guardrail.

    • action (string) –

      The action taken in the response from the guardrail.

    • actionReason (string) –

      The reason for the action taken when harmful content is detected.

    • outputs (list) –

      The output details in the response from the guardrail.

      • (dict) –

        The output content produced by the guardrail.

        • text (string) –

          The specific text for the output content produced by the guardrail.

    • assessments (list) –

      The assessment details in the response from the guardrail.

      • (dict) –

        A behavior assessment of the guardrail policies used in a call to the Converse API.

        • topicPolicy (dict) –

          The topic policy.

          • topics (list) –

            The topics in the assessment.

            • (dict) –

              Information about a topic guardrail.

              • name (string) –

                The name for the guardrail.

              • type (string) –

                The type behavior that the guardrail should perform when the model detects the topic.

              • action (string) –

                The action the guardrail should take when it intervenes on a topic.

              • detected (boolean) –

                Indicates whether topic content that breaches the guardrail configuration is detected.

        • contentPolicy (dict) –

          The content policy.

          • filters (list) –

            The content policy filters.

            • (dict) –

              The content filter for a guardrail.

              • type (string) –

                The guardrail type.

              • confidence (string) –

                The guardrail confidence.

              • filterStrength (string) –

                The filter strength setting for the guardrail content filter.

              • action (string) –

                The guardrail action.

              • detected (boolean) –

                Indicates whether content that breaches the guardrail configuration is detected.

        • wordPolicy (dict) –

          The word policy.

          • customWords (list) –

            Custom words in the assessment.

            • (dict) –

              A custom word configured in a guardrail.

              • match (string) –

                The match for the custom word.

              • action (string) –

                The action for the custom word.

              • detected (boolean) –

                Indicates whether custom word content that breaches the guardrail configuration is detected.

          • managedWordLists (list) –

            Managed word lists in the assessment.

            • (dict) –

              A managed word configured in a guardrail.

              • match (string) –

                The match for the managed word.

              • type (string) –

                The type for the managed word.

              • action (string) –

                The action for the managed word.

              • detected (boolean) –

                Indicates whether managed word content that breaches the guardrail configuration is detected.

        • sensitiveInformationPolicy (dict) –

          The sensitive information policy.

          • piiEntities (list) –

            The PII entities in the assessment.

            • (dict) –

              A Personally Identifiable Information (PII) entity configured in a guardrail.

              • match (string) –

                The PII entity filter match.

              • type (string) –

                The PII entity filter type.

              • action (string) –

                The PII entity filter action.

              • detected (boolean) –

                Indicates whether personally identifiable information (PII) that breaches the guardrail configuration is detected.

          • regexes (list) –

            The regex queries in the assessment.

            • (dict) –

              A Regex filter configured in a guardrail.

              • name (string) –

                The regex filter name.

              • match (string) –

                The regesx filter match.

              • regex (string) –

                The regex query.

              • action (string) –

                The region filter action.

              • detected (boolean) –

                Indicates whether custom regex entities that breach the guardrail configuration are detected.

        • contextualGroundingPolicy (dict) –

          The contextual grounding policy used for the guardrail assessment.

          • filters (list) –

            The filter details for the guardrails contextual grounding filter.

            • (dict) –

              The details for the guardrails contextual grounding filter.

              • type (string) –

                The contextual grounding filter type.

              • threshold (float) –

                The threshold used by contextual grounding filter to determine whether the content is grounded or not.

              • score (float) –

                The score generated by contextual grounding filter.

              • action (string) –

                The action performed by the guardrails contextual grounding filter.

              • detected (boolean) –

                Indicates whether content that fails the contextual grounding evaluation (grounding or relevance score less than the corresponding threshold) was detected.

        • invocationMetrics (dict) –

          The invocation metrics for the guardrail assessment.

          • guardrailProcessingLatency (integer) –

            The processing latency details for the guardrail invocation metrics.

          • usage (dict) –

            The usage details for the guardrail invocation metrics.

            • topicPolicyUnits (integer) –

              The topic policy units processed by the guardrail.

            • contentPolicyUnits (integer) –

              The content policy units processed by the guardrail.

            • wordPolicyUnits (integer) –

              The word policy units processed by the guardrail.

            • sensitiveInformationPolicyUnits (integer) –

              The sensitive information policy units processed by the guardrail.

            • sensitiveInformationPolicyFreeUnits (integer) –

              The sensitive information policy free units processed by the guardrail.

            • contextualGroundingPolicyUnits (integer) –

              The contextual grounding policy units processed by the guardrail.

            • contentPolicyImageUnits (integer) –

              The content policy image units processed by the guardrail.

          • guardrailCoverage (dict) –

            The coverage details for the guardrail invocation metrics.

            • textCharacters (dict) –

              The text characters of the guardrail coverage details.

              • guarded (integer) –

                The text characters that were guarded by the guardrail coverage.

              • total (integer) –

                The total text characters by the guardrail coverage.

            • images (dict) –

              The guardrail coverage for images (the number of images that guardrails guarded).

              • guarded (integer) –

                The count (integer) of images guardrails guarded.

              • total (integer) –

                Represents the total number of images (integer) that were in the request (guarded and unguarded).

    • guardrailCoverage (dict) –

      The guardrail coverage details in the apply guardrail response.

      • textCharacters (dict) –

        The text characters of the guardrail coverage details.

        • guarded (integer) –

          The text characters that were guarded by the guardrail coverage.

        • total (integer) –

          The total text characters by the guardrail coverage.

      • images (dict) –

        The guardrail coverage for images (the number of images that guardrails guarded).

        • guarded (integer) –

          The count (integer) of images guardrails guarded.

        • total (integer) –

          Represents the total number of images (integer) that were in the request (guarded and unguarded).

Exceptions