本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 测试代理行为并进行问题排查
创建代理后，您将获得一份*工作草稿*。工作草稿是代理的一个版本，可用于以迭代方式构建代理。每次您对代理进行更改时，工作草稿都会更新。确认代理配置无误之后，您可以创建一个*版本*（即代理的快照）和指向该版本的一个*别名*。然后，您可以通过调用别名将代理部署到您的应用程序中。有关更多信息，请参阅 [在您的应用程序中部署和使用 Amazon Bedrock 代理](agents-deploy.md)。
以下列表介绍了如何测试代理：
+ 在 Amazon Bedrock 控制台中，您可以打开侧面的测试窗口并发送输入，让代理进行响应。您可以选择工作草稿或已创建的版本。
+ 在 API 中，工作草稿是 `DRAFT` 版本。您可以使用 [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)，并通过测试别名 `TSTALIASID` 或指向静态版本的其他别名向代理发送输入。在测试您的代理之前，必须通过调用 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) 来准备您的代理。
## 跟踪代理行为
为了帮助您针对代理行为进行问题排查，Amazon Bedrock 代理提供了在与代理会话期间查看*跟踪记录*的功能。跟踪记录显示代理的分步推理过程。有关跟踪记录的更多信息，请参阅 [使用跟踪功能跟踪代理的分步推理过程](trace-events.md)。
## 测试您的代理
以下是测试代理的步骤。选择与您的首选方法对应的选项卡，然后按照以下步骤操作：
------
#### [ Console ]
**测试代理**
1. 使用有权使用 Amazon Bedrock 控制台的 IAM 身份登录。 AWS 管理控制台 然后，打开 Amazon Bedrock 控制台，网址为[https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)。
1. 从左侧导航窗格中选择**代理**。然后，在**代理**部分选择一个代理。
1. 在**代理**部分，从代理列表中选择要测试的代理的链接。
1. **测试**窗口将显示在右侧的窗格中。
**注意**
如果**“测试”窗口**已关闭，您可以在代理详细信息页面或其中的任何页面的顶部选择**测试**，重新打开该窗口。
1. 创建代理后，您必须使用以下方式之一准备代理，将其与工作草稿更改打包：
+ 在**测试**窗口中，选择**准备**。
+ 在**工作草稿**页面中，选择页面顶部的**准备**。
**注意**
每次更新工作草稿时，您都必须准备代理，将最新更改打包到代理中。根据最佳实践，我们建议您始终在**工作草稿**页面的**代理概述**部分检查代理的**上次准备时间**，以便确保使用最新配置来测试代理。
1. 使用**测试窗口**顶部的下拉菜单选择要测试的别名和关联版本。默认情况下，选择 **TestAlias：工作草稿**组合。
1. （可选）要为您的别名选择预调配吞吐量，您选择的测试别名下方的文本将显示**使用 ODT** 或**使用 PT**。要创建预调配吞吐量模型，请选择**更改**。有关更多信息，请参阅 [利用 Amazon Bedrock 中的预调配吞吐量增加模型调用容量](prov-throughput.md)。
1. （可选）要使用提示管理器中的提示，请在消息框中选择选项图标（），然后选择**导入提示**。选择提示和版本。在**测试变量值**部分中输入提示变量的值。有关提示管理器中的提示的更多信息，请参阅 [在 Amazon Bedrock 中使用提示管理器构建和存储可重复使用的提示](prompt-management.md)。
1. 要测试代理，您需要输入一条消息并选择**运行**。在等待系统生成响应时或响应生成后，您可以选择以下选项：
+ 要查看代理编排过程中每个步骤的详细信息，包括每个步骤的提示、推理配置和代理的推理过程以及其操作组和知识库的使用情况，请选择**显示跟踪记录**。跟踪记录会实时更新，因此您可以在系统返回响应之前进行查看。选择步骤旁边的箭头，展开或折叠某个步骤的跟踪记录。有关**跟踪记录**窗口和显示的详细信息的更多信息，请参阅 [使用跟踪功能跟踪代理的分步推理过程](trace-events.md)。
+ 如果代理调用了知识库，响应中将包含脚注。要查看包含响应特定部分引用信息的 S3 对象的链接，请选择相关的脚注。
+ 如果您将代理设置为交还控制权，而不是使用 Lambda 函数来处理操作组，则响应中将包含预测的操作及其参数。提供与操作相对应的 API 或函数的输出值示例，然后选择**提交**以生成代理响应。有关示例，请参阅下图：
您可以在**测试**窗口中执行以下操作：
+ 要与代理开始新的对话，选择刷新图标。
+ 要查看**跟踪记录**窗口，选择展开图标。要关闭**跟踪记录**窗口，选择收起图标。
+ 要关闭**测试**窗口，选择右箭头图标。
您可以启用或禁用操作组和知识库。通过使用不同的设置观察代理的行为，确定哪些操作组或知识库需要更新，进而利用此功能来进行问题排查。
**启用操作组或知识库**
1. 使用有权使用 Amazon Bedrock 控制台的 IAM 身份登录。 AWS 管理控制台 然后，打开 Amazon Bedrock 控制台，网址为[https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)。
1. 从左侧导航窗格中选择**代理**。然后，在**代理**部分选择一个代理。
1. 在**代理**部分，从代理列表中选择要测试的代理的链接。
1. 在代理详细信息页面上的**工作草稿**部分，选择**工作草稿**的链接。
1. 在**操作组**或**知识库**部分，将鼠标悬停在要更改其状态的操作组或知识库的**状态**上。
1. 此时将出现一个编辑按钮。选择编辑图标，然后从下拉菜单中选择**启用**或**禁用**操作组或知识库。
1. 如果操作组处于**禁用**状态，则代理不会使用该操作组。如果知识库处于**禁用**状态，则代理不会使用该知识库。启用或禁用操作组或知识库，然后使用**测试**窗口对代理进行问题排查。
1. 选择**准备**以应用对代理所做的更改，然后再测试代理。
------
#### [ API ]
对于 `after` 2025 年 3 月 31 日创建的代理：
+ 如果您在控制台中创建了代理，则默认情况下会启用流式传输。您可以随时禁用流式传输。
+ 请确保代理执行角色包含已配置代理模型的 `bedrock:InvokeModelWithResponseStream` 权限。
在第一次测试代理之前，您必须通过使用 [Amazon Bedrock 代理构建时端点](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)发送 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) 请求，将代理与工作草稿更改打包。在请求中包含 `agentId`。更改将应用于 `TSTALIASID` 别名指向的 `DRAFT` 版本。
```
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
```
有关更多信息，请参阅 [开始使用 Amazon Bedrock 代理](bedrock-agent_example_bedrock-agent_Hello_section.md)。
**注意**
每次更新工作草稿时，您都必须准备代理，将最新更改打包到代理中。根据最佳实践，我们建议您使用 [Amazon Bedrock 代理构建时端点](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)发送 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html) 请求（有关请求和响应格式以及字段详细信息，请参阅链接），并查看代理的 `preparedAt` 时间，以便确保使用最新配置来测试代理。
要测试您的代理，请向代理发送 [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) 请求。有关示例代码，请参阅[从您的应用程序调用代理](agents-invoke-agent.md)。
**注意**
AWS CLI 不支持[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)。
请求中包含以下字段：
+ 至少提供以下必填字段：
****
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/bedrock/latest/userguide/agents-test.html)
+ 以下字段是可选字段：
****
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/bedrock/latest/userguide/agents-test.html)
响应以事件流的形式返回。每个事件都包含一个 `chunk`，其中包含响应的一部分，该部分位于 `bytes` 字段中，您必须对相应数据进行解码。系统还可能返回以下对象：
+ 如果代理查询了知识库，则 `chunk` 中还会包含 `citations`。
+ 如果启用了流式传输并为代理配置了护栏，则会按照为护栏间隔指定的字符间隔生成响应。默认情况下，间隔设置为 50 个字符。
+ 如果您启用了跟踪功能，系统还会返回一个 `trace` 对象。如果发生错误，系统会返回包含错误消息的字段。有关如何读取跟踪记录的更多信息，请参阅 [使用跟踪功能跟踪代理的分步推理过程](trace-events.md)。
+ 如果您使用 Lambda 函数将操作组设置为跳过，则字段中将`returnControl`返回一个[ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html)对象。该[ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html)对象的一般结构如下：
```
{
"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),
...
]
}
```
`invocationInputs` 列表中的每一项都是以下几项之一：
+ 除了为实现 API 而从用户那里获得的参数和其他信息外，还应根据用户输入来调用包含代理预测的 API 操作的[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html)对象。[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) 对象的结构如下所示：
```
{
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
{{}}: {
"properties": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
}
}
```
+ 除了从用户那里获得的该函数的参数外，还应根据用户输入调用包含代理预测的函数的[FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html)对象。的结构[FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html)如下：
```
{
"actionGroup": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
```
------