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á.
# Retornar o controle ao desenvolvedor do agente enviando informações obtidas em uma resposta do 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 [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). É 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 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html) ou [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html). Para obter mais informações, consulte [Adicionar um grupo de ação ao agente no Amazon Bedrock](agents-action-add.md).
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 [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), 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 [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), no campo `sessionState`, para fornecer contexto ao agente. Use os mesmos `invocationId` e `actionGroup` que foram apresentados na resposta [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). 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](agents-action-add.md).
## 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 [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).
1. 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`.
1. 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?”.
1. O usuário responde **Seattle**.
1. O agente retorna os parâmetros de `getWeather` na seguinte resposta de [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) (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"
}
```
------
1. 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.
1. Você envia esses resultados no campo `sessionState` de outra solicitação [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), 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."
}
}
}
}]
}
}
```
------
1. 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 para retornar o controle ao agente colaborador
Se você estiver usando a [colaboração multiagente](agents-multi-agent-collaboration.md) e se um agente colaborador optar por retornar o controle enviando as informações na resposta [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), as informações serão exibidas na resposta do agente supervisor com os identificadores adicionais `agentId` e `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 campo `sessionState` de volta ao agente supervisor com o `agentId` correspondente 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."
}
}
}
}]
}
}
```
------