AIP-C01 Responsible AI: Transparency, Fairness Evaluations and Policy-Compliant GenAI on AWS

You get a step-by-step reasoning trace from an Amazon Bedrock agent by setting enableTrace to true on the InvokeAgent request. (Amazon Bedrock Agents, now labelled Agents Classic, is no longer open to new customers; tracing still works for existing agents, and AWS points new agent builds at Amazon Bedrock AgentCore and its built-in observability.) Trace is switched on per request, needs no instrumentation code, and arrives in the same response stream as the answer: alongside the answer chunk (one chunk for the whole answer by default, or many when the final response is streamed), the stream carries TracePart events that record what the agent did at each step of orchestration.

What a trace contains

A trace is evidence from inside the agent, which is what sets it apart from the other observability tools. AWS CloudTrail is an API audit log: it captures who made a call and when, at the boundary of the service. AWS X-Ray captures timing and dependencies of the code it instruments. Neither sees the orchestration decisions the agent makes between the request and the answer. And any account the model writes about its own steps is self-report, which is only as accurate as the model's narration.

Multi-agent collaboration: attributing each step

With a supervisor agent routing to collaborator agents, every trace part also carries collaboratorName and callerChain. For a single agent, callerChain holds only that agent's alias ARN; with collaboration it lists every agent that forwarded the request. Those two fields are how you attribute a rationale to the agent that produced it. Identifiers that describe the conversation as a whole (the session ID) or a single model call (an invocation log record) cannot tell you which agent in the chain made a decision.

Keeping traces safe and long-lived

Because the trace includes prompts, it must never be forwarded to a browser and "hidden" by client-side code: anything sent to the client is exposed. The backend receives the stream, extracts only what users may see, and separately persists the full trace events to controlled storage, for example a CloudWatch Logs log group encrypted with an AWS KMS key, with the retention period the audit policy requires and IAM access limited to the audit team. Disabling trace in production to protect prompts destroys the very evidence auditors need.

Live progress without exposing internals

Trace parts stream as orchestration progresses, so a backend can show progress while a step runs. Map each step's invocationInput (which action group or knowledge base is starting) to a pre-approved status line such as "Looking up your booking", rather than displaying the raw rationale. The agent's streamFinalResponse setting only streams the final answer text as it is generated; it says nothing while an action group or knowledge base call is in progress.

A user-facing explanation should be a deliberate, validated output that describes the real basis of the result, not the model's raw reasoning. Two failure modes drive the design: raw reasoning can contain speculation and unvetted wording, and a model asked to explain itself can describe steps it never took.

For a decision such as an insurance claim triage result, ask the model for structured output that includes a dedicated explanation field (required by a JSON schema), validate it in code (allowed factors, no unapproved wording), and display only that field, while the full reasoning goes to an internal log. For an agent, the most faithful explanation is built from the trace: the backend collects the invocation inputs and observations of the current turn and lets the model only phrase those facts in friendly language. Keep in mind what each tool controls: temperature controls how variable the wording is, not whether it is true; a contextual grounding check measures whether claims are supported by reference passages, not which actions ran; and a guardrail assessment records why content was filtered, which is not the basis of a business decision.

Source attribution means each claim in an answer links to the specific retrieved passage that supports it, using data your application recorded rather than sources the model writes itself. Model-written source lists are where fabricated citations come from.

Amazon Bedrock Knowledge Bases citations

The RetrieveAndGenerate response includes a citations array. Each citation has a generatedResponsePart (the text and its span within the answer) and retrievedReferences (the chunk content, its location such as the S3 URI, and its metadata). Rendering these as footnotes on the matching span gives evidence for each part of the answer with no extra calls. A separate Retrieve call shows what was found but loses the mapping between text spans and sources, and a contextual grounding score is a number, not a source.

Linking to the original document, not the bucket

If documents are synced from another system (a content management system, a ticketing tool) into a private S3 bucket, the S3 URI is useless to users and must not be made accessible. For an S3 data source, add a <file>.metadata.json sidecar with custom metadataAttributes, such as the original page URL. After ingestion, those attributes come back in retrievedReferences[].metadata on every citation, so the interface links to the original page, where the source system applies the user's own permissions. The principle is to keep the source system as the place that decides who may open a document: anything that hands users direct access to the synced copy in S3 sidesteps those permissions, and any link the model writes from memory is a guess rather than a record.

