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'
                }
            }
        },
    ]
)

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.

Return type:

dict

Returns:

Response Syntax

{
    'usage': {
        'topicPolicyUnits': 123,
        'contentPolicyUnits': 123,
        'wordPolicyUnits': 123,
        'sensitiveInformationPolicyUnits': 123,
        'sensitiveInformationPolicyFreeUnits': 123,
        'contextualGroundingPolicyUnits': 123
    },
    'action': 'NONE'|'GUARDRAIL_INTERVENED',
    'outputs': [
        {
            'text': 'string'
        },
    ],
    'assessments': [
        {
            'topicPolicy': {
                'topics': [
                    {
                        'name': 'string',
                        'type': 'DENY',
                        'action': 'BLOCKED'
                    },
                ]
            },
            'contentPolicy': {
                'filters': [
                    {
                        'type': 'INSULTS'|'HATE'|'SEXUAL'|'VIOLENCE'|'MISCONDUCT'|'PROMPT_ATTACK',
                        'confidence': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'filterStrength': 'NONE'|'LOW'|'MEDIUM'|'HIGH',
                        'action': 'BLOCKED'
                    },
                ]
            },
            'wordPolicy': {
                'customWords': [
                    {
                        'match': 'string',
                        'action': 'BLOCKED'
                    },
                ],
                'managedWordLists': [
                    {
                        'match': 'string',
                        'type': 'PROFANITY',
                        'action': 'BLOCKED'
                    },
                ]
            },
            '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'
                    },
                ],
                'regexes': [
                    {
                        'name': 'string',
                        'match': 'string',
                        'regex': 'string',
                        'action': 'ANONYMIZED'|'BLOCKED'
                    },
                ]
            },
            'contextualGroundingPolicy': {
                'filters': [
                    {
                        'type': 'GROUNDING'|'RELEVANCE',
                        'threshold': 123.0,
                        'score': 123.0,
                        'action': 'BLOCKED'|'NONE'
                    },
                ]
            },
            'invocationMetrics': {
                'guardrailProcessingLatency': 123,
                'usage': {
                    'topicPolicyUnits': 123,
                    'contentPolicyUnits': 123,
                    'wordPolicyUnits': 123,
                    'sensitiveInformationPolicyUnits': 123,
                    'sensitiveInformationPolicyFreeUnits': 123,
                    'contextualGroundingPolicyUnits': 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.

  • action (string) –

    The action taken in the response from the guardrail.

  • 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.

      • 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.

      • 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.

        • 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.

      • 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.

        • 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.

      • 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.

      • 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.

        • 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

• BedrockRuntime.Client.exceptions.AccessDeniedException

• BedrockRuntime.Client.exceptions.ResourceNotFoundException

• BedrockRuntime.Client.exceptions.ThrottlingException

• BedrockRuntime.Client.exceptions.InternalServerException

• BedrockRuntime.Client.exceptions.ValidationException

• BedrockRuntime.Client.exceptions.ServiceQuotaExceededException