Devolva o controle ao agente desenvolvedor enviando informações extraídas em uma resposta InvokeAgent - Amazon Bedrock
Exemplo de retorno do controle ao desenvolvedor do agente

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Devolva o controle ao agente desenvolvedor enviando informações extraídas em uma resposta InvokeAgent

Em vez de enviar as informações que o agente obteve do usuário a uma função do Lambda para atendimento, é possível optar por retornar o controle ao desenvolvedor do agente enviando as informações na resposta InvokeAgent. É possível configurar o retorno do controle para o desenvolvedor do agente ao criar ou atualizar um grupo de ação. Por meio da API, especifique RETURN_CONTROL como o valor de customControl no objeto actionGroupExecutor em uma solicitação UpdateAgentActionGroup ou CreateAgentActionGroup. Para obter mais informações, consulte Adicionar um grupo de ação ao agente no Amazon Bedrock.

Se você configurar o retorno de controle para um grupo de ação e se o agente determinar que deve chamar uma ação nesse grupo de ação, os detalhes da API ou da função obtidos do usuário serão apresentados no campo invocationInputs da resposta InvokeAgent, com um invocationId exclusivo. Depois, será possível fazer o seguinte:

  • Configure a aplicação para invocar a API ou a função definida, desde que as informações sejam apresentadas em invocationInputs.

  • Envie os resultados da invocação da aplicação em outra solicitação InvokeAgent, no campo sessionState, para fornecer contexto ao agente. Use os mesmos invocationId e actionGroup que foram apresentados na resposta InvokeAgent. Essas informações podem ser usadas como contexto para orquestração adicional, enviadas ao pós-processamento para que o agente formate uma resposta ou usadas diretamente na resposta do agente ao usuário.

    nota

    Se você incluir returnControlInvocationResults no campo sessionState, o campo inputText será ignorado.

Para saber como configurar o retorno do controle ao desenvolvedor do agente ao criar o grupo de ação, consulte Adicionar um grupo de ação ao agente no Amazon Bedrock.

Exemplo de retorno do controle ao desenvolvedor do agente

Por exemplo, é possível ter os seguintes grupos de ação:

  • Um grupo de ação PlanTrip com uma ação suggestActivities que ajuda os usuários a encontrar atividades para realizar durante uma viagem. A description desta ação diz This action suggests activities based on retrieved weather information.

  • Um grupo de ação WeatherAPIs com uma ação getWeather que ajuda o usuário a obter a previsão de meteorologia para um local específico. Os parâmetros necessários são location e date. O grupo de ação está configurado para retornar o controle ao desenvolvedor do agente.

Veja uma sequência hipotética que pode ocorrer:

  1. O usuário envia um prompt ao agente com a seguinte consulta: What should I do today?, que é enviada no campo inputText de uma solicitação InvokeAgent.

  2. O agente reconhece que a ação suggestActivities deve ser invocada, mas, dada a descrição, prevê que deve primeiro invocar a ação getWeather como contexto para ajudar a atender à ação suggestActivities.

  3. O agente sabe que a date atual é 2024-09-15, mas precisa do location do usuário como um parâmetro necessário para obter a meteorologia. O agente envia um prompt ao usuário novamente com a pergunta “Onde você está localizado?”.

  4. O usuário responde Seattle.

  5. O agente retorna os parâmetros de getWeather na seguinte resposta de InvokeAgent (selecione uma guia para ver os exemplos de um grupo de ação definido com esse método):

    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. A aplicação está configurada para usar esses parâmetros para obter a previsão de meteorologia para seattle na data 2024-09-15. A previsão da meteorologia está determinada como chuvosa.

  7. Você envia esses resultados no campo sessionState de outra solicitação InvokeAgent, usando os mesmos invocationId, actionGroup e function como na resposta anterior. Selecione uma guia para ver exemplos de um grupo de ação definido com esse método:

    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. O agente prevê que deve chamar a ação suggestActivities. Ele usa o contexto de que está chuvoso naquele dia e sugere atividades internas, em vez de externas, ao usuário na resposta.

Exemplo de devolução do controle ao agente colaborador

Se você estiver usando a colaboração multiagente e se um agente colaborador optar por retornar o controle enviando as informações na InvokeAgentresposta, as informações serão retornadas na resposta do agente supervisor com identificadores adicionais e. agentId collaboratorName Selecione uma guia para ver exemplos de um grupo de ação definido com esse método:

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"
}

O invocador do agente supervisor envia os resultados no sessionState campo de volta ao agente supervisor com o correspondente agentId para que sejam propagados ao agente colaborador correto.

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."
                    }
                }
            }
        }]
    }
}