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

# Conversare con un flusso Amazon Bedrock
<a name="flows-multi-turn-invocation"></a>

**Nota**  
La conversazione multi-turno di Amazon Bedrock Flows è in versione di anteprima per Amazon Bedrock ed è soggetta a modifiche.

La conversazione a più turni di Amazon Bedrock Flows consente back-and-forth conversazioni dinamiche tra utenti e flussi, simili a un dialogo naturale. Quando un nodo agente richiede chiarimenti o contesto aggiuntivo, può mettere in pausa in modo intelligente l’esecuzione del flusso e chiedere all’utente informazioni specifiche. Si determina così un’esperienza più interattiva e accurata rispetto al contesto, poiché il nodo può adattare il proprio comportamento in base alle risposte degli utenti. Ad esempio, se una richiesta iniziale dell’utente è ambigua o incompleta, il nodo può porre domande successive per raccogliere i dettagli necessari. Dopo che l’utente ha inviato le informazioni richieste, il flusso riprende senza problemi l’esecuzione con gli input arricchiti, garantendo risultati più accurati e pertinenti. Questa funzionalità è particolarmente utile per scenari complessi in cui una singola interazione potrebbe non essere sufficiente per comprendere e soddisfare appieno le esigenze dell’utente.

**Topics**
+ [Come elaborare una conversazione multi-turno in un flusso](#flows-multi-turn-invocation-how)
+ [Creazione ed esecuzione di un flusso di esempio](#flows-multi-turn-invocation-example-flow)

## Come elaborare una conversazione multi-turno in un flusso
<a name="flows-multi-turn-invocation-how"></a>

Per utilizzare una conversazione multi-turno in un flusso, è necessario un [nodo agente](flows-nodes.md#flows-nodes-agent) collegato a un agente di Amazon Bedrock. Durante l’esecuzione di un flusso, si ha una conversazione multi-turno quando l’agente necessita di ulteriori informazioni dall’utente prima di poter continuare. Questa sezione descrive un flusso che utilizza un agente con le seguenti istruzioni:

```
You are a playlist creator for a radio station. 
When asked to create a playlist, ask for the number of songs,
the genre of music, and a theme for the playlist.
```

Per informazioni sulla creazione di un agente, consulta [Automazione delle attività nella propria applicazione utilizzando agenti IA](agents.md). 

### Fase 1. Avvio del flusso
<a name="flows-multi-turn-invocation-start-flow"></a>

Si avvia un flusso chiamando l'[InvokeFlow](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeFlow.html)operazione. Includi il contenuto iniziale che desideri inviare al flusso. Nell’esempio seguente, il campo `document` contiene una richiesta *Crea una playlist*. Ogni conversazione ha un identificatore univoco (*ID di esecuzione*) che identifica la conversazione all’interno del flusso. Per ottenere l’ID di esecuzione, non invii il campo `executionID` durante la prima chiamata a `InvokeFlow`. La risposta di `InvokeFlow` include l’ID di esecuzione. Nel codice, usa l’identificatore per tenere traccia di più conversazioni e identificare una conversazione nelle successive chiamate all’operazione `InvokeFlow`. 

Di seguito è riportato un esempio JSON di richiesta `InvokeFlow`.

```
{
  "flowIdentifier": "XXXXXXXXXX",
  "flowAliasIdentifier": "YYYYYYYYYY",
  "inputs": [
    {
      "content": {
        "document": "Create a playlist."
      },
      "nodeName": "FlowInputNode",
      "nodeOutputName": "document"
    }
  ]
}
```

### Fase 2. Recupero delle richieste dell’agente
<a name="flows-multi-turn-invocation-retrieve-requests"></a>

Se il nodo agente nel flusso decide che gli servono ulteriori informazioni da parte dell’utente, lo streaming di risposte (`responseStream`) provenienti da `InvokeFlow` include un oggetto evento `FlowMultiTurnInputRequestEvent`. L’evento contiene le informazioni richieste nel campo `content` (`FlowMultiTurnInputContent`). Nell’esempio seguente, la richiesta nel campo `document` riguarda informazioni sul numero di brani, sul genere musicale e sul tema della playlist. Nel codice, è quindi necessario acquisire tali informazioni dall’utente.

Di seguito è riportato un esempio dell’oggetto JSON `FlowMultiTurnInputRequestEvent`.

```
{
    "nodeName": "AgentsNode_1",
    "nodeType": "AgentNode",
    "content": {
        "document": "Certainly! I'd be happy to create a playlist for you. To make sure it's tailored to your preferences, could you please provide me with the following information:
        1. How many songs would you like in the playlist?
        2. What genre of music do you prefer? 
        3. Is there a specific theme or mood you'd like for the playlist? Once you provide these details, I'll be able to create a customized playlist just for you."
    }
}
```

Poiché il flusso non può continuare finché non si riceve ulteriore input, il flusso emette anche un evento `FlowCompletionEvent`. Un flusso emette sempre `FlowMultiTurnInputRequestEvent` prima di `FlowCompletionEvent`. Se il valore di `completionReason` nell’evento `FlowCompletionEvent` è `INPUT_REQUIRED`, il flusso necessita di ulteriori informazioni prima di poter continuare. 

Di seguito è riportato un esempio dell’oggetto JSON `FlowCompletionEvent`.

```
{
    "completionReason": "INPUT_REQUIRED"
}
```

### Fase 3. Invio della risposta dell’utente al flusso
<a name="flows-multi-turn-invocation-continue"></a>

Invia di nuovo la risposta dell’utente al flusso chiamando nuovamente l’operazione `InvokeFlow`. Assicurati di includere `executionId` nella conversazione.

Di seguito è riportato un esempio JSON per la richiesta `InvokeFlow`. Il campo `document` contiene la risposta dell’utente.

```
{
  "flowIdentifier": "AUS7BMHXBE",
  "flowAliasIdentifier": "4KUDB8VBEF",
  "executionId": "b6450554-f8cc-4934-bf46-f66ed89b60a0",
  "inputs": [
    {
      "content": {
        "document": "1. 5 songs 2. Welsh rock music 3. Castles"
      },
      "nodeName": "AgentsNode_1",
      "nodeInputName": "agentInputText"
    }
  ]
}
```

Se necessita di altre informazioni, il flusso crea ulteriori eventi `FlowMultiTurnInputRequestEvent`.

### Fase 4. Fine del flusso
<a name="flows-multi-turn-invocation-end"></a>

Quando non sono necessarie ulteriori informazioni, il flusso emette un evento `FlowOutputEvent` che contiene la risposta finale.

Di seguito è riportato un esempio dell’oggetto JSON `FlowOutputEvent`.

```
{
    "nodeName": "FlowOutputNode",
    "content": {
        "document": "Great news! I've created a 5-song Welsh rock playlist centered around the theme of castles. 
        Here's the playlist I've put together for you: Playlist Name: Welsh Rock Castle Anthems 
        Description: A 5-song Welsh rock playlist featuring songs about castles 
        Songs: 
        1. Castell y Bere - Super Furry Animals 
        2. The Castle - Manic Street Preachers 
        3. Caerdydd (Cardiff Castle) - Stereophonics 
        4. Castell Coch - Catatonia 
        5. Chepstow Castle - Feeder 
        This playlist combines Welsh rock bands with songs that reference castles or specific Welsh castles. 
        Enjoy your castle-themed Welsh rock music experience!"
     }
}
```

Il flusso emette anche un evento `FlowCompletionEvent`. Il valore di `completionReason` è `SUCCESS`. 

Di seguito è riportato un esempio dell’oggetto JSON `FlowCompletionEvent`.

```
{
    "completionReason": "SUCCESS"
}
```

Il seguente diagramma di sequenza mostra le fasi di un flusso multi-turno.

![\[Fasi del flusso per una conversazione multi-turno.\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/images/flows/flows-multi-turn-steps.png)


## Creazione ed esecuzione di un flusso di esempio
<a name="flows-multi-turn-invocation-example-flow"></a>

In questo esempio, creerai un flusso che utilizza un agente per creare playlist per una stazione radio. L’agente pone domande chiarificatrici per stabilire il numero di brani, il genere musicale e il tema della playlist.

**Per creare il flusso**

1. Crea un agente nella console Amazon Bedrock seguendo le istruzioni disponibili in [Creazione e configurazione manuale dell’agente](agents-create.md). 
   + Per la fase *2.d*, inserisci **You are a playlist creator for a radio station. When asked to create a playlist, ask for the number of songs, the genre of music, and a theme for the playlist.**.
   + Per la fase *2.e*, in **Input dell’utente**, scegli **Abilitato**. In questo modo l’agente può chiedere ulteriori informazioni, se necessario.

1. Crea il flusso seguendo le istruzioni in [Creare e progettare un flusso in Amazon Bedrock](flows-create.md). Assicurati che il flusso abbia un nodo di input, un nodo agente e un nodo di output. 

1. Collega il nodo agente all’agente creato nella fase 1. Il risultato sarà simile all’immagine seguente.  
![\[Conversazione multi-turno del flusso\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/images/flows/flows-multi-turn.png)

1. Esegui il flusso nella console Amazon Bedrock. Per i test, puoi tracciare le fasi eseguite dal flusso. Per ulteriori informazioni, consulta [Testare un flusso in Amazon Bedrock](flows-test.md).

Il seguente esempio di codice Python mostra come utilizzare il flusso. 

Per eseguire il codice, specifica quanto segue:
+ `region_name`— La AWS regione in cui si esegue il flusso.
+ `FLOW_ID`: l’ID del flusso.
+ `FLOW_ALIAS_ID`: l’ID alias del flusso.

Per informazioni su come ottenere il IDs, vedere[Visualizzare informazioni sui flussi in Amazon Bedrock](flows-view.md). Il codice effettua una richiesta iniziale da inviare al flusso e chiede ulteriore input in base alle esigenze del flusso. Il codice non gestisce altre richieste dell'agente, come le richieste di chiamata a AWS Lambda funzioni. Per ulteriori informazioni, consulta [Come funziona Agent per Amazon Bedrock](agents-how.md). Durante l’esecuzione, il codice genera oggetti `FlowTraceEvent` che è possibile utilizzare per tracciare il percorso dall’input alla risposta restituita dal flusso. Per ulteriori informazioni, consulta [Tenere traccia di ciascuna fase del flusso visualizzandone la traccia in Amazon BedrockTenere traccia di ciascuna fase del flusso visualizzandone la traccia](flows-trace.md).

```
"""
Runs an Amazon Bedrock flow and handles muli-turn interaction for a single conversation.

"""
import logging
import boto3
import botocore



import botocore.exceptions

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


def invoke_flow(client, flow_id, flow_alias_id, input_data, execution_id):
    """
    Invoke an Amazon Bedrock flow and handle the response stream.

    Args:
        client: Boto3 client for Amazon Bedrock agent runtime
        flow_id: The ID of the flow to invoke
        flow_alias_id: The alias ID of the flow
        input_data: Input data for the flow
        execution_id: Execution ID for continuing a flow. Use the value None on first run.

    Returns:
        Dict containing flow_complete status, input_required info, and execution_id
    """

    response = None
    request_params = None

    if execution_id is None:
        # Don't pass execution ID for first run.
        request_params = {
            "flowIdentifier": flow_id,
            "flowAliasIdentifier": flow_alias_id,
            "inputs": [input_data],
            "enableTrace": True
        }
    else:
        request_params = {
            "flowIdentifier": flow_id,
            "flowAliasIdentifier": flow_alias_id,
            "executionId": execution_id,
            "inputs": [input_data],
            "enableTrace": True
        }

    response = client.invoke_flow(**request_params)
    if "executionId" not in request_params:
        execution_id = response['executionId']

    input_required = None
    flow_status = ""

    # Process the streaming response
    for event in response['responseStream']:
        # Check if flow is complete.
        if 'flowCompletionEvent' in event:
            flow_status = event['flowCompletionEvent']['completionReason']

        # Check if more input us needed from user.
        elif 'flowMultiTurnInputRequestEvent' in event:
            input_required = event

        # Print the model output.
        elif 'flowOutputEvent' in event:
            print(event['flowOutputEvent']['content']['document'])

        elif 'flowTraceEvent' in event:
            logger.info("Flow trace:  %s", event['flowTraceEvent'])

    return {
        "flow_status": flow_status,
        "input_required": input_required,
        "execution_id": execution_id
    }


if __name__ == "__main__":

    session = boto3.Session(profile_name='default', region_name='YOUR_FLOW_REGION')
    bedrock_agent_client = session.client('bedrock-agent-runtime')
    
    # Replace these with your actual flow ID and alias ID
    FLOW_ID = 'YOUR_FLOW_ID'
    FLOW_ALIAS_ID = 'YOUR_FLOW_ALIAS_ID'


    flow_execution_id = None
    finished = False

    # Get the intial prompt from the user.
    user_input = input("Enter input: ")

    flow_input_data = {
        "content": {
            "document": user_input
        },
        "nodeName": "FlowInputNode",
        "nodeOutputName": "document"
    }

    logger.info("Starting flow %s", FLOW_ID)

    try:
        while not finished:
            # Invoke the flow until successfully finished.

            result = invoke_flow(
                bedrock_agent_client, FLOW_ID, FLOW_ALIAS_ID, flow_input_data, flow_execution_id)
            status = result['flow_status']
            flow_execution_id = result['execution_id']
            more_input = result['input_required']
            if status == "INPUT_REQUIRED":
                # The flow needs more information from the user.
                logger.info("The flow %s requires more input", FLOW_ID)
                user_input = input(
                    more_input['flowMultiTurnInputRequestEvent']['content']['document'] + ": ")
                flow_input_data = {
                    "content": {
                        "document": user_input
                    },
                    "nodeName": more_input['flowMultiTurnInputRequestEvent']['nodeName'],
                    "nodeInputName": "agentInputText"

                }
            elif status == "SUCCESS":
                # The flow completed successfully.
                finished = True
                logger.info("The flow %s successfully completed.", FLOW_ID)

    except botocore.exceptions.ClientError as e:
        print(f"Client error: {str(e)}")
        logger.error("Client error: %s", {str(e)})

    except Exception as e:
        print(f"An error occurred: {str(e)}")
        logger.error("An error occurred: %s", {str(e)})
        logger.error("Error type: %s", {type(e)})
```