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à.

# Contesto della sessione dell’agente di controllo
<a name="agents-session-state"></a>

Per un maggiore controllo del contesto della sessione, puoi modificare l’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) nell’agente. L’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) contiene informazioni che possono essere gestite a turno (richieste e risposte [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) separate). È possibile utilizzare queste informazioni per fornire un contesto di conversazione all’agente durante le conversazioni con gli utenti.

Il formato generale dell’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState) è il seguente.

```
{
    "sessionAttributes": {
        "<attributeName1>": "<attributeValue1>",
        "<attributeName2>": "<attributeValue2>",
        ...
    },
     "conversationHistory": {
          "messages": [{
              "role": "user | assistant",
              "content": [{
                  "text": "string"
              }]
          }],
               },
    "promptSessionAttributes": {
        "<attributeName3>": "<attributeValue3>",
        "<attributeName4>": "<attributeValue4>",
        ...
    },
    "invocationId": "string",
    "returnControlInvocationResults": [
        [ApiResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiResult.html) or [FunctionResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionResult.html),
        ...
    ],
    "knowledgeBases": [
       {
        "knowledgeBaseId": "string",
        "retrievalConfiguration": {
            "vectorSearchConfiguration": {
                "overrideSearchType": "HYBRID | SEMANTIC",
                "numberOfResults": int,
                "filter": [RetrievalFilter](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html) object
            }
        }
       },
       ...
    ]
}
```

Seleziona un argomento per scoprire di più sui campi dell’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_SessionState.html#bedrock-Type-agent-runtime_SessionState).

