本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 透過在 InvokeAgent 回應中傳送取得的資訊，將控制權傳回給代理程式開發人員
與其將代理程式從使用者那裡取得的資訊傳送到 Lambda 函數進行履行，您可以選擇改為透過 [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) 回應傳送資訊，將控制權還回給代理程式開發人員。您可以在建立或更新動作群組時，設定將控制權傳回給代理程式開發人員。透過 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` 物件中將 `RETURN_CONTROL` 指定為 `customControl` 值。如需詳細資訊，請參閱 [在 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`。然後，您可以執行下列作業：
+ 設定您的應用程式來調用您定義的 API 或函數，並提供 `invocationInputs` 中傳回的資訊。
+ 將應用程式調用的結果在另一個 [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. 您的應用程式已設定為使用這些參數，以取得日期為 `2024-09-15` 的 `seattle` 當地天氣。天氣預報顯示為下雨。
1. 您可以使用與上一個回應相同的 `invocationId`、`actionGroup` 和 `function`，在另一個 [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` 欄位中傳送這些結果。選取標籤以查看使用該方法定義的動作群組範例：
------
#### [ 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."
}
}
}
}]
}
}
```
------