Tieni traccia del processo di step-by-step ragionamento dell'agente utilizzando trace - Amazon Bedrock
Struttura della traccia

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

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.

Struttura della traccia

Se la traccia è abilitata, nella risposta InvokeAgent, ogni chunk del flusso è accompagnato da un campo trace mappato a un oggetto TracePart. 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 TracePart:

  • 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 TracePart si trova un campo trace mappato a un oggetto Trace. La traccia viene mostrata come oggetto JSON sia nella console che nell’API. Ogni Fase nella console o nell’API Trace può essere una delle seguenti tracce:

  • PreProcessingTrace— 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— 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— 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— Dettagli sulla fase di orchestrazione personalizzata in cui l'agente determina l'ordine in cui le azioni vengono eseguite.

  • RoutingClassifierTrace— Traccia l'input e l'output del classificatore di routing

  • FailureTrace— Traccia il motivo per cui un passaggio non è riuscito.

  • GuardrailTrace— Traccia le azioni del Guardrail.

Ciascuna delle tracce (tranne FailureTrace) contiene un oggetto ModelInvocationInput. L’oggetto ModelInvocationInput 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. 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 ModelInvocationInput:

Per ulteriori informazioni su ciascuna opzione, consultare le sezioni riportate di seguito:

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "metadata": {
             "usage": {
                  "inputToken":: int,
                  "outputToken":: int
           },
         "rawResponse": {
              "content": "string"
          }
        "parsedResponse": {
            "isValid": boolean,
            "rationale": "string"
        },
        "traceId": "string"
    }
}

PreProcessingTraceÈ costituito da un ModelInvocationInputoggetto e un PreProcessingModelInvocationOutputoggetto. PreProcessingModelInvocationOutput 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È costituito dall'ModelInvocationInputoggetto, dall'OrchestrationModelInvocationOutputoggetto e da qualsiasi combinazione degli oggetti Rationale e Observation. InvocationInput OrchestrationModelInvocationOutput contiene i seguenti campi. Per ulteriori informazioni sugli oggetti Rationale e Observation, selezionate una delle seguenti schede. InvocationInput 

{
    "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, OrchestrationModelInvocationOutput conterrà la seguente struttura:

routingClassifierModelInvocationOutput: {
        traceId: "string",
        rawResponse: "string",
        routerClassifierParsedResponse: {...} 
        metadata: {
            inputTokens: "..."
            outputTokens: "..."    
        }
    }
Rationale

L’oggetto Rationale 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:

  • traceId: identificatore univoco della fase della traccia.

  • text: processo di ragionamento dell’agente, basato sul prompt dell’utente.

InvocationInput

L'oggetto InvocationInput 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:

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

    • 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. 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": {
            "<content-type>": [
                {
                    "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.

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

      • 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. 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 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:

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

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

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "rawResponse": {
            "content": "string"
        },
        "metadata": {
            "usage": {
                "inputToken": int,
                "outputToken": int    
             }     
         },
        "parsedResponse": {
            "text": "string"
        },
        "traceId": "string"
    }
}

PostProcessingTraceÈ costituito da un ModelInvocationInputoggetto e un PostProcessingModelInvocationOutputoggetto. Il PostProcessingModelInvocationOutput 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.

{
    "failureReason": "string",
    "traceId": "string"
}

Nell’elenco seguente sono descritti i campi dell’oggetto FailureTrace:

  • failureReason: motivo per cui la fase non è riuscita.

  • traceId: identificatore univoco della traccia.

{
    "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.

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"
        }]
    }
}