Tracciamento del comportamento dell’agente Test dell'agente

Test e risoluzione dei problemi relativi al comportamento dell’agente

Dopo aver creato un agente, avrai una bozza di lavoro. La bozza di lavoro è una versione dell'agente da utilizzare per costruire l'agente in modo iterativo Ogni volta che apporti modifiche al tuo agente, la bozza di lavoro viene aggiornata. Quando ritieni che le configurazioni del tuo agente siano soddisfacenti, puoi creare una versione, ovvero uno snapshot del tuo agente, e un alias, che rimanda alla versione. Puoi quindi distribuire l’agente nelle tue applicazioni chiamando l’alias. Per ulteriori informazioni, consulta Implementazione e utilizzo di un agente di Amazon Bedrock nell’applicazione.

Nell’elenco seguente viene spiegato come testare l’agente:

Nella console Amazon Bedrock, apri la finestra di test laterale e invii l’input a cui il tuo agente dovrà rispondere. Puoi selezionare la bozza di lavoro o una versione che hai creato.
Nell’API, la bozza di lavoro è la versione DRAFT. Invia l’input al tuo agente utilizzando InvokeAgent con l’alias di test o un alias diverso, TSTALIASID, che punti a una versione statica. Prima di poter testare il tuo agente, devi prepararlo chiamando PrepareAgent.

Tracciamento del comportamento dell’agente

Per aiutarti a risolvere i problemi di comportamento del tuo agente, Agent per Amazon Bedrock offre la possibilità di visualizzare la traccia durante una sessione con l’agente. La traccia mostra il processo di ragionamento dell’agente nei dettagli. Per ulteriori informazioni sulla traccia, consulta Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace.

Test dell'agente

Di seguito è riportata la procedura per testare l’agente. Scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:

Console

Per testare un agente

Accedi alla Console di gestione AWS con un’identità IAM che disponga delle autorizzazioni per utilizzare la console Amazon Bedrock. Quindi, apri la console Amazon Bedrock all’indirizzo https://console.aws.amazon.com/bedrock.
Seleziona Agenti nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione Agenti.
Nella sezione Agenti, seleziona il link relativo all’agente che desideri testare dall’elenco degli agenti.
La finestra Test viene visualizzata in un riquadro sulla destra.

Nota
Se la finestra Test è chiusa, puoi riaprirla selezionando Test nella parte superiore della pagina dei dettagli dell’agente o in qualsiasi pagina al suo interno.
Dopo aver creato un agente, è necessario inserire le modifiche nella bozza di lavoro preparandola in uno dei seguenti modi:
- Nella finestra Test, seleziona Prepara.
- Nella pagina Bozza di lavoro, seleziona Prepara nella parte superiore della pagina.
Nota
Ogni volta che aggiorni la bozza di lavoro, devi preparare l’agente in modo che includa le ultime modifiche. Come best practice, consigliamo di controllare sempre l’ora dell’Ultima preparazione dell’agente nella sezione Panoramica degli agenti della pagina Bozza di lavoro, per verificare che il test dell’agente sia eseguito con le configurazioni più recenti.
Per scegliere un alias e la versione associata da testare, utilizza il menu a discesa nella parte superiore della finestra Test. Per impostazione predefinita, è selezionata la combinazione TestAlias: Bozza di lavoro.
(Facoltativo) Per selezionare Throughput assegnato come alias, il testo sotto l’alias di test selezionato indicherà Utilizzo di ODT o Utilizzo di PT. Per creare un modello Throughput assegnato, seleziona Modifica. Per ulteriori informazioni, consulta Aumenta la capacità di invocazione del modello con Provisioned Throughput in Amazon Bedrock.
(Facoltativo) Per utilizzare un prompt da Gestione prompt, seleziona l’icona delle opzioni ( ) nella finestra del messaggio e scegli Importa prompt. Seleziona il prompt e la versione. Immetti i valori per le variabili di prompt nella sezione Valori delle variabili di test. Per ulteriori informazioni sui prompt in Gestione prompt, consulta Creare e archiviare prompt riutilizzabili con Gestione dei prompt in Amazon Bedrock.
Per testare l’agente, inserisci un messaggio e scegli Esegui. In attesa che la risposta venga generata o dopo che è stata generata, hai a disposizione le seguenti opzioni:
- Per visualizzare i dettagli di ogni fase del processo di orchestrazione dell’agente, inclusi il prompt, le configurazioni di inferenza e il processo di ragionamento dell’agente per ogni fase e l’utilizzo dei relativi gruppi di operazioni e knowledge base, seleziona Mostra traccia. La traccia viene aggiornata in tempo reale, in modo da poterla visualizzare prima che venga restituita la risposta. Per espandere o comprimere le tracce relative alle singole fasi, seleziona una freccia accanto a ciascuna di esse. Per ulteriori informazioni sulla finestra Traccia e sui dettagli visualizzati, consulta Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace.
- Se l’agente invoca una knowledge base, la risposta contiene note a piè di pagina. Per visualizzare il link all’oggetto S3 contenente le informazioni citate per una parte specifica della risposta, seleziona la nota a piè di pagina pertinente.
- Se imposti l’agente in modo che restituisca il controllo anziché utilizzare una funzione Lambda per gestire il gruppo di operazioni, la risposta conterrà l’operazione prevista e i relativi parametri. Fornisci un esempio di valore di output dall’API o dalla funzione per l’operazione, quindi scegli Invia per generare una risposta dell’agente. Per un esempio, vedi le immagini seguenti.
Nella finestra Test puoi eseguire le seguenti operazioni:
- Per avviare una nuova conversazione con l’agente, seleziona l’icona aggiornamento.
- Per visualizzare la finestra Traccia, seleziona l’icona espansione. Per chiudere la finestra Traccia, seleziona l’icona riduzione.
- Per chiudere la finestra Test, seleziona l’icona freccia destra.

