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à.
# 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](agents-deploy.md).
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 [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 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 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html).
## 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](trace-events.md).
## 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**
1. 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](https://console.aws.amazon.com/bedrock).
1. Seleziona **Agenti** nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione **Agenti**.
1. Nella sezione **Agenti**, seleziona il link relativo all’agente che desideri testare dall’elenco degli agenti.
1. 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.
1. 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.
1. 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**.
1. (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](prov-throughput.md).
1. (Facoltativo) Per utilizzare un prompt da Gestione prompt, seleziona l’icona delle opzioni (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) 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](prompt-management.md).
1. 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](trace-events.md).
+ 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.
![\[Richiesta della finestra di test per fornire un output di esempio per l’operazione.\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/images/agents/roc-testwindow.png)
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**
1. 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](https://console.aws.amazon.com/bedrock).
1. Seleziona **Agenti** nel riquadro di navigazione a sinistra. Quindi, scegli un agente nella sezione **Agenti**.
1. Nella sezione **Agenti**, seleziona il link relativo all’agente che desideri testare dall’elenco degli agenti.
1. Nella sezione **Bozza di lavoro** della pagina dei dettagli dell’agente, seleziona il collegamento per la **bozza di lavoro**.
1. Nella sezione **Gruppi di operazioni** o **Knowledge base**, passa il mouse sopra lo **Stato** del gruppo di operazioni di cui desideri modificare lo stato.
1. 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**.
1. 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.
1. 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 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) con un [endpoint in fase di compilazione di Agent per Amazon Bedrock.](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) 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](bedrock-agent_example_bedrock-agent_Hello_section.md).
**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 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html) (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](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) 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 [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). Per il codice di esempio, consulta [Invocazione di un agente dalla propria applicazione](agents-invoke-agent.md).
**Nota**
La AWS CLI non supporta [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).
La richiesta include i campi indicati di seguito:
+ Compila almeno i seguenti campi obbligatori:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/agents-test.html)
+ I seguenti campi sono facoltativi:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/bedrock/latest/userguide/agents-test.html)
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](trace-events.md).
+ Se configuri il gruppo di operazioni in modo che non utilizzi una funzione Lambda, nel campo `returnControl` viene restituito un oggetto [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html). La struttura generale dell’oggetto [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) è la seguente:
```
{
"invocationId": "string",
"invocationInputs": [
[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) or [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html),
...
]
}
```
Ogni membro dell’elenco di `invocationInputs` è uno dei seguenti:
+ In base all’input dell’utente, deve essere chiamato un oggetto [ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) 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](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) è la seguente:
```
{
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
: {
"properties": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
}
}
```
+ In base all’input dell’utente, deve essere chiamato un oggetto [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) contenente la funzione prevista dall’agente, oltre ai parametri per quella funzione che si ottengono dall’utente. La struttura di [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) è la seguente:
```
{
"actionGroup": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
```
------
# Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace
Ogni risposta di Agent per Amazon Bedrock è accompagnata da una *traccia* che descrive in dettaglio le fasi orchestrate dall’agente. La traccia è utile per capire il ragionamento che l’agente ha seguito per dare risposta in quel momento della conversazione.
Usare la traccia per monitorare il percorso dell’agente dall’input dell’utente alla risposta restituita. La traccia fornisce informazioni sugli input nei gruppi di azioni invocati dall’agente e sulle knowledge base interrogate dall’agente per rispondere all’utente. Inoltre, la traccia fornisce informazioni sugli output restituiti dai gruppi di azione e dalle knowledge base. È possibile visualizzare il ragionamento utilizzato dall’agente per determinare l’azione da eseguire o la query che esegue su una knowledge base. Se una fase nella traccia non riesce, viene restituito il motivo dell’errore. Utilizzare le informazioni dettagliate contenute nella traccia per risolvere i problemi dell’agente. È possibile identificare le fasi in cui l’agente ha problemi o in cui produce un comportamento imprevisto. È quindi possibile utilizzare queste informazioni per valutare i modi in cui è possibile migliorare il comportamento dell’agente.
# Visualizzazione della traccia
Di seguito viene descritto come visualizzare la traccia. Scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:
------
#### [ Console ]
**Come visualizzare la traccia durante una conversazione con 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](https://console.aws.amazon.com/bedrock).
1. Nella sezione **Agenti**, seleziona il link relativo all’agente che desideri testare dall’elenco degli agenti.
1. La finestra **Test** viene visualizzata in un riquadro sulla destra.
1. Inserisci un messaggio e scegli **Esegui**. Durante la generazione della risposta o al termine della generazione, seleziona **Mostra traccia**.
1. Puoi visualizzare la traccia per ogni **Fase** in tempo reale mentre il tuo agente esegue l’orchestrazione.
------
#### [ API ]
Per visualizzare la traccia, invia 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 un [endpoint di runtime Agent per Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt) e imposta il campo `enableTrace` su `TRUE`. Per impostazione predefinita, la traccia è disabilitata. Per un codice di esempio, consulta [Invocazione di un agente dalla propria applicazione](agents-invoke-agent.md).
Se abiliti la traccia, 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), ogni elemento `chunk` del flusso è accompagnato da un campo `trace` mappato a un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html). All’interno di [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) si trova un campo `trace` mappato a un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html).
------
## Struttura della traccia
Se la traccia è abilitata, 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), ogni `chunk` del flusso è accompagnato da un campo `trace` mappato a un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html). L’oggetto `tracePart` contiene informazioni sull’agente e sulle sessioni, oltre al processo di ragionamento dell’agente e ai risultati delle chiamate alle funzioni dell’API.
```
{
"agentId": "string",
"agentName": "string",
"collaboratorName": "string",
"agentAliasId": "string",
"sessionId": "string",
"agentVersion": "string",
"trace": { ...},
"callerChain": [{
"agentAliasArn": "agent alias arn"
}]
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html):
+ `agentId`: identificatore univoco dell’agente.
+ `agentName`: nome dell’agente.
+ `collaboratorName`: se la collaborazione multiagente è abilitata, il nome dell’agente collaboratore.
+ `agentVersion`: versione dell’agente.
+ `agentAliasId`: identificatore univoco dell’alias dell’agente.
+ `sessionId`: identificatore univoco della sessione con l’agente.
+ `trace`: contiene il processo di ragionamento dell’agente e i risultati delle chiamate delle azioni dell’API. Per ulteriori informazioni, vedere di seguito.
+ `callerChain`: elenco dei chiamanti tra l’agente che ha pubblicato questa traccia e l’utente finale.
+ Se si tratta di un singolo agente, questo campo conterrà l’alias Arn dello stesso agente che ha pubblicato la traccia.
+ Se la collaborazione multiagente è abilitata, questo campo conterrà l’alias Arn di tutti gli agenti che hanno inoltrato la richiesta dell’utente finale all’agente corrente.
All’interno di [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_TracePart.html) si trova un campo `trace` mappato a un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html). La traccia viene mostrata come oggetto JSON sia nella console che nell’API. Ogni **Fase** nella console o nell’API [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Trace.html) può essere una delle seguenti tracce:
+ [PreProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingTrace.html)— Traccia l'input e l'output della fase di pre-elaborazione, in cui l'agente contestualizza e classifica l'input dell'utente e determina se è valido.
+ [OrchestrationTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationTrace.html)— Traccia l'input e l'output della fase di orchestrazione, in cui l'agente interpreta l'input, richiama i gruppi di azioni e interroga le knowledge base. Poi l’agente restituisce l’output per continuare l’orchestrazione o per rispondere all’utente.
+ [PostProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingTrace.html)— Traccia l'input e l'output della fase di post-elaborazione, in cui l'agente gestisce l'output finale dell'orchestrazione e determina come restituire la risposta all'utente.
+ [CustomOrchestrationTrace](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_CustomOrchestrationTrace.html)— Dettagli sulla fase di orchestrazione personalizzata in cui l'agente determina l'ordine in cui le azioni vengono eseguite.
+ [RoutingClassifierTrace](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_RoutingClassifierTrace.html)— Traccia l'input e l'output del classificatore di routing
+ [FailureTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FailureTrace.html)— Traccia il motivo per cui un passaggio non è riuscito.
+ [GuardrailTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GuardrailTrace.html)— Traccia le azioni del Guardrail.
Ciascuna delle tracce (tranne `FailureTrace`) contiene un oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html). L’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html) contiene le configurazioni impostate nel modello di prompt per la fase, oltre al prompt fornito all’agente in questa fase. Per ulteriori informazioni su come modificare i modelli di prompt, consultare [Miglioramento della precisione dell’agente utilizzando modelli di prompt avanzati in Amazon Bedrock](advanced-prompts.md). La struttura di un oggetto `ModelInvocationInput` è la seguente:
```
{
"traceId": "string",
"text": "string",
"type": "PRE_PROCESSING | ORCHESTRATION | ROUTING_CLASSIFIER | KNOWLEDGE_BASE_RESPONSE_GENERATION | POST_PROCESSING",
"foundationModel":string",
"inferenceConfiguration": {
"maximumLength": number,
"stopSequences": ["string"],
"temperature": float,
"topK": float,
"topP": float
},
"promptCreationMode": "DEFAULT | OVERRIDDEN",
"parserMode": "DEFAULT | OVERRIDDEN",
"overrideLambda": "string"
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html):
+ `traceId`: identificatore univoco della traccia.
+ `text`: testo del prompt fornito all’agente in questa fase.
+ `type`: fase attuale del processo dell’agente.
+ `foundationModel`: modello di fondazione dell’agente collaboratore nella collaborazione multiagente. Questo campo è popolato solo se `type` è `ROUTING_CLASSIFIER`. Se il modello predefinito utilizzato per il routing dei prompt viene sovrascritto, questo campo mostra il modello dell’agente supervisore utilizzato per il routing dei prompt.
+ `inferenceConfiguration`: parametri di inferenza che influiscono sulla generazione della risposta. Per ulteriori informazioni, consulta [Influenza sulla generazione della risposta con i parametri di inferenza](inference-parameters.md).
+ `promptCreationMode`: se il modello di prompt di base predefinito dell’agente è stato sovrascritto o meno per questa fase. Per ulteriori informazioni, consulta [Miglioramento della precisione dell’agente utilizzando modelli di prompt avanzati in Amazon Bedrock](advanced-prompts.md).
+ `parserMode`: se il parser della risposta predefinito dell’agente è stato sovrascritto o meno per questa fase. Per ulteriori informazioni, consulta [Miglioramento della precisione dell’agente utilizzando modelli di prompt avanzati in Amazon Bedrock](advanced-prompts.md).
+ `overrideLambda`: nome della risorsa Amazon (ARN) della funzione Lambda del parser utilizzata per analizzare la risposta, se il parser predefinito è stato sovrascritto. Per ulteriori informazioni, consulta [Miglioramento della precisione dell’agente utilizzando modelli di prompt avanzati in Amazon Bedrock](advanced-prompts.md).
Per ulteriori informazioni su ciascuna opzione, consultare le sezioni riportate di seguito:
### PreProcessingTrace
```
{
"modelInvocationInput": { // see above for details }
"modelInvocationOutput": {
"metadata": {
"usage": {
"inputToken":: int,
"outputToken":: int
},
"rawResponse": {
"content": "string"
}
"parsedResponse": {
"isValid": boolean,
"rationale": "string"
},
"traceId": "string"
}
}
```
[PreProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingTrace.html)È costituito da un [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html)oggetto e un [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html)oggetto. [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PreProcessingModelInvocationOutput.html) contiene i seguenti campi.
+ `metadata`: contiene le seguenti informazioni relative all’output del modello di fondazione.
+ `usage`: contiene le seguenti informazioni relative all’utilizzo del modello di fondazione.
+ `inputTokens`: contiene le informazioni sui token di input derivanti dall’utilizzo del modello di fondazione.
+ `outputTokens`: contiene le informazioni sui token di output derivanti dall’utilizzo del modello di fondazione.
+ `rawResponse`: contiene l’output non elaborato del modello di fondazione.
+ `content`: contenuto di output non elaborato del modello di fondazione.
+ `parsedResponse`: contiene i seguenti dettagli sul prompt dell’utente analizzato.
+ `isValid`: specifica se il prompt dell’utente è valido o meno.
+ `rationale`: specifica il ragionamento dell’agente per le fasi successive da eseguire.
+ `traceId`: identificatore univoco della traccia.
### OrchestrationTrace
[OrchestrationTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationTrace.html)È costituito dall'[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html)oggetto, dall'[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html)oggetto e da qualsiasi combinazione degli oggetti [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html) e [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html). [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html) [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html) contiene i seguenti campi. Per ulteriori informazioni sugli oggetti [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html) e [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html), selezionate una delle seguenti schede. [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html)
```
{
"modelInvocationInput": { // see above for details },
"modelInvocationOutput": {
"metadata": {
"usage": {
"inputToken":: int,
"outputToken":: int
},
"rawResponse": {
"content": "string"
},
"rationale": { ... },
"invocationInput": { ... },
"observation": { ... }
}
```
Se `type` è `AGENT_COLLABORATOR` e se il routing è stato abilitato per l’agente supervisore, [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_OrchestrationModelInvocationOutput.html) conterrà la seguente struttura:
```
routingClassifierModelInvocationOutput: {
traceId: "string",
rawResponse: "string",
routerClassifierParsedResponse: {...}
metadata: {
inputTokens: "..."
outputTokens: "..."
}
}
```
------
#### [ Rationale ]
L’oggetto [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html) contiene il ragionamento dell’agente in base all’input dell’utente. Di seguito è riportata la struttura:
```
{
"traceId": "string",
"text": "string"
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [Rationale](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rationale.html):
+ `traceId`: identificatore univoco della fase della traccia.
+ `text`: processo di ragionamento dell’agente, basato sul prompt dell’utente.
------
#### [ InvocationInput ]
L'oggetto [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html) contiene informazioni che verranno inserite nel gruppo di operazioni o nella knowledge base da richiamare o interrogare. Di seguito è riportata la struttura:
```
{
"traceId": "string",
"invocationType": "AGENT_COLLABORATOR" | "ACTION_GROUP | KNOWLEDGE_BASE | FINISH",
"agentCollaboratorInvocationInput": {
// see below for details
},
"actionGroupInvocationInput": {
// see below for details
},
"knowledgeBaseLookupInput": {
"knowledgeBaseId": "string",
"text": "string"
}
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [InvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvocationInput.html):
+ `traceId`: identificatore univoco della traccia.
+ `invocationType`: specifica se l’agente sta invocando un agente collaboratore o una knowledge base oppure se sta terminando la sessione.
+ `agentCollaborationInvocationInput`: contiene l’input di invocazione per gli agenti collaboratori. Viene visualizzato se il `type` è `AGENT_COLLABORATOR` e se il routing è abilitato per l’agente supervisore. Per ulteriori informazioni, consulta [Utilizzo della collaborazione multiagente con Agent per Amazon Bedrock](agents-multi-agent-collaboration.md).
+ La struttura `agentCollaborationInvocationInput ` è la seguente:
```
{
"agentCollaboratorName": "string",
"agentCollaboratorAliasArn": "string",
"input": {
"text": "string"
}
}
```
Di seguito sono riportate le descrizioni dei campi:
+ `agentCollaboratorName`: nome dell’agente collaboratore associato all’agente supervisore.
+ `agentCollaboratorAliasArn`: Arn alias dell’agente collaboratore.
+ `input`: La stringa di input per l’agente collaboratore.
+ `actionGroupInvocationInput`: appare se `type` è `ACTION_GROUP`. Per ulteriori informazioni, consulta [Definizione delle azioni nel gruppo di azioni](action-define.md). Può essere una delle seguenti strutture:
+ Se il gruppo di azioni è definito da uno schema API, la struttura è la seguente:
```
{
"actionGroupName": "string",
"apiPath": "string",
"verb": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
"content": {
"": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
},
"executionType": "LAMBDA | RETURN_CONTROL",
"invocationId": "string"
}
```
Di seguito sono riportate le descrizioni dei campi:
+ `actionGroupName`: nome del gruppo di azioni che l’agente prevede che debba essere invocato.
+ `apiPath`: percorso dell’operazione dell’API da chiamare, in base allo schema dell’API.
+ `verb`: metodo API in uso, secondo lo schema dell’API.
+ `parameters`: contiene un elenco di oggetti. Ogni oggetto contiene il nome, il tipo e il valore di un parametro nell’operazione dell’API, come definito nello schema dell’API.
+ `requestBody`: contiene il corpo della richiesta e le relative proprietà, come definito nello schema dell’API.
+ `executionType`: se l’adempimento dell’azione viene trasferito a una funzione Lambda (`LAMBDA`) o il controllo viene restituito tramite la risposta `InvokeAgent` (`RETURN_CONTROL`). Per ulteriori informazioni, consulta [Gestione dell’adempimento dell’azione](action-handle.md).
+ `invocationId`: identificatore dell’invocazione. Restituito solo se `executionType` è `RETURN_CONTROL`.
+ Se il gruppo di azioni è definito dai dettagli della funzione, la struttura è la seguente:
```
{
"actionGroupName": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"executionType": "LAMBDA | RETURN_CONTROL",
"invocationId": "string"
}
```
Di seguito sono riportate le descrizioni dei campi:
+ `actionGroupName`: nome del gruppo di azioni che l’agente prevede che debba essere invocato.
+ `function`: nome della funzione che l’agente prevede che debba essere chiamata.
+ `parameters`: parametri della funzione.
+ `executionType`: se l’adempimento dell’azione viene trasferito a una funzione Lambda (`LAMBDA`) o il controllo viene restituito tramite la risposta `InvokeAgent` (`RETURN_CONTROL`). Per ulteriori informazioni, consulta [Gestione dell’adempimento dell’azione](action-handle.md).
+ `invocationId`: identificatore dell’invocazione. Restituito solo se `executionType` è `RETURN_CONTROL`.
+ `knowledgeBaseLookupInput`: appare se `type` è `KNOWLEDGE_BASE`. Per ulteriori informazioni, consulta [Recupero di dati e generazione di risposte di IA con Knowledge Base per Amazon Bedrock](knowledge-base.md). Contiene le seguenti informazioni sulla knowledge base e sulla query di ricerca per la knowledge base:
+ `knowledgeBaseId`: identificatore univoco della knowledge base che l’agente cercherà.
+ `text`: query da eseguire sulla knowledge base.
------
#### [ Observation ]
L’oggetto [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html) contiene il risultato o l’output di un agente collaboratore, di un gruppo di azioni o di una knowledge base oppure la risposta all’utente. Di seguito è riportata la struttura:
```
{
"traceId": "string",
"type": "AGENT_COLLABORATOR |ACTION_GROUP | KNOWLEDGE_BASE | REPROMPT | ASK_USER | FINISH",
"agentCollaboratorInvocationOutput": {
"agentCollaboratorName": "string",
"agentCollaboratorAliasArn": "string",
"output": {
"text": "string"
},
"actionGroupInvocation": {
"text": "JSON-formatted string"
},
"knowledgeBaseLookupOutput": {
"retrievedReferences": [
{
"content": {
"text": "string"
},
"location": {
"type": "S3",
"s3Location": {
"uri": "string"
}
}
},
...
]
},
"repromptResponse": {
"source": "ACTION_GROUP | KNOWLEDGE_BASE | PARSER",
"text": "string"
},
"finalResponse": {
"text"
}
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [Observation](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Observation.html):
+ `traceId`: identificatore univoco della traccia.
+ `type`: specifica se l’osservazione dell’agente viene restituita dal risultato di un agente collaboratore, di un gruppo di azioni o di una knowledge base oppure se l’agente sta inviando nuovamente un prompt all’utente, sta chiedendo ulteriori informazioni o sta terminando la conversazione.
+ `agentCollaboratorInvocationOutput`: contiene la risposta dell’agente collaboratore o la risposta finale. Viene visualizzato se il `type` è `AGENT_COLLABORATOR` e se il routing è abilitato per l’agente supervisore. Per ulteriori informazioni, consulta [Utilizzo della collaborazione multiagente con Agent per Amazon Bedrock](agents-multi-agent-collaboration.md). Ogni risposta contiene i seguenti campi:
+ `agentCollaboratorName`: nome dell’agente collaboratore che invia la risposta.
+ `agentCollaboratorAliasArn`: Arn alias dell’agente collaboratore che invia la risposta.
+ `output`: contiene la risposta inviata dall’agente collaboratore.
+ `actionGroupInvocationOutput`: contiene la stringa in formato JSON restituita dall’operazione dell’API invocata dal gruppo di azioni. Appare se `type` è `ACTION_GROUP`. Per ulteriori informazioni, consulta [Definire schemi OpenAPI per i gruppi di operazioni dell’agente in Amazon Bedrock](agents-api-schema.md).
+ `knowledgeBaseLookupOutput`: contiene il testo recuperato dalla knowledge base utile per rispondere al prompt, oltre alla posizione Amazon S3 dell’origine dati. Appare se `type` è `KNOWLEDGE_BASE`. Per ulteriori informazioni, consulta [Recupero di dati e generazione di risposte di IA con Knowledge Base per Amazon Bedrock](knowledge-base.md). Ogni oggetto dell’elenco di `retrievedReferences` contiene i seguenti campi:
+ `content`: contiene il `text` della knowledge base che viene restituito dalla query alla knowledge base.
+ `location`: contiene l’URI Amazon S3 dell’origine dati in cui è stato trovato il testo restituito.
+ `repromptResponse`: appare se `type` è `REPROMPT`. Contiene `text` che richiede un altro prompt, oltre a `source` per cui l’agente deve inviare nuovamente il prompt.
+ `finalResponse`: appare se `type` è `ASK_USER` o `FINISH`. Contiene il `text` che richiede all’utente ulteriori informazioni o è una risposta all’utente.
------
### PostProcessingTrace
```
{
"modelInvocationInput": { // see above for details }
"modelInvocationOutput": {
"rawResponse": {
"content": "string"
},
"metadata": {
"usage": {
"inputToken": int,
"outputToken": int
}
},
"parsedResponse": {
"text": "string"
},
"traceId": "string"
}
}
```
[PostProcessingTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingTrace.html)È costituito da un [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ModelInvocationInput.html)oggetto e un [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html)oggetto. Il [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_PostProcessingModelInvocationOutput.html) contiene i seguenti campi:
+ `rawResponse`: contiene l’output non elaborato del modello di fondazione.
+ `content`: contenuto di output non elaborato del modello di fondazione.
+ `metadata`: contiene le seguenti informazioni relative all’output del modello di fondazione.
+ `usage`: contiene le seguenti informazioni relative all’utilizzo del modello di fondazione.
+ `inputTokens`: contiene le informazioni sui token di input derivanti dall’utilizzo del modello di fondazione.
+ `outputTokens`: contiene le informazioni sui token di output derivanti dall’utilizzo del modello di fondazione.
+ `parsedResponse`: contiene il `text` da restituire all’utente dopo essere stato elaborato dalla funzione del parser.
+ `traceId`: identificatore univoco della traccia.
### FailureTrace
```
{
"failureReason": "string",
"traceId": "string"
}
```
Nell’elenco seguente sono descritti i campi dell’oggetto [FailureTrace](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FailureTrace.html):
+ `failureReason`: motivo per cui la fase non è riuscita.
+ `traceId`: identificatore univoco della traccia.
### GuardrailTrace
```
{
"action": "GUARDRAIL_INTERVENED" | "NONE",
"inputAssessments": [GuardrailAssessment],
"outputAssessments": [GuardrailAssessment]
}
```
L'elenco seguente descrive i campi dell' GuardrailAssessment oggetto:
+ `action`: indica se i guardrail sono intervenuti o meno sui dati di input. Le opzioni sono `GUARDRAIL_INTERVENED` o `NONE`.
+ `inputAssessments`: dettagli della valutazione del guardrail sull’input dell’utente.
+ `outputAssessments`: dettagli della valutazione del guardrail sulla risposta.
Per ulteriori informazioni sull’oggetto `GuardrailAssessment` e sul test di un guardrail, consultare [Testare il guardrail](guardrails-test.md).
GuardrailAssessment esempio:
```
{
"topicPolicy": {
"topics": [{
"name": "string",
"type": "string",
"action": "string"
}]
},
"contentPolicy": {
"filters": [{
"type": "string",
"confidence": "string",
"action": "string"
}]
},
"wordPolicy": {
"customWords": [{
"match": "string",
"action": "string"
}],
"managedWordLists": [{
"match": "string",
"type": "string",
"action": "string"
}]
},
"sensitiveInformationPolicy": {
"piiEntities": [{
"type": "string",
"match": "string",
"action": "string"
}],
"regexes": [{
"name": "string",
"regex": "string",
"match": "string",
"action": "string"
}]
}
}
```