本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 通过在 InvokeAgent 响应中发送从用户那里获取的信息，将控制权交还给代理开发人员
您可以选择通过在 [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) 响应中发送信息将控制权交还给代理开发人员，而不是将您的代理从用户那里获取的信息发送到 Lambda 函数进行处理。在创建或更新操作组时，您可以配置将控制权交还给代理开发人员。通过 API，您可以在 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html) 或 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html) 请求中的 `actionGroupExecutor` 对象中，将 `customControl` 的值指定为 `RETURN_CONTROL`。有关更多信息，请参阅 [在 Amazon Bedrock 中向代理添加操作组](agents-action-add.md)。
如果您为操作组配置了控制权交还，并且代理确定应该调用操作组中的操作，那么从用户那里获取的 API 或函数详细信息将在 [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) 响应中的 `invocationInputs` 字段中返回，同时，系统会返回唯一的 `invocationId`。然后，您可执行以下操作：
+ 根据 `invocationInputs` 中返回的信息，设置您的应用程序以调用您定义的 API 或函数。
+ 在另一个 [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) 请求中发送应用程序调用的结果，并将结果放入 `sessionState` 字段中，以便为代理提供上下文。您必须使用在 [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) 响应中返回的 `invocationId` 和 `actionGroup`。这些信息可用作进一步编排的上下文，发送到后处理阶段，以便代理对响应进行格式化，或者直接用于代理对用户的响应。
**注意**
如果您在 `sessionState` 字段中包含 `returnControlInvocationResults`，则 `inputText` 字段将被忽略。
要了解如何在创建操作组时配置将控制权交还给代理开发人员，请参阅 [在 Amazon Bedrock 中向代理添加操作组](agents-action-add.md)。
## 将控制权交还给代理开发人员的示例
例如，您可能设置了以下操作组：
+ 一个名为 `PlanTrip` 的操作组，其中包含一个 `suggestActivities` 操作，帮助用户在旅途中查找要进行的活动。该操作的 `description` 为：`This action suggests activities based on retrieved weather information`。
+ 一个名为 `WeatherAPIs` 的操作组，其中包含一个 `getWeather` 操作，帮助用户获取特定位置的天气。该操作必需的参数为 `location` 和 `date`。您将操作组配置为将控制权交还给代理开发人员。
下面提供了一个假设的操作流程：
1. 用户向您的代理发出以下查询：**What should I do today?**。该查询通过 [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) 请求中的 `inputText` 字段发送。
1. 您的代理确定应该调用 `suggestActivities` 操作，但是根据其描述，代理预测应该首先调用 `getWeather` 操作，以获取上下文信息来帮助完成 `suggestActivities` 操作。
1. 代理知道当前 `date` 为 `2024-09-15`，但获取天气信息所需的参数是用户的 `location`。代理会再次向用户提问“您在哪里？”
1. 用户提供的回复是 **Seattle**。
1. 代理在以下 [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) 响应中返回 `getWeather` 所需的参数（请选择一个选项卡，查看使用该方法定义的操作组的示例）：
------
#### [ Function details ]
```
HTTP/1.1 200
x-amzn-bedrock-agent-content-type: application/json
x-amz-bedrock-agent-session-id: session0
Content-type: application/json
{
"returnControl": {
"invocationInputs": [{
"functionInvocationInput": {
"actionGroup": "WeatherAPIs",
"function": "getWeather",
"parameters": [
{
"name": "location",
"type": "string",
"value": "seattle"
},
{
"name": "date",
"type": "string",
"value": "2024-09-15"
}
]
}
}],
"invocationId": "79e0feaa-c6f7-49bf-814d-b7c498505172"
}
}
```
------
#### [ OpenAPI schema ]
```
HTTP/1.1 200
x-amzn-bedrock-agent-content-type: application/json
x-amz-bedrock-agent-session-id: session0
Content-type: application/json
{
"invocationInputs": [{
"apiInvocationInput": {
"actionGroup": "WeatherAPIs",
"apiPath": "/get-weather",
"httpMethod": "get",
"parameters": [
{
"name": "location",
"type": "string",
"value": "seattle"
},
{
"name": "date",
"type": "string",
"value": "2024-09-15"
}
]
}
}],
"invocationId": "337cb2f6-ec74-4b49-8141-00b8091498ad"
}
```
------
1. 您的应用程序已配置为使用这些参数来获取与日期 `seattle` 对应的 `2024-09-15` 的天气。天气情况为下雨。
1. 您在另一个 [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) 请求的 `sessionState` 字段中发送这些结果，使用与之前的响应相同的 `invocationId`、`actionGroup` 和 `function`。请选择一个选项卡，查看使用该方法定义的操作组的示例：
------
#### [ Function details ]
```
POST https://bedrock-agent-runtime.us-east-1.amazonaws.com/agents/AGENT12345/agentAliases/TSTALIASID/sessions/abb/text
{
"enableTrace": true,
"sessionState": {
"invocationId": "79e0feaa-c6f7-49bf-814d-b7c498505172",
"returnControlInvocationResults": [{
"functionResult": {
"actionGroup": "WeatherAPIs",
"function": "getWeather",
"responseBody": {
"TEXT": {
"body": "It's rainy in Seattle today."
}
}
}
}]
}
}
```
------
#### [ OpenAPI schema ]
```
POST https: //bedrock-agent-runtime.us-east-1.amazonaws.com/agents/AGENT12345/agentAliases/TSTALIASID/sessions/abb/text
{
"enableTrace": true,
"sessionState": {
"invocationId": "337cb2f6-ec74-4b49-8141-00b8091498ad",
"returnControlInvocationResults": [{
"apiResult": {
"actionGroup": "WeatherAPIs",
"httpMethod": "get",
"apiPath": "/get-weather",
"responseBody": {
"application/json": {
"body": "It's rainy in Seattle today."
}
}
}
}]
}
}
```
------
1. 代理预测应该调用 `suggestActivities` 操作。它使用当天下雨的上下文信息，并在响应中建议用户进行室内活动，而不是室外活动。
### 将控制权交还给协作者代理的示例
如果您正在使用[多代理协作](agents-multi-agent-collaboration.md)，并且代理协作者选择通过在 [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) 响应中发送信息来交还控制权，则该信息将在主管代理响应中返回，并带有其他标识符 `agentId` 和 `collaboratorName`。请选择一个选项卡，查看使用该方法定义的操作组的示例：
------
#### [ Function details ]
```
HTTP/1.1 200
x-amzn-bedrock-agent-content-type: application/json
x-amz-bedrock-agent-session-id: session0
Content-type: application/json
{
"returnControl": {
"invocationInputs": [{
"functionInvocationInput": {
"agentId": "AGENTID",
"collaboratorName": "WeatherAgent"
"actionGroup": "WeatherAPIs",
"function": "getWeather",
"parameters": [
{
"name": "location",
"type": "string",
"value": "seattle"
},
{
"name": "date",
"type": "string",
"value": "2024-09-15"
}
]
}
}],
"invocationId": "79e0feaa-c6f7-49bf-814d-b7c498505172"
}
}
```
------
#### [ OpenAPI Schema ]
```
HTTP/1.1 200
x-amzn-bedrock-agent-content-type: application/json
x-amz-bedrock-agent-session-id: session0
Content-type: application/json
{
"invocationInputs": [{
"apiInvocationInput": {
"actionGroup": "WeatherAPIs",
"agentId": "AGENTID",
"collaboratorName": "WeatherAgent"
"apiPath": "/get-weather",
"httpMethod": "get",
"parameters": [
{
"name": "location",
"type": "string",
"value": "seattle"
},
{
"name": "date",
"type": "string",
"value": "2024-09-15"
}
]
}
}],
"invocationId": "337cb2f6-ec74-4b49-8141-00b8091498ad"
}
```
------
主管代理的调用者会将 `sessionState` 字段中的结果发送回主管代理，并附上相应的 `agentId`，以便将其传播给正确的代理协作者。
------
#### [ Function details ]
```
POST https://bedrock-agent-runtime.us-east-1.amazonaws.com/agents/AGENT12345/agentAliases/TSTALIASID/sessions/abb/text
{
"enableTrace": true,
"sessionState": {
"invocationId": "79e0feaa-c6f7-49bf-814d-b7c498505172",
"returnControlInvocationResults": [{
"functionResult": {
"agentId": "AGENTID",
"actionGroup": "WeatherAPIs",
"function": "getWeather",
"responseBody": {
"TEXT": {
"body": "It's rainy in Seattle today."
}
}
}
}]
}
}
```
------
#### [ OpenAPI Schema ]
```
POST https: //bedrock-agent-runtime.us-east-1.amazonaws.com/agents/AGENT12345/agentAliases/TSTALIASID/sessions/abb/text
{
"enableTrace": true,
"sessionState": {
"invocationId": "337cb2f6-ec74-4b49-8141-00b8091498ad",
"returnControlInvocationResults": [{
"apiResult": {
"agentId": "AGENTID",
"actionGroup": "WeatherAPIs",
"httpMethod": "get",
"apiPath": "/get-weather",
"responseBody": {
"application/json": {
"body": "It's rainy in Seattle today."
}
}
}
}]
}
}
```
------