È possibile abilitare o disabilitare gruppi di operazioni e knowledge base. Utilizza questa funzionalità per risolvere i problemi relativi all’agente isolando i gruppi di operazioni o le knowledge base che devono essere aggiornati valutandone il comportamento con impostazioni diverse.

Per abilitare un gruppo di operazioni o una knowledge base

Accedi alla Console di gestione AWS con un’identità IAM che disponga delle autorizzazioni per utilizzare la console Amazon Bedrock. Quindi, apri la console Amazon Bedrock all’indirizzo https://console.aws.amazon.com/bedrock.
Seleziona Agenti nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione Agenti.
Nella sezione Agenti, seleziona il link relativo all’agente che desideri testare dall’elenco degli agenti.
Nella sezione Bozza di lavoro della pagina dei dettagli dell’agente, seleziona il collegamento per la bozza di lavoro.
Nella sezione Gruppi di operazioni o Knowledge base, passa il mouse sopra lo Stato del gruppo di operazioni di cui desideri modificare lo stato.
Viene visualizzato un pulsante di modifica. Seleziona l’icona di modifica, quindi scegli dal menu a discesa se lo stato del gruppo di operazioni o della knowledge base deve essere Abilitato o Disabilitato.
Se lo stato di un gruppo di operazioni è Disabilitato, l’agente non utilizza tale gruppo. Se lo stato di una knowledge base è Disabilitato, l’agente non utilizza tale knowledge base. Abilita o disabilita i gruppi di operazioni o le knowledge base, quindi utilizza la finestra Test per risolvere i problemi del tuo agente.
Seleziona Prepara per applicare le modifiche apportate all’agente prima di testarlo.

API

Per gli agenti creati after il 31 marzo 2025:

Se hai creato il tuo agente nella console, lo streaming è abilitato per impostazione predefinita. Puoi disabilitare lo streaming in qualsiasi momento.
Assicurati che il ruolo di esecuzione Agente includa l’autorizzazione bedrock:InvokeModelWithResponseStream per il modello di agente configurato.

Prima di testare il tuo agente per la prima volta, devi impacchettarlo con le modifiche alla bozza di lavoro inviando una richiesta PrepareAgent con un endpoint in fase di compilazione di Agent per Amazon Bedrock. Includi agentId nella richiesta. Le modifiche si applicano alla versione DRAFT, a cui fa riferimento l’alias TSTALIASID.


    def prepare_agent(self, agent_id):
        """
        Creates a DRAFT version of the agent that can be used for internal testing.

        :param agent_id: The unique identifier of the agent to prepare.
        :return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
        """
        try:
            prepared_agent_details = self.client.prepare_agent(agentId=agent_id)
        except ClientError as e:
            logger.error(f"Couldn't prepare agent. {e}")
            raise
        else:
            return prepared_agent_details