Custom RAG pipelines

When you retrieve with your own code (for example from Amazon OpenSearch Service or Aurora PostgreSQL with pgvector) and generate with the Converse API, build attribution yourself: give each retrieved passage an identifier in the prompt, require structured output that maps each claim to passage identifiers, and validate in code that every identifier belongs to this request's retrieval set before turning it into a link from stored metadata. The model can still cite the wrong passage within the set, but it can no longer cite a document that was never retrieved. Dumping all retrieved passages beneath the answer shows evidence but does not attribute any claim.

Confidence in an FM answer should be measured from observable signals, published to Amazon CloudWatch as custom metrics, and used to decide what the user sees. A model's statement about its own confidence ("I am 90% sure") is self-report and is not a measurement.

Signals that measure uncertainty

Default Amazon Bedrock and guardrail metrics (invocations, latency, errors, interventions) are operational; they say nothing about how well each answer is grounded. To trend grounding over time, set the contextual grounding check to detect (action none) or read the assessment even when blocking is on, and publish each grounding and relevance score as a custom metric. A dashboard then shows the trend, and an alarm on a low percentile or on the share of answers below a threshold flags degradation.

Publishing at volume: the embedded metric format

From a Lambda function handling thousands of requests a minute, write metrics with the CloudWatch embedded metric format (EMF): structured log lines that CloudWatch turns into metrics with no PutMetricData calls. Choose dimensions with few values (use case, model ID, prompt version) so graphs and alarms aggregate cleanly, and write high-cardinality values such as the request ID as a property: it lands in CloudWatch Logs, where Logs Insights finds the exact request behind a low score, without creating a separate metric per request.

Calibrating thresholds

A confidence threshold picked by intuition means nothing. If a "verified" label must meet a stated accuracy target for labelled answers, run the scoring on a labelled question set, measure accuracy in each score band (publishing per-band accuracy as a metric), and set the threshold at the lowest band that meets the target. A new model changes how scores relate to correctness, so repeat the calibration for each model version. A threshold means something only when it is tied to measured correctness; any change that moves scores or alerts without that labelled comparison leaves the label's promise unverified.

Streaming caveat: with streaming output, the contextual grounding check evaluates the response in chunks, and AWS notes that relevance is judged per chunk, so an irrelevant response can reach the user before it is flagged. Where the disclosure must come before the user reads the answer, evaluate the complete response first.

Telling the user when the evidence is weak

Transparency includes saying "I could not find support for this". Three patterns cover most policies:

• Abstain before generating. Compare the best retrieval score with the policy's threshold in code; if nothing passes, skip generation, return an honest no-support message with a route to a person who can help, and count the abstention as a metric. The decision rests on a measured threshold applied in code; anything that still produces an answer without supporting passages, or that leaves the decision to the model, gives up that guarantee.
• Explain a guardrail block. A guardrail has two configurable messages: one for blocked prompts (blockedInputMessaging) and one for blocked responses (blockedOutputsMessaging). The contextual grounding check evaluates the response, so the response message is the one users see when it intervenes; rewriting it to say the answer could not be confirmed and where to go instead is a configuration change, not a code change.
• Tiered disclosure. Block mode is a single cut-off: the answer is returned or replaced. A policy with several tiers (withhold below one score, show with a warning between two scores, show normally above) needs the numeric score, so set the check to detect, read the score from the guardrail assessment, and apply the thresholds in the application. Any arrangement built only from block decisions yields pass or replace, never "show with a warning".

A counterfactual fairness test sends prompts that are identical except for one demographic signal (a name, dialect, gender or background) and compares the business outcome and tone across the variants. If only that signal changed, any systematic difference is attributable to it. This is the evidence a responsible AI board needs before launch; toxicity sampling of past transcripts, general-knowledge benchmarks and jailbreak suites measure different properties.

Rules for a test whose results you can defend

