Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Restituzione del controllo allo sviluppatore dell’agente inviando le informazioni richieste in una risposta InvokeAgent
Anziché inviare le informazioni che l’agente ha ottenuto dall’utente a una funzione Lambda per l’adempimento, puoi scegliere di restituire il controllo allo sviluppatore dell’agente inviando le informazioni nella risposta [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). È possibile configurare la restituzione del controllo allo sviluppatore dell’agente durante la creazione o l’aggiornamento di un gruppo di operazioni. Tramite l’API, puoi specificare `RETURN_CONTROL` come valore `customControl` nell’oggetto `actionGroupExecutor` in una richiesta [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentActionGroup.html) o [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentActionGroup.html). Per ulteriori informazioni, consulta [Aggiunta di un gruppo di operazioni all’agente in Amazon Bedrock](agents-action-add.md).
Se configuri la restituzione del controllo per un gruppo di operazioni e se l’agente stabilisce che deve chiamare un’azione in tale gruppo, i dettagli dell’API o della funzione richiesti all’utente verranno restituiti nel campo `invocationInputs` della risposta [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), insieme a un valore `invocationId` univoco. A questo punto puoi effettuare le seguenti operazioni:
+ Configurare l’applicazione per invocare l’API o la funzione che hai definito, a condizione di fornire le informazioni restituite in `invocationInputs`.
+ Inviare i risultati dell’invocazione dell’applicazione in un’altra richiesta [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), nel campo `sessionState`, per fornire un contesto all’agente. È necessario utilizzare gli stessi `invocationId` e `actionGroup` restituiti nella risposta [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). Queste informazioni possono essere utilizzate come contesto per un’ulteriore orchestrazione, inviate in post-elaborazione affinché l’agente formatti una risposta o utilizzate direttamente nella risposta dell’agente all’utente.
**Nota**
Se includi `returnControlInvocationResults` nel campo `sessionState`, il campo `inputText` verrà ignorato.
Per informazioni su come configurare la restituzione del controllo allo sviluppatore dell’agente durante la creazione del gruppo di operazioni, consulta [Aggiunta di un gruppo di operazioni all’agente in Amazon Bedrock](agents-action-add.md).
## Esempio di restituzione del controllo allo sviluppatore dell’agente
Ad esempio potrebbero essere presenti i seguenti gruppi di operazioni:
+ Un gruppo di operazioni `PlanTrip` con un’azione `suggestActivities` che aiuta gli utenti a trovare le attività da svolgere durante un viaggio. La `description` di questa azione riporta `This action suggests activities based on retrieved weather information`.
+ Un gruppo di operazioni `WeatherAPIs` con un’azione `getWeather` che aiuta l’utente a consultare le condizioni meteorologiche di una località specifica. I parametri dell’azione richiesti sono `location` e `date`. Il gruppo di operazioni è configurato in modo da restituire il controllo allo sviluppatore dell’agente.
Di seguito è riportata una sequenza ipotetica che potrebbe verificarsi:
1. L’utente pone all’agente la seguente domanda: **What should I do today?** Questa query viene inviata nel campo `inputText` di una richiesta [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. L’agente riconosce che l’azione `suggestActivities` deve essere invocata ma, data la descrizione, prevede di dover prima invocare l’azione `getWeather` come contesto per contribuire all’adempimento dell’azione `suggestActivities`.
1. L’agente sa che la `date` corrente è `2024-09-15`, ma per scoprire le condizioni meteorologiche ha bisogno della `location` dell’utente come parametro obbligatorio. Quindi, si rivolge nuovamente all’utente ponendo la domanda “Dove ti trovi?”
1. L’utente risponde **Seattle**.
1. L’agente restituisce i parametri per `getWeather` nella seguente risposta [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) (seleziona una scheda per consultare gli esempi di un gruppo di operazioni definito con quel metodo):
------
#### [ 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. L’applicazione è configurata per utilizzare questi parametri allo scopo di ottenere le condizioni meteorologiche di `seattle` in data `2024-09-15`. Viene determinato che il tempo è piovoso.
1. Questi risultati vengono inviati nel campo `sessionState` di un’altra richiesta [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), utilizzando gli stessi `invocationId`, `actionGroup` e `function` della risposta precedente. Seleziona una scheda per consultare esempi di un gruppo di operazioni definito con tale metodo:
------
#### [ 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. L’agente prevede di dover chiamare l’azione `suggestActivities`. Basandosi sul contesto secondo cui quel giorno pioverà, nella risposta suggerisce all’utente attività al chiuso anziché all’aperto.
### Esempio di restituzione del controllo all’agente collaboratore
Se utilizzi la [collaborazione multiagente](agents-multi-agent-collaboration.md) e un agente collaboratore sceglie di restituire il controllo inviando le informazioni nella risposta [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), le informazioni vengono restituite nella risposta dell’agente supervisore con gli identificatori aggiuntivi `agentId` e `collaboratorName`. Seleziona una scheda per consultare esempi di un gruppo di operazioni definito con tale metodo:
------
#### [ 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"
}
```
------
L’invoker dell’agente supervisore invia i risultati del campo `sessionState` all’agente supervisore con i risultati `agentId` corrispondenti, affinché vengano propagati all’agente collaboratore giusto.
------
#### [ 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."
}
}
}
}]
}
}
```
------