Per ulteriori informazioni, consulta Agent per Amazon Bedrock.

Nota

Ogni volta che aggiorni la bozza di lavoro, devi preparare l’agente in modo che includa le ultime modifiche. Come best practice, ti consigliamo di inviare una richiesta GetAgent (consulta il link per i formati di richiesta e risposta e i dettagli sui campi) con un endpoint in fase di compilazione di Agent per Amazon Bedrock e di controllare l’ora di preparedAt, per verificare che il test dell’agente sia eseguito con le configurazioni più recenti.

Per testare il tuo agente, inviagli una richiesta InvokeAgent. Per il codice di esempio, consulta Invocazione di un agente dalla propria applicazione.

Nota

La AWS CLI non supporta InvokeAgent.

La richiesta include i campi indicati di seguito:

Compila almeno i seguenti campi obbligatori:

Campo	Breve descrizione
agentId	ID dell’agente
agentAliasId	ID dell’alias. Utilizza `TSTALIASID` per invocare la versione `DRAFT`
sessionId	ID alfanumerico della sessione (2-100 caratteri)
inputText	Prompt dell’utente da inviare all’agente

I seguenti campi sono facoltativi:

Campo	Breve descrizione
enableTrace	Specifica `TRUE` per visualizzare la traccia.
endSession	Specifica `TRUE` per terminare la sessione con l’agente dopo questa richiesta.
sessionState	Include il contesto che influisce sul comportamento dell’agente o delle knowledge base collegate all’agente. Per ulteriori informazioni, consulta Contesto della sessione dell’agente di controllo.
streamingConfigurations	Include configurazioni per la risposta in streaming. Per abilitare lo streaming, imposta `streamFinalResponse` su `TRUE`.

La risposta viene restituita in un flusso di eventi. Ogni evento contiene un chunk, che contiene parte della risposta nel campo bytes e deve essere decodificata. È inoltre possibile che vengano restituiti i seguenti oggetti:

Se l’agente ha eseguito una query su una knowledge base, chunk include anche citations.
Se lo streaming è abilitato e il guardrail è configurato per l’agente, la risposta viene generata negli intervalli di caratteri specificati per l’intervallo di guardrail. Per impostazione predefinita, l’intervallo è impostato su 50 caratteri.
Se hai abilitato una traccia, viene restituito anche un oggetto trace. In caso di errore, viene restituito un campo con il messaggio di errore. Per ulteriori informazioni su come leggere la traccia, consulta Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace.

Se configuri il gruppo di operazioni in modo che non utilizzi una funzione Lambda, nel campo returnControl viene restituito un oggetto ReturnControlPayload. La struttura generale dell’oggetto ReturnControlPayload è la seguente:


{
    "invocationId": "string",
    "invocationInputs": [
        ApiInvocationInput or FunctionInvocationInput,
        ...
    ]
}

Ogni membro dell’elenco di invocationInputs è uno dei seguenti:

In base all’input dell’utente, deve essere chiamato un oggetto ApiInvocationInput contenente l’operazione API prevista dall’agente, oltre ai parametri e ad altre informazioni che si ottengono dall’utente per soddisfare l’API. La struttura di un oggetto ApiInvocationInput è la seguente:


{
    "actionGroup": "string",
    "apiPath": "string",
    "httpMethod": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "requestBody": {
        <content-type>: {
            "properties": [
                {
                    "name": "string",
                    "type": "string",
                    "value": "string"
                }
            ]
        }
    }
}

In base all’input dell’utente, deve essere chiamato un oggetto FunctionInvocationInput contenente la funzione prevista dall’agente, oltre ai parametri per quella funzione che si ottengono dall’utente. La struttura di FunctionInvocationInput è la seguente:
```
{
    "actionGroup": "string",
    "function": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        }
    ]
}
```

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Gestione delle richieste di strumenti per l’utilizzo del computer da parte degli agenti durante le conversazioni

Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace