# Test and troubleshoot agent behavior
After you create an agent, you will have a *working draft*. The working draft is a version of the agent that you can use to iteratively build the agent. Each time you make changes to your agent, the working draft is updated. When you're satisfied with your agent's configurations, you can create a *version*, which is a snapshot of your agent, and an *alias*, which points to the version. You can then deploy your agent to your applications by calling the alias. For more information, see [Deploy and use an Amazon Bedrock agent in your application](agents-deploy.md).
The following list describes how you test your agent:
+ In the Amazon Bedrock console, you open up the test window on the side and send input for your agent to respond to. You can select the working draft or a version that you've created.
+ In the API, the working draft is the `DRAFT` version. You send input to your agent by using [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) with the test alias, `TSTALIASID`, or a different alias pointing to a static version. Before you can test your agent, you must prepare your agent by calling [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html).
## Tracing agent behavior
To help troubleshoot your agent's behavior, Amazon Bedrock Agents provides the ability to view the *trace* during a session with your agent. The trace shows the agent's step-by-step reasoning process. For more information about the trace, see [Track agent's step-by-step reasoning process using trace](trace-events.md).
## Test your agent
Following are steps for testing your agent. Choose the tab for your preferred method, and then follow the steps:
------
#### [ Console ]
**To test an agent**
1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).
1. Select **Agents** from the left navigation pane. Then, choose an agent in the **Agents** section.
1. In the **Agents** section, select the link for the agent that you want to test from the list of agents.
1. The **Test** window appears in a pane on the right.
**Note**
If the **Test window** is closed, you can reopen it by selecting **Test** at the top of the agent details page or any page within it.
1. After you create an agent, you must package it with the working draft changes by preparing it in one of the following ways:
+ In the **Test** window, select **Prepare**.
+ In the **Working draft** page, select **Prepare** at the top of the page.
**Note**
Every time you update the working draft, you must prepare the agent to package the agent with your latest changes. As a best practice, we recommend that you always check your agent's **Last prepared** time in the **Agent overview** section of the **Working draft** page to verify that you're testing your agent with the latest configurations.
1. To choose an alias and associated version to test, use the dropdown menu at the top of the **Test window**. By default, the **TestAlias: Working draft** combination is selected.
1. (Optional) To select Provisioned Throughput for your alias, the text below the test alias you selected will indicate **Using ODT** or **Using PT**. To create a Provisioned Throughput model, select **Change**. For more information, see [Increase model invocation capacity with Provisioned Throughput in Amazon Bedrock](prov-throughput.md).
1. (Optional) To use a prompt from Prompt management, select the options icon (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) in the message box and choose **Import prompt**. Select the prompt and version. Enter values for the prompt variables in the **Test variable values** section. For more information about prompts in Prompt management, see [Construct and store reusable prompts with Prompt management in Amazon Bedrock](prompt-management.md).
1. To test the agent, enter a message and choose **Run**. While you wait for the response to generate or after it is generated, you have the following options:
+ To view details for each step of the agent's orchestration process, including the prompt, inference configurations, and agent's reasoning process for each step and usage of its action groups and knowledge bases, select **Show trace**. The trace is updated in real-time so you can view it before the response is returned. To expand or collapse the trace for a step, select an arrow next to a step. For more information about the **Trace** window and details that appear, see [Track agent's step-by-step reasoning process using trace](trace-events.md).
+ If the agent invokes a knowledge base, the response contains footnotes. To view the link to the S3 object containing the cited information for a specific part of the response, select the relevant footnote.
+ If you set your agent to return control rather than using a Lambda function to handle the action group, the response contains the predicted action and its parameters. Provide an example output value from the API or function for the action and then choose **Submit** to generate an agent response. See the following image for an example:
![\[Test window request to provide an example output for the action.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/agents/roc-testwindow.png)
You can perform the following actions in the **Test** window:
+ To start a new conversation with the agent, select the refresh icon.
+ To view the **Trace** window, select the expand icon. To close the **Trace** window, select the shrink icon.
+ To close the **Test** window, select the right arrow icon.
You can enable or disable action groups and knowledge bases. Use this feature to troubleshoot your agent by isolating which action groups or knowledge bases need to be updated by assessing its behavior with different settings.
**To enable an action group or knowledge base**
1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).
1. Select **Agents** from the left navigation pane. Then, choose an agent in the **Agents** section.
1. In the **Agents** section. select the link for the agent that you want to test from the list of agents.
1. On the agent's details page, in the **Working draft** section, select the link for the **Working draft**.
1. In the **Action groups** or **Knowledge bases** section, hover over the **State** of the action group or knowledge base whose state you want to change.
1. An edit button appears. Select the edit icon and then choose from the dropdown menu whether the action group or knowledge base is **Enabled** or **Disabled**.
1. If an action group is **Disabled**, the agent doesn't use the action group. If a knowledge base is **Disabled**, the agent doesn't use the knowledge base. Enable or disable action groups or knowledge bases and then use the **Test** window to troubleshoot your agent.
1. Choose **Prepare** to apply the changes that you have made to the agent before testing it.
------
#### [ API ]
For agents that are created `after` March 31, 2025:
+ If you've created your agent in the console, streaming is enabled by default. You can disable streaming anytime.
+ Ensure the Agent execution role includes the `bedrock:InvokeModelWithResponseStream` permission for the configured agent model.
Before you test your agent for the first time, you must package it with the working draft changes by sending a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Include the `agentId` in the request. The changes apply to the `DRAFT` version, which the `TSTALIASID` alias points to.
```
def prepare_agent(self, agent_id):
"""
Creates a DRAFT version of the agent that can be used for internal testing.
:param agent_id: The unique identifier of the agent to prepare.
:return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
"""
try:
prepared_agent_details = self.client.prepare_agent(agentId=agent_id)
except ClientError as e:
logger.error(f"Couldn't prepare agent. {e}")
raise
else:
return prepared_agent_details
```
For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md).
**Note**
Every time you update the working draft, you must prepare the agent to package the agent with your latest changes. As a best practice, we recommend that you send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html) request (see link for request and response formats and field details) with a [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and check the `preparedAt` time for your agent to verify that you're testing your agent with the latest configurations.
To test your agent, send an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) request to the agent. For example code, see [Invoke an agent from your application](agents-invoke-agent.md).
**Note**
The AWS CLI doesn't support [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html).
The following fields exist in the request:
+ Minimally, provide the following required fields:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/agents-test.html)
+ The following fields are optional:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/agents-test.html)
The response is returned in an event stream. Each event contains a `chunk`, which contains part of the response in the `bytes` field, which must be decoded. The following objects may also be returned:
+ If the agent queried a knowledge base, the `chunk` also includes `citations`.
+ If streaming is enabled and guardrail is configured for the agent, the response is generated in the character intervals specified for the guardrail interval. By default, the interval is set to 50 characters.
+ If you enabled a trace, a `trace` object is also returned. If an error occurs, a field is returned with the error message. For more information about how to read the trace, see [Track agent's step-by-step reasoning process using trace](trace-events.md).
+ If you set up your action group to skip using a Lambda function, a [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) object is returned in the `returnControl` field. The general structure of the [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) object is as follows:
```
{
"invocationId": "string",
"invocationInputs": [
[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) or [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html),
...
]
}
```
Each member of the `invocationInputs` list is one of the following:
+ An [ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) object containing the API operation that the agent predicts should be called based on the user input, in addition to the parameters and other information that it gets from the user to fulfill the API. The structure of the [ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) object is as follows:
```
{
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
: {
"properties": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
}
}
```
+ A [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) object containing the function that the agent predicts should be called based on the user input, in addition to the parameters for that function that it gets from the user. The structure of the [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) is as follows:
```
{
"actionGroup": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
```
------
# Track agent's step-by-step reasoning process using trace
Each response from an Amazon Bedrock agent is accompanied by a *trace* that details the steps being orchestrated by the agent. The trace helps you follow the agent's reasoning process that leads it to the response it gives at that point in the conversation.
Use the trace to track the agent's path from the user input to the response it returns. The trace provides information about the inputs to the action groups that the agent invokes and the knowledge bases that it queries to respond to the user. In addition, the trace provides information about the outputs that the action groups and knowledge bases return. You can view the reasoning that the agent uses to determine the action that it takes or the query that it makes to a knowledge base. If a step in the trace fails, the trace returns a reason for the failure. Use the detailed information in the trace to troubleshoot your agent. You can identify steps at which the agent has trouble or at which it yields unexpected behavior. Then, you can use this information to consider ways in which you can improve the agent's behavior.
# View the trace
The following describes how to view the trace. Choose the tab for your preferred method, and then follow the steps:
------
#### [ Console ]
**To view the trace during a conversation with an agent**
Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).
1. In the **Agents** section, select the link for the agent that you want to test from the list of agents.
1. The **Test** window appears in a pane on the right.
1. Enter a message and choose **Run**. While the response is generating or after it finishes generating, select **Show trace**.
1. You can view the trace for each **Step** in real-time as your agent performs orchestration.
------
#### [ API ]
To view the trace, send an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) request with a [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt) and set the `enableTrace` field to `TRUE`. By default, the trace is disabled. or example code, see [Invoke an agent from your application](agents-invoke-agent.md).
If you enable the trace, in the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) response, each `chunk` in the stream is accompanied by a `trace` field that maps to a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) object. Within the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) is a `trace` field that maps to a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html) object.
------
## Structure of the trace
If you enable the trace, in the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) response, each `chunk` in the stream is accompanied by a `trace` field that maps to a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) object. The `tracePart` object contains information about the agent and sessions, alongside the agent's reasoning process and and results from calling API functions.
```
{
"agentId": "string",
"agentName": "string",
"collaboratorName": "string",
"agentAliasId": "string",
"sessionId": "string",
"agentVersion": "string",
"trace": { ...},
"callerChain": [{
"agentAliasArn": "agent alias arn"
}]
}
```
The following list describes the fields of [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) object:
+ `agentId` – The unique identifier of the agent.
+ `agentName` – The name of the agent.
+ `collaboratorName` – If the multi-agent collaboration is enabled, the name of the collaborator agent.
+ `agentVersion` – The version of the agent.
+ `agentAliasId` – The unique identifier of the alias of the agent.
+ `sessionId` – The unique identifier of the session with the agent.
+ `trace` – Contains the agent's reasoning process and results from calling API actions. See below for more information.
+ `callerChain` – List of callers between the agent that published this trace and the end user.
+ If it is a single agent, this field will contain the alias Arn of the same agent who published the trace.
+ If multi-agent collaboration is enabled, this field will contain the alias Arn of all agents that forwarded the end user request to the current agent.
Within the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) is a `trace` field that maps to a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html) object. The trace is shown as a JSON object in both the console and the API. Each **Step** in the console or [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html) in the API can be one of the following traces:
+ [PreProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingTrace.html) – Traces the input and output of the pre-processing step, in which the agent contextualizes and categorizes user input and determines if it is valid.
+ [OrchestrationTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationTrace.html) – Traces the input and output of the orchestration step, in which the agent interprets the input, invokes action groups, and queries knowledge bases. Then the agent returns output to either continue orchestration or to respond to the user.
+ [PostProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingTrace.html) – Traces the input and output of the post-processing step, in which the agent handles the final output of the orchestration and determines how to return the response to the user.
+ [CustomOrchestrationTrace](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_CustomOrchestrationTrace.html) – Details about the custom orchestration step in which the agent determines the order in which actions are executed.
+ [RoutingClassifierTrace](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_RoutingClassifierTrace.html) – Traces the input and output of the routing classifier
+ [FailureTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FailureTrace.html) – Traces the reason that a step failed.
+ [GuardrailTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GuardrailTrace.html) – Traces the actions of the Guardrail.
Each of the traces (except `FailureTrace`) contains a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object. The [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object contains configurations set in the prompt template for the step, alongside the prompt provided to the agent at this step. For more information about how to modify prompt templates, see [Enhance agent's accuracy using advanced prompt templates in Amazon Bedrock](advanced-prompts.md). The structure of the `ModelInvocationInput` object is as follows:
```
{
"traceId": "string",
"text": "string",
"type": "PRE_PROCESSING | ORCHESTRATION | ROUTING_CLASSIFIER | KNOWLEDGE_BASE_RESPONSE_GENERATION | POST_PROCESSING",
"foundationModel":string",
"inferenceConfiguration": {
"maximumLength": number,
"stopSequences": ["string"],
"temperature": float,
"topK": float,
"topP": float
},
"promptCreationMode": "DEFAULT | OVERRIDDEN",
"parserMode": "DEFAULT | OVERRIDDEN",
"overrideLambda": "string"
}
```
The following list describes the fields of the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object:
+ `traceId` – The unique identifier of the trace.
+ `text` – The text from the prompt provided to the agent at this step.
+ `type` – The current step in the agent's process.
+ `foundationModel` – The foundation model of the collaborator agent in the multi-agent collaboration. This field is populated only if the `type` is `ROUTING_CLASSIFIER`. If the default model used for routing prompt is overridden, this field shows the model of the supervisor agent that is used for routing the prompt.
+ `inferenceConfiguration` – Inference parameters that influence response generation. For more information, see [Influence response generation with inference parameters](inference-parameters.md).
+ `promptCreationMode` – Whether the agent's default base prompt template was overridden for this step. For more information, see [Enhance agent's accuracy using advanced prompt templates in Amazon Bedrock](advanced-prompts.md).
+ `parserMode` – Whether the agent's default response parser was overridden for this step. For more information, see [Enhance agent's accuracy using advanced prompt templates in Amazon Bedrock](advanced-prompts.md).
+ `overrideLambda` – The Amazon Resource Name (ARN) of the parser Lambda function used to parse the response, if the default parser was overridden. For more information, see [Enhance agent's accuracy using advanced prompt templates in Amazon Bedrock](advanced-prompts.md).
For more information about each trace type, see the following sections:
### PreProcessingTrace
```
{
"modelInvocationInput": { // see above for details }
"modelInvocationOutput": {
"metadata": {
"usage": {
"inputToken":: int,
"outputToken":: int
},
"rawResponse": {
"content": "string"
}
"parsedResponse": {
"isValid": boolean,
"rationale": "string"
},
"traceId": "string"
}
}
```
The [PreProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingTrace.html) consists of a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object and a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html) object. The [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html) contains the following fields.
+ `metadata` – Contains the following information about the foundation model output.
+ `usage` – Contains the following information of the usage of the foundation model.
+ `inputTokens` – Contains the information about the input tokens from the foundation model usage.
+ `outputTokens` – Contains the information about the output tokens from the foundation model usage.
+ `rawResponse` – Contains the raw output from the foundation model.
+ `content` – The foundation model's raw output content.
+ `parsedResponse` – Contains the following details about the parsed user prompt.
+ `isValid` – Specifies whether the user prompt is valid.
+ `rationale` – Specifies the agent's reasoning for the next steps to take.
+ `traceId` – The unique identifier of the trace.
### OrchestrationTrace
The [OrchestrationTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationTrace.html) consists of the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object, [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html) object, and any combination of the [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html), [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html), and [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html) objects. The [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html) contains the following fields. For more information about [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html), [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html), and [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html) objects, select from the following tabs.
```
{
"modelInvocationInput": { // see above for details },
"modelInvocationOutput": {
"metadata": {
"usage": {
"inputToken":: int,
"outputToken":: int
},
"rawResponse": {
"content": "string"
},
"rationale": { ... },
"invocationInput": { ... },
"observation": { ... }
}
```
If the `type` is `AGENT_COLLABORATOR` and if the routing was enabled for the supervisor agent, [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html) will contain the following structure:
```
routingClassifierModelInvocationOutput: {
traceId: "string",
rawResponse: "string",
routerClassifierParsedResponse: {...}
metadata: {
inputTokens: "..."
outputTokens: "..."
}
}
```
------
#### [ Rationale ]
The [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html) object contains the reasoning of the agent given the user input. Following is the structure:
```
{
"traceId": "string",
"text": "string"
}
```
The following list describes the fields of the [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html) object:
+ `traceId` – The unique identifier of the trace step.
+ `text` – The reasoning process of the agent, based on the input prompt.
------
#### [ InvocationInput ]
The [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html) object contains information that will be input to the action group or knowledge base that is to be invoked or queried. Following is the structure:
```
{
"traceId": "string",
"invocationType": "AGENT_COLLABORATOR" | "ACTION_GROUP | KNOWLEDGE_BASE | FINISH",
"agentCollaboratorInvocationInput": {
// see below for details
},
"actionGroupInvocationInput": {
// see below for details
},
"knowledgeBaseLookupInput": {
"knowledgeBaseId": "string",
"text": "string"
}
}
```
The following list describes the fields of the [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html) object:
+ `traceId` – The unique identifier of the trace.
+ `invocationType` – Specifies whether the agent is invoking a collaborator agent, an action group or a knowledge base, or ending the session.
+ `agentCollaborationInvocationInput` – Contains the invocation input to the collaborator agents. Appears if the `type` is `AGENT_COLLABORATOR` and if routing is enabled for the supervisor agent. For more information, see [Use multi-agent collaboration with Amazon Bedrock Agents](agents-multi-agent-collaboration.md).
+ The `agentCollaborationInvocationInput ` structure is as follows:
```
{
"agentCollaboratorName": "string",
"agentCollaboratorAliasArn": "string",
"input": {
"text": "string"
}
}
```
Following are descriptions of the fields:
+ `agentCollaboratorName` – The name of the collaborator agent associated with the supervisor agent.
+ `agentCollaboratorAliasArn` – The alias Arn of the collaborator agent.
+ `input` – The input string for the collaborator agent.
+ `actionGroupInvocationInput` – Appears if the `type` is `ACTION_GROUP`. For more information, see [Define actions in the action group](action-define.md). Can be one of the following structures:
+ If the action group is defined by an API schema, the structure is as follows:
```
{
"actionGroupName": "string",
"apiPath": "string",
"verb": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
"content": {
"": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
},
"executionType": "LAMBDA | RETURN_CONTROL",
"invocationId": "string"
}
```
Following are descriptions of the fields:
+ `actionGroupName` – The name of the action group that the agent predicts should be invoked.
+ `apiPath` – The path to the API operation to call, according to the API schema.
+ `verb` – The API method being used, according to the API schema.
+ `parameters` – Contains a list of objects. Each object contains the name, type, and value of a parameter in the API operation, as defined in the API schema.
+ `requestBody` – Contains the request body and its properties, as defined in the API schema.
+ `executionType` – Whether fulfillment of the action is passed to a Lambda function (`LAMBDA`) or control is returned through the `InvokeAgent` response (`RETURN_CONTROL`). For more information, see [Handle fulfillment of the action](action-handle.md).
+ `invocationId` – The unique identifier of the invocation. Only returned if the `executionType` is `RETURN_CONTROL`.
+ If the action group is defined by function details, the structure is as follows:
```
{
"actionGroupName": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"executionType": "LAMBDA | RETURN_CONTROL",
"invocationId": "string"
}
```
Following are descriptions of the fields:
+ `actionGroupName` – The name of the action group that the agent predicts should be invoked.
+ `function` – The name of the function that the agent predicts should be called.
+ `parameters` – The parameters of the function.
+ `executionType` – Whether fulfillment of the action is passed to a Lambda function (`LAMBDA`) or control is returned through the `InvokeAgent` response (`RETURN_CONTROL`). For more information, see [Handle fulfillment of the action](action-handle.md).
+ `invocationId` – The unique identifier of the invocation. Only returned if the `executionType` is `RETURN_CONTROL`.
+ `knowledgeBaseLookupInput` – Appears if the `type` is `KNOWLEDGE_BASE`. For more information, see [Retrieve data and generate AI responses with Amazon Bedrock Knowledge Bases](knowledge-base.md). Contains the following information about the knowledge base and the search query for the knowledge base:
+ `knowledgeBaseId` – The unique identifier of the knowledge base that the agent will look up.
+ `text` – The query to be made to the knowledge base.
------
#### [ Observation ]
The [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html) object contains the result or output of an agent collaborator, an action group or knowledge base, or the response to the user. Following is the structure:
```
{
"traceId": "string",
"type": "AGENT_COLLABORATOR |ACTION_GROUP | KNOWLEDGE_BASE | REPROMPT | ASK_USER | FINISH",
"agentCollaboratorInvocationOutput": {
"agentCollaboratorName": "string",
"agentCollaboratorAliasArn": "string",
"output": {
"text": "string"
},
"actionGroupInvocation": {
"text": "JSON-formatted string"
},
"knowledgeBaseLookupOutput": {
"retrievedReferences": [
{
"content": {
"text": "string"
},
"location": {
"type": "S3",
"s3Location": {
"uri": "string"
}
}
},
...
]
},
"repromptResponse": {
"source": "ACTION_GROUP | KNOWLEDGE_BASE | PARSER",
"text": "string"
},
"finalResponse": {
"text"
}
}
```
The following list describes the fields of the [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html) object:
+ `traceId` – The unique identifier of the trace.
+ `type` – Specifies whether the agent's observation is returned from the result of an agent collaborator, an action group or a knowledge base, if the agent is reprompting the user, requesting more information, or ending the conversation.
+ `agentCollaboratorInvocationOutput` – Contains the response from the collaborator agent or the final response. Appears if the `type` is `AGENT_COLLABORATOR` and if routing is enabled for the supervisor agent. For more information, see [Use multi-agent collaboration with Amazon Bedrock Agents](agents-multi-agent-collaboration.md). Each response contains the following fields:
+ `agentCollaboratorName` – The name of the collaborator agent sending the response.
+ `agentCollaboratorAliasArn` – The alias Arn of the collaborator agent sending the response.
+ `output` – Contains the response sent by the collaborator agent.
+ `actionGroupInvocationOutput` – Contains the JSON-formatted string returned by the API operation that was invoked by the action group. Appears if the `type` is `ACTION_GROUP`. For more information, see [Define OpenAPI schemas for your agent's action groups in Amazon Bedrock](agents-api-schema.md).
+ `knowledgeBaseLookupOutput` – Contains text retrieved from the knowledge base that is relevant to responding to the prompt, alongside the Amazon S3 location of the data source. Appears if the `type` is `KNOWLEDGE_BASE`. For more information, see [Retrieve data and generate AI responses with Amazon Bedrock Knowledge Bases](knowledge-base.md). Each object in the list of `retrievedReferences` contains the following fields:
+ `content` – Contains `text` from the knowledge base that is returned from the knowledge base query.
+ `location` – Contains the Amazon S3 URI of the data source from which the returned text was found.
+ `repromptResponse` – Appears if the `type` is `REPROMPT`. Contains the `text` that asks for a prompt again alongside the `source` of why the agent needs to reprompt.
+ `finalResponse` – Appears if the `type` is `ASK_USER` or `FINISH`. Contains the `text` that asks the user for more information or is a response to the user.
------
### PostProcessingTrace
```
{
"modelInvocationInput": { // see above for details }
"modelInvocationOutput": {
"rawResponse": {
"content": "string"
},
"metadata": {
"usage": {
"inputToken": int,
"outputToken": int
}
},
"parsedResponse": {
"text": "string"
},
"traceId": "string"
}
}
```
The [PostProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingTrace.html) consists of a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) object and a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html) object. The [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html) contains the following fields:
+ `rawResponse` – Contains the raw output from the foundation model.
+ `content` – The foundation model's raw output content.
+ `metadata` – Contains the following information about the foundation model output.
+ `usage` – Contains the following information of the usage of the foundation model.
+ `inputTokens` – Contains the information about the input tokens from the foundation model usage.
+ `outputTokens` – Contains the information about the output tokens from the foundation model usage.
+ `parsedResponse` – Contains the `text` to return to the user after the text is processed by the parser function.
+ `traceId` – The unique identifier of the trace.
### FailureTrace
```
{
"failureReason": "string",
"traceId": "string"
}
```
The following list describes the fields of the [FailureTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FailureTrace.html) object:
+ `failureReason` – The reason that the step failed.
+ `traceId` – The unique identifier of the trace.
### GuardrailTrace
```
{
"action": "GUARDRAIL_INTERVENED" | "NONE",
"inputAssessments": [GuardrailAssessment],
"outputAssessments": [GuardrailAssessment]
}
```
The following list describes the fields of the GuardrailAssessment object:
+ `action` – indicates whether guardrails intervened or not on the input data. Options are `GUARDRAIL_INTERVENED` or `NONE`.
+ `inputAssessments` – The details of the Guardrail assessment on the user input.
+ `outputAssessments` – The details of the Guardrail assessment on the response.
For more details on the `GuardrailAssessment` object and testing a Guardrail, see [Test your guardrail](guardrails-test.md).
GuardrailAssessment example:
```
{
"topicPolicy": {
"topics": [{
"name": "string",
"type": "string",
"action": "string"
}]
},
"contentPolicy": {
"filters": [{
"type": "string",
"confidence": "string",
"action": "string"
}]
},
"wordPolicy": {
"customWords": [{
"match": "string",
"action": "string"
}],
"managedWordLists": [{
"match": "string",
"type": "string",
"action": "string"
}]
},
"sensitiveInformationPolicy": {
"piiEntities": [{
"type": "string",
"match": "string",
"action": "string"
}],
"regexes": [{
"name": "string",
"regex": "string",
"match": "string",
"action": "string"
}]
}
}
```