AWSAWS Certified Generative AI Developer - Professional2026-103.1 Implement input and output safety controls
Place guardrail checks before content release
Completed by the knowledge check
Learning objective
Apply guardrails to requests and responses inline or with the ApplyGuardrail API.
Core idea
A guardrail protects the boundary where its result is enforced. Inline integration evaluates content as part of a Bedrock inference request. The independent ApplyGuardrail operation evaluates supplied content without invoking a foundation model. Both can use a configured Bedrock guardrail, but they place responsibility for sequencing and release in different places.
Choose inline enforcement when the model request is the boundary you need to protect. Choose independent assessment when you must reject input before retrieval, protect output from a separately hosted model, or evaluate an intermediate result. Combine them when the application has several distinct trust boundaries. Repeatedly checking the same text without defining those boundaries adds latency without explaining which risk it controls.
A successful HTTP call does not mean content is safe to release. Inspect the operation’s intervention signal, distinguish blocking from masking, and route assessment errors separately. A timeout means the assessment did not finish; it is neither approval nor a detected policy violation.
How it works
Attach an inline guardrail
For Converse, pass guardrailConfig with guardrailIdentifier and guardrailVersion. Setting trace: enabled provides assessment details. The request connects a particular policy configuration to a particular inference call; the application must attach that configuration on every intended route, including approved model fallbacks.
When a guardrail intervenes, Converse sets stopReason to guardrail_intervened and returns the configured blocked-content message in output. With tracing enabled, inspect trace.guardrail. ConverseStream carries the trace in its metadata event. Treat the blocked message as a policy outcome, rather than trying another model until an unrestricted answer appears.
For InvokeModel and InvokeModelWithResponseStream, attach the guardrail through the request headers X-Amzn-Bedrock-GuardrailIdentifier and X-Amzn-Bedrock-GuardrailVersion; the documented guardrail example also uses X-Amzn-Bedrock-GuardrailTrace for tracing. The native response body, or a streaming response chunk, carries amazon-bedrock-guardrailAction with INTERVENED or NONE. These names differ from Converse’s configuration and stop reason.
For selective input evaluation on the Invoke APIs, wrap text in matching <amazon-bedrock-guardrails-guardContent_TAG_SUFFIX> tags and set amazon-bedrock-guardrailConfig.tagSuffix in the request body to the same suffix. Replace TAG_SUFFIX with an application-generated random alphanumeric string of 1–20 characters for each request. The body configuration also carries the streaming processing mode described here. Converse uses guardContent blocks instead of these XML tags.
guardContent blocks let you identify message content for assessment, including contextual grounding sources and queries. Make wrapper construction an application responsibility. Do not accept a caller-selected list of protected fields: otherwise, the caller can omit the malicious portion from the intended assessment scope.
AWS’s Converse guidance contains both a general statement that adding guardContent restricts evaluation to wrapped blocks and an example in which a word filter still evaluates unwrapped text. Do not build a security guarantee around unwrapped text being ignored. Explicitly mark content intended for assessment and verify the behavior of every configured policy against the actual payload.
Inline tool use also has a separate boundary. AWS documents that guardrails do not evaluate toolSpec, toolResult, or toolUse.input. Assess extracted text separately when it needs content filtering, and retain schema and authorization checks for the complete tool action; see 2.1.10 and 2.3.7.
Assess content independently
ApplyGuardrail requires guardrailIdentifier, guardrailVersion, source, and content. Set source: INPUT for user input and source: OUTPUT for model output. content contains the blocks you want assessed. The operation applies the direction-specific settings configured in the guardrail; calling it twice with INPUT does not implement distinct input and output policies.
The API returns action, assessments, outputs, and usage. The intervention value is GUARDRAIL_INTERVENED; absence of intervention is NONE. Assessment details identify the policy responsible, such as a contextual grounding filter’s score and threshold or a sensitive-information match’s action.
Use those details to select the application outcome. A blocked response returns safe replacement messaging. Masked content can continue only through a route that accepts the transformation. Do not display the original after deciding that the replacement is acceptable. An empty outputs array with action: NONE means no intervention: release the content that was assessed. On GUARDRAIL_INTERVENED, release only outputs[].text through the appropriate replacement or masking route.
outputScope: FULL requests detected and non-detected assessment entries for debugging. Its full scope does not apply to word filters or regex matches in sensitive-information filters. Avoid interpreting missing entries as proof that every policy inspected every substring. Store only assessment evidence needed for review; assessment payloads themselves can contain sensitive material.
Enforce the sequence
An independent input gate can run before any knowledge retrieval. If action indicates a blocking intervention, stop before sending the request to the retriever or model. If the approved policy masks input, use the masked text consistently downstream. Preserve a correlation between the assessed content and the exact content subsequently consumed.
An independent output gate runs after generation and before publication. For grounding, include the actual source passages and question with the output being checked, using the documented grounding_source, query, and guard_content qualifiers. Checking an answer against different passages creates misleading evidence. The interpretation of grounding scores belongs to 3.1.6.
An independent input gate stops a blocked request before retrieval, and an output gate after generation decides which text is released.
Assessment exceptions require their own terminal behavior. An application policy can withhold the answer, retry within a deadline, or return an assessment-unavailable response. It must not silently label an unchecked answer as approved. Keep policy rejection separate from transport failure so retries do not bypass the intended safeguard.
Key distinctions and trade-offs
Inline integration reduces application sequencing around a Bedrock request. Independent assessment makes earlier or external boundaries possible, but the application owns the check, decision, and release sequence. Neither attaches protection automatically to unrelated inference paths.
Streaming changes what release means. For InvokeModelWithResponseStream, the documented default synchronous mode buffers response chunks and scans them before returning them. Asynchronous mode delivers chunks while checks run; a later intervention blocks subsequent chunks but cannot retract content already delivered. Enable it with amazon-bedrock-guardrailConfig.streamProcessingMode: ASYNCHRONOUS only when that exposure fits the product policy.
AWS does not support sensitive-information masking in asynchronous mode. Moreover, contextual relevance can be determined only after later response chunks arrive. Synchronous chunk checks therefore do not establish that the complete answer is relevant. If acceptance depends on a complete-response decision, buffer the complete answer before publication rather than equating streaming progress with approval.
Architecture / decision scenario
A support gateway serves Bedrock and an approved external model. It first calls ApplyGuardrail with source: INPUT, so a prohibited request stops before retrieval. Allowed requests retrieve authorized passages. The Bedrock route also includes inline guardrailConfig; the external route uses independent output assessment.
Before either answer is displayed, the gateway checks the generated text with source: OUTPUT. Blocking returns safe messaging; approved masking releases only transformed text. An assessment outage returns an unavailable result, with a bounded retry permitted before the request deadline.
The product prohibits disclosure of account identifiers, so it buffers final answers rather than enabling asynchronous streaming. Tests assert that every release uses the assessed bytes and that neither a model fallback nor a tool result creates an unprotected route.
Common exam traps
- Treating HTTP 200 as the guardrail decision.
- Mixing Converse
guardrail_intervened, InvokeINTERVENED, and ApplyGuardrailGUARDRAIL_INTERVENED, or attaching their configurations with the wrong field names. - Assuming
ApplyGuardrailalso performs model inference. - Checking input only after retrieval has already consumed it.
- Releasing original content after an anonymization decision.
- Expecting asynchronous streaming to retract delivered text or mask sensitive information.
What to remember
Select enforcement by trust boundary, not by service preference. Inline requests name the guardrail in guardrailConfig; independent checks name it in ApplyGuardrail and select INPUT or OUTPUT. Interpret intervention, replacement content, and assessment errors explicitly. Whole-answer acceptance requires control over whole-answer release.
Knowledge check
A gateway must stop prohibited input before knowledge retrieval, and it must assess answers from an externally hosted model before display. Which configuration covers both boundaries?
guardrailConfig on the Bedrock Converse call that generates the final answerApplyGuardrail with source: INPUT before retrieval and again on the external answerApplyGuardrail with source: INPUT before retrieval and source: OUTPUT on the external answerInvokeModel call made before retrievalApplyGuardrail assesses supplied content without invoking a model, so it can guard boundaries that no Bedrock inference call passes through: before retrieval, and after an external model. It applies the guardrail’s direction-specific settings, so checking an answer with INPUT does not apply the output policy.An output check with ApplyGuardrail returns action: GUARDRAIL_INTERVENED, and the assessment shows that a sensitive-information filter anonymized an account identifier. The product accepts masked answers. What does the display path release?
outputs , which carries the masked replacementoutputs[].text may be released, through the route that accepts the transformation. Accepting masking authorizes the masked text, never the original, and a fresh answer has not been assessed at all.An output guardrail check times out and returns no assessment. The product requires every answer to pass that check before display. What should the gateway do?
A product must never display an account identifier. To reduce latency, a team proposes guardrail streaming on InvokeModelWithResponseStream. Which processing mode fits the policy?
ASYNCHRONOUS , because a later intervention retracts chunks already deliveredASYNCHRONOUS , because the guardrail masks identifiers in each chunkA route moves from Converse to InvokeModel with the guardrail request headers. Its release check still looks for stopReason: guardrail_intervened, and blocked responses now pass the check. Which signal should it read?
action with the value GUARDRAIL_INTERVENEDtrace.guardrail with an intervention entryX-Amzn-Bedrock-GuardrailTrace header set to ENABLEDamazon-bedrock-guardrailAction with the value INTERVENEDConverse uses stopReason: guardrail_intervened , the Invoke APIs put amazon-bedrock-guardrailAction in the response body, and ApplyGuardrail returns action: GUARDRAIL_INTERVENED . A trace header requests detail; it does not report a decision.