**Topics**
+ [Attributi della sessione e della sessione di prompt](#session-state-attributes)
+ [Esempio di attributi di sessione](#session-attribute-ex)
+ [Esempio di attributo di sessione prompt](#prompt-session-attribute-ex)
+ [Risultati dell’invocazione del gruppo di operazioni](#session-state-return-control)
+ [Configurazioni di recupero della knowledge base](#session-state-kb)

## Attributi della sessione e della sessione di prompt
<a name="session-state-attributes"></a>

Agent per Amazon Bedrock consente di definire i seguenti tipi di attributi contestuali che persistono su alcune parti di una sessione:
+ **sessionAttributes**: attributi che persistono durante una [sessione](advanced-prompts.md#advanced-prompts-terminology) tra un utente e un agente. Tutte le richieste [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) effettuate con lo stesso `sessionId` appartengono alla medesima sessione, purché il limite di tempo della sessione (`idleSessionTTLinSeconds`) non sia stato superato.
+ **conversationHistory**: per la collaborazione multiagente, accetta un contesto aggiuntivo per elaborare le richieste di runtime se `conversationalHistorySharing` è abilitato per un agente collaboratore. Per impostazione predefinita, questo campo viene creato automaticamente dall’agente supervisore quando si invoca l’agente collaboratore. Facoltativamente, puoi utilizzare questo campo per fornire un contesto aggiuntivo. Per ulteriori informazioni, consulta [Utilizzo della collaborazione multiagente con Agent per Amazon Bedrock](agents-multi-agent-collaboration.md).
+ **promptSessionAttributes**: attributi che persistono per un singolo [turno](advanced-prompts.md#advanced-prompts-terminology) (una chiamata [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 utilizzare il [segnaposto](prompt-placeholders.md) \$1prompt\$1session\$1attributes\$1 quando si modifica il modello di prompt di orchestrazione di base. Questo segnaposto verrà compilato in fase di runtime con gli attributi specificati nel campo `promptSessionAttributes`.

È possibile definire gli attributi dello stato della sessione in due occasioni diverse:
+ Quando configuri un gruppo di operazioni e [scrivi la funzione Lambda](agents-lambda.md), includi `sessionAttributes` o `promptSessionAttributes` nell’[evento di risposta](agents-lambda.md#agents-lambda-response) che viene restituito ad Amazon Bedrock.
+ Durante il runtime, quando invii 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), includi un oggetto `sessionState` nel corpo della richiesta per modificare dinamicamente gli attributi dello stato della sessione durante la conversazione.

## Esempio di attributi di sessione
<a name="session-attribute-ex"></a>

Nell’esempio indicato di seguito, utilizza un attributo di sessione per personalizzare un messaggio per l’utente.

1. Scrivi il codice dell’applicazione in modo da chiedere all’utente di fornire il proprio nome e la richiesta che desidera fare all’agente e per archiviare le risposte come variabili *<first\$1name>* e *<request>*.

1. Scrivi il codice dell’applicazione in modo da inviare 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) con il seguente corpo:

   ```
   {
       "inputText": "<request>",
       "sessionState": {
           "sessionAttributes": {
               "firstName": "<first_name>"
           }
       }
   }
   ```

1. Quando un utente utilizza l’applicazione e fornisce il proprio nome, il codice invia il nome come attributo di sessione e l’agente lo memorizza per la durata dell’intera [sessione](advanced-prompts.md#advanced-prompts-terminology).

1. Poiché gli attributi di sessione vengono inviati nell’[evento di input Lambda](agents-lambda.md#agents-lambda-input), è possibile fare riferimento a tali attributi in una funzione Lambda per un gruppo di operazioni. Ad esempio, se lo [schema API](agents-api-schema.md) dell’azione richiede un nome nel corpo della richiesta, puoi utilizzare l’attributo di sessione `firstName` quando scrivi la funzione Lambda per un gruppo di operazioni, in modo che quel campo venga compilato automaticamente quando si invia la richiesta API.

## Esempio di attributo di sessione prompt
<a name="prompt-session-attribute-ex"></a>

L’esempio generale riportato di seguito utilizza un attributo di sessione prompt per fornire all’agente un contesto temporale.

1. Scrivi il codice dell’applicazione in modo da archiviare la richiesta dell’utente in una variabile chiamata *<request>*.

1. Scrivi il codice dell’applicazione in modo da recuperare il fuso orario relativo alla posizione dell’utente se l’utente utilizza nella*<request>* una parola che indica un periodo di tempo (ad esempio “domani”) e archivialo in una variabile chiamata*<timezone>*.

1. Scrivi l’applicazione in modo da inviare 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) con il seguente corpo:

   ```
   {
       "inputText": "<request>",
       "sessionState": {
           "promptSessionAttributes": {
               "timeZone": "<timezone>"
           }
       }
   }
   ```

1. Se un utente utilizza una parola che indica il tempo relativo, il codice invia l’attributo della sessione di prompt `timeZone` e l’agente lo memorizza per l’intera la durata del [turno](advanced-prompts.md#advanced-prompts-terminology).

1. Ad esempio, se un utente chiede **I need to book a hotel for tomorrow**, il codice invia il relativo fuso orario all’agente, che può determinare la data esatta a cui “domani” fa riferimento.

1. L’attributo di sessione prompt può essere utilizzato nelle fasi indicate di seguito.
   + Se includi il [segnaposto](prompt-placeholders.md) \$1prompt\$1session\$1attributes\$1 nel modello di prompt di orchestrazione, il prompt di orchestrazione sull’FM include gli attributi di sessione prompt.
   + Gli attributi di sessione prompt vengono inviati nell’[evento di input Lambda](agents-lambda.md#agents-lambda-input) e possono essere utilizzati per compilare le richieste API o restituiti nella [risposta](agents-lambda.md#agents-lambda-response).

## Risultati dell’invocazione del gruppo di operazioni
<a name="session-state-return-control"></a>

Se hai configurato un gruppo di operazioni in modo da [restituire il controllo in una 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)](agents-returncontrol.md), puoi inviare i risultati dell’invocazione del gruppo in `sessionState` di una 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) successiva includendo i seguenti campi:
+ `invocationId`: questo ID deve corrispondere al’`invocationId` restituito nell’oggetto [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) nel campo `returnControl` 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).
+ `returnControlInvocationResults`: include i risultati ottenuti dall’invocazione dell’azione. Puoi configurare l’applicazione in modo da passare l’oggetto [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) per eseguire una richiesta API o chiamare una funzione definita dall’utente e fornire i risultati di tale azione qui. Ogni membro dell’elenco di `returnControlInvocationResults` è uno dei seguenti elementi:
  + Un oggetto [ApiResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiResult.html) contenente l’operazione API che l’agente ha previsto di dover chiamare in una sequenza [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) precedente e i risultati derivanti dall’invocazione dell’azione nei tuoi sistemi. Il formato generale è il seguente:

    ```
    {
        "actionGroup": "string",
        "agentId" : :string",
        "apiPath": "string",
        "confirmationState" : "CONFIRM | DENY",
        "httpMethod": "string",
        "httpStatusCode": integer,
        "responseBody": {
            "TEXT": {
                "body": "string"
            }
        }
    }
    ```
  + Una funzione [FunctionResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionResult.html) contenente l’operazione API che l’agente ha previsto di dover chiamare in una sequenza [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) precedente e i risultati derivanti dall’invocazione dell’azione nei tuoi sistemi. Il formato generale è il seguente:

    ```
    {
        "actionGroup": "string",
        "agentId" : :string",
        "confirmationState" : "CONFIRM | DENY",
        "function": "string",
        "responseBody": {
            "TEXT": {
                "body": "string"
            }
        }
    }
    ```

I risultati forniti possono essere utilizzati come contesto per un’ulteriore orchestrazione, inviati in post-elaborazione affinché l’agente formatti una risposta o utilizzati direttamente nella risposta dell’agente all’utente.

## Configurazioni di recupero della knowledge base
<a name="session-state-kb"></a>

Per modificare la configurazione di recupero delle knowledge base collegate all’agente, includi il campo `knowledgeBaseConfigurations` con un elenco di configurazioni per ogni knowledge base di cui desideri specificare le configurazioni. Specificare il valore di `knowledgeBaseId`. Nel campo `vectorSearchConfiguration`, è possibile specificare le seguenti configurazioni di query (per ulteriori informazioni su queste configurazioni, consulta [Configurare e personalizzare la generazione di query e risposte](kb-test-config.md)):
+ **Tipo di ricerca**: indica se la knowledge base cerca solo gli embedding vettoriali (`SEMANTIC`) o sia gli embedding vettoriali che il testo non elaborato (`HYBRID`). Utilizza il campo `overrideSearchType`.
+ **Numero massimo di risultati recuperati**: il numero massimo di risultati del recupero della query da utilizzare nella risposta.
+ **Metadati e filtri**: filtri che è possibile configurare per filtrare i risultati in base agli attributi dei metadati nei file di origine dati.