AWSAWS Certified Generative AI Developer - Professional2026-103.4 Implement responsible AI principles
Explain agent actions through selected trace events
Completed by the knowledge check
Learning objective
Use Amazon Bedrock agent traces to explain externally observable action and tool execution sequences.
Core idea
A useful execution explanation says which operation the agent requested, what the operation returned, and how that result affected the visible outcome. It does not claim that an agent trace proves a business transaction committed or reveals the definitive cause of every model choice.
Amazon Bedrock traces include both execution information and model reasoning. Select the execution information for your explanation. Keep raw trace access restricted and publish only a reviewed projection of observable events. The architectural decision is where to separate diagnostic richness from the evidence a user or auditor needs.
This lesson focuses on the action sequence. Lesson 3.4.1 covers public source-backed explanations, and 3.3.4 covers forensic records across services. The sequence connects these concerns without replacing either one.
How it works
Capture the agent trace deliberately
Set enableTrace to true in InvokeAgent when you need trace events. The request identifies the agent, alias, and session through agentId, agentAliasId, and sessionId. Consume trace events from the response stream rather than assuming that the final answer contains the complete execution record.
The trace structure carries agent and session information, including agentVersion, alongside a trace object. Within an orchestration trace, the important execution structures are invocationInput and observation. These distinguish what the agent asks a tool or knowledge base to do from what comes back.
Attach an application request identifier to the captured sequence. A conversation session can contain more than one user request, so the session alone is too broad for explaining one action. Keep the observed event order and the identifiers needed to join related records. If capture stops partway through the response, label the sequence incomplete instead of constructing missing steps from the final prose.
Read invocation and observation separately
InvocationInput.invocationType identifies the category of invocation. actionGroupInvocationInput records an action-group request; for an API-schema action group, it includes actionGroupName, apiPath, verb, and parameters. Those fields answer “which operation was requested?” without requiring the agent’s rationale.
A knowledge-base lookup uses knowledgeBaseLookupInput, including knowledgeBaseId and text. It describes the query the agent submitted. The corresponding observation can contain knowledgeBaseLookupOutput.retrievedReferences, which records returned source content and locations. Publishing those fields requires the evidence and disclosure checks described in 3.4.1.
Observation.type tells you what kind of result the agent observed. actionGroupInvocationOutput contains the JSON-formatted output returned by the invoked action-group operation. Other observations include a reprompt or final response. Use traceId where the structures provide it to relate the observed steps; do not treat every identifier in a stream as an application transaction identifier.
The agent requesting “submit reimbursement” is different from receiving “request queued,” and both are different from a reimbursement actually completing. Interpret the returned tool contract. If completion happens in another service, retain that service’s completion evidence as a separate record. Tool idempotency and durable outcome design belong to 2.1.11.
Build an explanation from an event projection
Convert permitted events into a small sequence: requested operation, sanitized arguments, observed result, and unresolved outcome. Use vocabulary that matches the evidence. “Requested,” “returned,” and “confirmed by the business service” mean different things and should not be interchanged.
For a failed step, use FailureTrace.failureReason and its traceId to identify the observed failure, then include the application response: retry, clarification, cancellation, or escalation. Use GuardrailTrace to identify guardrail actions, including an intervention that stopped a step. Do not promise that a later success erased the earlier attempt. Multiple attempts are part of the sequence, particularly when a side effect might have occurred before a response was lost.
Avoid copying rationale.text into the explanation. AWS documents it as the agent’s reasoning process based on the input prompt. Model invocation inputs and raw outputs can also contain prompts, retrieved data, or sensitive tool content. Their diagnostic purpose does not make them appropriate public evidence. Sanitization and trace retention are covered in 3.2.9; apply those boundaries before exporting the sequence.
Make missing evidence visible
A trace can show that the agent received a tool response without showing the tool’s internal execution. For a consequential action, join the trace to a trusted business record, using an application-defined operation identifier passed through the tool contract.
When your application must own execution, configure actionGroupExecutor.customControl: RETURN_CONTROL. The InvokeAgent response then carries returnControl.invocationInputs and returnControl.invocationId; your application executes the action and sends results through sessionState.returnControlInvocationResults, with the same action group and invocation identifier in sessionState.invocationId. In the trace, ActionGroupInvocationInput.executionType distinguishes LAMBDA from RETURN_CONTROL, and its invocationId is returned only for RETURN_CONTROL; join that handoff to your application’s execution record.
If that record is missing, explain the narrower fact: the request was sent, but completion is unconfirmed. Do not infer completion from the final answer’s wording. This distinction is particularly important when the tool returns a request identifier for asynchronous work or when the agent produces a response after a recoverable failure.
With RETURN_CONTROL, your application’s execution record, not the agent’s final answer, is the evidence of completion.
Key distinctions and trade-offs
Invocation versus effect: An invocation describes an attempted operation. A trusted completion record establishes the business effect. Agent observability alone does not replace the latter.
Observation versus truth: The trace records what the agent received. A defective tool can return an incorrect success message; validate the tool contract and reconcile important outcomes.
Execution explanation versus rationale: Selected input and output events can explain the observable path. Rationale is model reasoning and should remain outside the public sequence.
Capturing detailed traces improves diagnosis but creates sensitive records and review work. A minimal projection reduces disclosure while losing some debugging detail. Keep both needs explicit: restricted diagnostics for operators and a smaller event contract for explanations.
Architecture / decision scenario
An expense agent looks up a policy, invokes a reimbursement action group, and tells the employee the request was processed. The tool actually returned a queue receipt.
With tracing enabled, the application records the knowledge-base lookup, the action group’s API path and sanitized parameters, and the queue receipt in actionGroupInvocationOutput. It joins the receipt to the reimbursement service’s operation record. That record remains pending.
The employee sees “submitted for processing,” with the receipt and an authorized status path. An operator can inspect the restricted trace if processing fails, but neither surface publishes rationale or raw policy content. When the business service confirms completion, the explanation adds that independently verified event. The agent’s initial final response never becomes the sole proof of payment.
Common exam traps
- Assuming trace is enabled without setting
enableTrace. - Treating an invocation input as proof of completed tool execution.
- Treating a tool response as proof of an independently committed business effect.
- Publishing rationale alongside sanitized execution events.
- Using a session identifier as the only correlation key for every request.
- Filling gaps in an incomplete trace with a model-generated narrative.
What to remember
- Capture
InvokeAgenttrace events deliberately. - Separate
invocationInputfromobservation. - Explain requested operations and observed outputs with precise outcome vocabulary.
- Join consequential effects to trusted business completion records.
- Publish a permitted event projection, with missing evidence stated explicitly.
Knowledge check
An expense agent’s trace shows an actionGroupInvocationInput for the reimbursement API and an actionGroupInvocationOutput containing a queue receipt. The agent’s final answer tells the employee the reimbursement was processed. What should the explanation say?
An auditor asks which operation an agent asked a tool to perform for one request, with its arguments. Which trace content answers that without exposing the agent’s reasoning?
rationale.text for that stepmodelInvocationInput sent to the foundation model at that stepactionGroupInvocationInput with its apiPath , verb , and parametersfinalResponse observation that was returned to the useractionGroupInvocationInput records the requested operation and its parameters, which should be sanitized before export. rationale.text is the agent’s reasoning, the model invocation input carries the whole prompt and retrieved content, and the final response is prose, not an execution record.Trace capture for a request stops before any action-group observation arrives, yet the agent’s final answer says the refund succeeded. What should the application record?
An action group is configured with customControl: RETURN_CONTROL, so the application executes the payment itself. How should the explanation link the agent’s request to the payment?
invocationId to the application’s execution record for that paymentsessionId to the application’s payment records for that sessiontraceId to the next payment record created after the requestinvocationId , returned only for RETURN_CONTROL , and the application sends its results back under that identifier. Joining it to the application’s execution record ties the request to the effect. A session can hold many requests, and time or amount matching is inference, not a join.An employee makes three reimbursement requests in one agent session. The team must explain the action sequence for the second request only. Which identifier should scope the captured events?
sessionId that the application passed to InvokeAgentagentAliasId and agentVersion of the deployed agenttraceId of the first trace event in the sessiontraceId relates steps where the trace provides it, not whole requests.