透過在 InvokeAgent 回應中傳送取得的資訊，將控制權傳回給代理程式開發人員 - Amazon Bedrock
傳回控制權給代理程式開發人員的範例

透過在 InvokeAgent 回應中傳送取得的資訊，將控制權傳回給代理程式開發人員

與其將代理程式從使用者那裡取得的資訊傳送到 Lambda 函數進行履行，您可以選擇改為透過 InvokeAgent 回應傳送資訊，將控制權還回給代理程式開發人員。您可以在建立或更新動作群組時，設定將控制權傳回給代理程式開發人員。透過 API，您可以在 CreateAgentActionGroup 或 UpdateAgentActionGroup 請求的 actionGroupExecutor 物件中將 RETURN_CONTROL 指定為 customControl 值。如需詳細資訊，請參閱 在 Amazon Bedrock 中將動作群組新增至您的代理程式。

如果您為動作群組設定傳回控制權，且代理程式判斷應呼叫此動作群組中的動作，則從使用者取得的 API 或函數詳細資訊將在 InvokeAgent 回應的 invocationInputs 欄位中傳回，連同唯一的 invocationId。然後，您可以執行下列作業：

  • 設定您的應用程式來調用您定義的 API 或函數，並提供 invocationInputs 中傳回的資訊。

  • 將應用程式調用的結果在另一個 InvokeAgent 請求的 sessionState 欄位中傳送，以提供內容給代理程式。您必須使用與 InvokeAgent 回應中傳回的相同 invocationId 和 actionGroup。此資訊可以用作進一步協同運作的內容、傳送至代理程式的後製處理以格式化回應，或直接用於代理程式對使用者的回應。

    注意

    如果您在 sessionState 欄位中包含 returnControlInvocationResults，則會忽略 inputText 欄位。

若要了解如何在建立動作群組時設定將控制權傳回給代理程式開發人員，請參閱在 Amazon Bedrock 中將動作群組新增至您的代理程式。

傳回控制權給代理程式開發人員的範例

例如，您可能有下列動作群組：

  • PlanTrip 動作群組，其 suggestActivities 動作可協助您的使用者在旅行期間尋找活動。此動作的 description 會顯示 This action suggests activities based on retrieved weather information。

  • WeatherAPIs 動作群組，其 getWeather 動作可協助使用者取得特定地點天氣資訊。動作的必要參數為 location 和 date。動作群組設定為將控制權傳回給代理程式開發人員。

以下是可能發生的假設序列：

  1. 使用者向您的代理程式發出以下查詢：What should I do today?。此查詢會在 InvokeAgent 請求的 inputText 欄位中傳送。

  2. 您的代理程式認為應該調用 suggestActivities 動作，但根據描述，預測它應該先調用 getWeather 動作做為內容，以協助完成 suggestActivities 動作。

  3. 代理程式知道目前 date 是 2024-09-15，但需要使用者的 location 作為取得天氣的必要參數。它會再次提示使用者「您位於哪裡？」這個問題。

  4. 使用者回應 Seattle。

  5. 代理程式會在下列 InvokeAgent 回應中傳回 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"
}

  6. 您的應用程式已設定為使用這些參數，以取得日期為 2024-09-15 的 seattle 當地天氣。天氣預報顯示為下雨。

  7. 您可以使用與上一個回應相同的 invocationId、actionGroup 和 function，在另一個 InvokeAgent 請求的 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."
                    }
                }
            }
        }]
    }
}

  8. 代理程式預測應該呼叫 suggestActivities 動作。它使用當天下雨的內容資訊，在回應中建議使用者進行室內活動，而不是戶外活動。

傳回控制項給協作者代理程式的範例

如果您使用多代理協同作業，且代理程式協作者選擇透過在 InvokeAgent 回應中傳送資訊來傳回控制項，則該資訊將隨主管代理程式回應一同傳回，並包含額外識別符 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."
                    }
                }
            }
        }]
    }
}