• Vary one thing only. Income, tenure, postcode and every other field stay identical within each pair. Making each variant "realistic" for its group adds confounders.
• Use several signals per group. Many names associated with each group, so one name's particular associations do not drive the result.
• Use synthetic cases. Real applicants' records with a group inferred from the name are not counterfactual pairs, and inferring protected attributes may break privacy policy.
• Control sampling noise. Generate several responses per prompt and compare score distributions (with a significance test), not single generations.
• Control version drift. Run both halves of each pair against the same prompt version and model version in one test run, and score them with the same judge. Different days, prompt updates or different judges are confounds.

Measuring is different from mitigating. Masking names with a sensitive information filter or blocking demographic words with a denied topic may reduce one route to bias, but it measures nothing, and removing the signal from a counterfactual test defeats the test.

Fairness monitoring in production publishes outcome metrics per group as CloudWatch custom metrics (a dimension for the group or cohort) and alarms on the disparity between groups with metric math. An overall average, or an anomaly band on it, can stay flat while one group is treated worse.

Probe-based monitoring

When policy forbids storing or inferring real users' protected attributes, measure with synthetic probes: a fixed set of counterfactual cases run through the production prompt and model on a schedule (for example a Lambda function invoked by Amazon EventBridge Scheduler), publishing per-group results. Add the prompt version and model ID as dimensions so that a change in disparity can be correlated with a deployment. Per-user identifiers as dimensions create high-cardinality metrics that answer nothing.

Turning a fairness rule into an alarm

Publishing counts rather than pre-computed rates matters when some groups have few samples in a period: rates computed from summed counts are weighted correctly, while averaging small-sample rates is not. A per-group alarm against that group's own history detects drift, not disparity; an average across all groups hides the gap.

Systematic A/B testing of prompt variants (for example a variant written to reduce stereotyped language) needs three things: variants that cannot change during the test, a controlled split of traffic, and results recorded per variant. Amazon Bedrock Prompt Management and Amazon Bedrock Flows (formerly Prompt Flows) provide the first two as configuration.

Prompt Management versions

A prompt has a working draft that authors edit, and versions: immutable snapshots of the template and its configuration. A version can be invoked directly by passing its ARN as the modelId in Converse or InvokeModel, or referenced from a Flows prompt node. That lets you run every variant against the same test inputs, re-run exactly the same variant months later, and switch production to the winner by changing configuration rather than code. The value lies in immutability plus a built-in record of what each version contained; any mechanism where the text can change in place loses that.

Flows versions and aliases

Inline prompts copied into prompt nodes give up the prompt versioning that makes the test reproducible.

Splitting traffic consistently

To send a share of users to the new variant and keep each user on the same variant, hash a stable user ID into buckets in the application, pass the bucket into the flow as input, and route with a condition node to the prompt node bound to the test version. Emit the variant as a CloudWatch dimension so fairness metrics separate by arm. A valid A/B test needs both arms live at once, assignment decided by your code rather than the model, and assignment that stays the same for a user across requests.

An LLM-as-a-judge evaluation is an Amazon Bedrock model evaluation job in which a second model (the evaluator, or judge) scores each response from the model under test against selected metrics. It needs no human raters, runs on your own prompt dataset, and suits automated checks before each release.

Built-in metrics for responsible AI

Responsible AI metrics trade off against each other. A prompt change that cuts stereotyping can cause over-refusal: legitimate questions that mention a protected characteristic (for example a question about accessibility support for disabled travellers) get declined, and both Stereotyping and Harmfulness give a refusal a good score. Track Refusal alongside them to see whether a fix traded one harm for another. You can also define custom metrics with your own judge prompt and rating scale.

The dataset

Each JSONL record holds prompt, an optional referenceResponse (ground truth for correctness-type metrics) and an optional category. Scores are reported per category, so one job can give results per customer segment; splitting the dataset into one job per segment only adds work.

Judging responses you generated elsewhere

To evaluate a model that is not in Amazon Bedrock (for example on a SageMaker AI endpoint) without importing it, generate the responses yourself and supply them in each record's modelResponses (the response plus a modelIdentifier). Bedrock then skips inference and the judge scores the supplied responses. Such a dataset supports one response per prompt and a single unique modelIdentifier, so comparing two models takes one job per model, and you compare the reports.

Keeping scores comparable over time

A judge score depends on the judge. If the evaluator model changes between releases, a score change mixes the product change with the judge change. To attribute it, re-score the previous release's saved responses with the new evaluator (as your own inference responses) and compare both under that evaluator; for trend reporting, keep the evaluator model, its version and the dataset fixed, and re-baseline whenever the evaluator changes. The metric name being the same does not make the scale the same.

Match the tool to the property you need to measure: human-based evaluation jobs use a work team of people as raters; SageMaker Clarify pre-training bias metrics describe imbalance in a training dataset rather than in generated text; guardrails act on content at request time rather than scoring a release.

A policy-compliant AI system translates each written policy rule into the guardrail policy type that detects that kind of content, then makes the guardrail impossible to skip. Choosing the wrong policy type is the usual mistake.

Define denied topics positively. Describe what to block ("advice on how to resolve a specific legal dispute"), not "all legal questions except questions about our terms of service". AWS advises against exceptions and negative phrasing in definitions; they cause both over-blocking of allowed requests and under-blocking of prohibited ones. Sample phrases teach what to block, not what to allow.

Enforcing the guardrail with IAM

The bedrock:GuardrailIdentifier condition key lets a policy deny InvokeModel, InvokeModelWithResponseStream, Converse and ConverseStream unless the request names the approved guardrail. The ARN pattern decides which versions match:

A Deny that should allow future published versions but refuse the draft therefore uses ArnNotLike with the :* pattern.

Known limitation: AWS documents that a role restricted this way should not also call RetrieveAndGenerate, InvokeAgent or InvokeInlineAgent. Those APIs make several internal InvokeModel calls, some without the guardrail, so they are denied even when the request names it. Use a separate role without the condition for that workload and set the guardrail in its request (for example in the RetrieveAndGenerate generation configuration). The condition key can only test a guardrail that the call carries, so internal calls without one always fail the condition.

Selective input evaluation: when a prompt contains guardrail input tags (or guardContent blocks in Converse), only the tagged content is evaluated on input. Tagging your fixed instructions and leaving user text outside the tags means user input is never assessed, while responses are still filtered. Tag the user input, or don't tag selectively.

Model cards document what a model is for and where it fails; Lambda functions enforce the rules a guardrail cannot express. Together with guardrails they make responsible AI policy checkable.

SageMaker Model Cards vs AWS AI Service Cards

Tags or a prompt description field lack this structure and history; AWS Artifact reports cover infrastructure compliance, not model behaviour. The model card's approval status can become a preventive control: a release pipeline stage (for example in AWS CodePipeline) invokes a Lambda function that calls DescribeModelCard and fails the release unless the status is Approved. Note the distinction between preventive controls, which stop a non-compliant release before it ships, and detective controls such as AWS Config rules, which report noncompliance after the fact; and keep fields apart: the risk rating describes how risky the use is, while the approval status records whether it was signed off.

Automated compliance checks with Lambda

Guardrails detect and block unwanted content. They cannot enforce that something must be present (an AI-generated content notice, a jurisdiction-specific risk warning), that a value exactly equals a system of record (a quoted fee that must match the pricing database), or rules that need a lookup, a log entry with expected and actual values, or routing to human review. Those need code in the response path:

• A post-processing Lambda function checks each draft response before it is returned, then appends, blocks or replaces it as policy says, and logs each violation to CloudWatch Logs or a compliance store. It runs alongside any guardrail, not instead of it.
• In an Amazon Bedrock flow, a Lambda function node after the prompt node runs the check (reading reference data such as disclosures from DynamoDB, logging failures, queueing them for review), and a condition node routes on its result: failures to an output carrying a holding message, passes to the main output.

The general principle: instructions and extra context make compliance more likely, but only deterministic code that compares the response with the rule verifies it. A contextual grounding check is probabilistic support scoring, so a near-miss value can still score as grounded; a model reviewing its own output is self-assessment; masking removes information rather than checking it; and any analysis run over logs later is detective, finding violations after users have seen them.