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

Guida introduttiva alla valutazione su richiesta

Segui questi passaggi per configurare ed eseguire la tua prima valutazione su richiesta.

Prerequisiti

Per utilizzare le funzionalità di AgentCore OnDemand valutazione delle valutazioni, hai bisogno di:

Framework supportati

Crea il tuo agente con un framework e una libreria di strumentazione supportati da Evaluations. AgentCore Per ulteriori informazioni sui framework e sulle librerie di strumentazione supportati, consulta Frameworks per agenti supportati. Framework per agenti supportati

Fase 1: Crea e distribuisci il tuo agente

Crea e distribuisci il tuo agente seguendo la guida introduttiva per AgentCore Runtime. Puoi trovare altri esempi negli esempi di AgentCore valutazione.

Fase 2: Richiama il tuo agente

Richiama il tuo agente utilizzando il seguente comando e visualizza le tracce, le sessioni e le metriche sulla dashboard di GenAI Observability su. CloudWatch

Esempio: invoke_agent.py

import boto3
import json
import uuid

region = "region-code"
ace_demo_agent_arn = "agent-arn from step-2"

agent_core_client = boto3.client('bedrock-agentcore', region_name=region)

text_to_analyze = "Sample text to test agent for agentcore evaluations demo"

payload = json.dumps({
    "prompt": f"Can you analyze this text and tell me about its statistics: {text_to_analyze}"
})

# random session-id, you can set your own here
session_id = "test-ace-demo-session-18a1dba0-62a0-462g"

response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=ace_demo_agent_arn,
    runtimeSessionId=session_id,
    payload=payload,
    qualifier="DEFAULT"
)

response_body = response['response'].read()
response_data = json.loads(response_body)
print("Agent Response:", response_data)
print("SessionId:", session_id)

Fase 3: Valuta l'agente

Dopo aver fatto alcune chiamate al tuo agente, sei pronto per valutarlo. Per le valutazioni abbiamo bisogno di:

Esempi di codice per CLI e SDK AgentCore AgentCore

I seguenti esempi di codice dimostrano come eseguire valutazioni su richiesta utilizzando diversi approcci di sviluppo. Scegliete il metodo più adatto al vostro ambiente di sviluppo e alle vostre preferenze.

AWS SDK

Scarica gli span-logs da CloudWatch

Prima di chiamare l'EvaluateAPI, devi scaricare gli span log da. CloudWatch Puoi usare il codice Python qui sotto per farlo e facoltativamente salvarli in un file JSON. In questo modo è più semplice effettuare la richiesta per la stessa sessione con diversi valutatori.

import boto3
import time
import json
from datetime import datetime, timedelta

region = "region-code"
agent_id = "agent-id-from-step-2"
session_id = "session-id-from-step-3"

def query_logs(log_group_name, query_string):
    client = boto3.client('logs', region_name=region)
    start_time = datetime.now() - timedelta(minutes=60) # past 1 hour
    end_time = datetime.now()

    query_id = client.start_query(
        logGroupName=log_group_name,
        startTime=int(start_time.timestamp()),
        endTime=int(end_time.timestamp()),
        queryString=query_string
    )['queryId']

    while (result := client.get_query_results(queryId=query_id))['status'] not in ['Complete', 'Failed']:
        time.sleep(1)

    if result['status'] == 'Failed':
        raise Exception("Query failed")
    return result['results']

def query_session_logs(log_group_name, session_id, **kwargs):
    query = f"""fields @timestamp, @message
    | filter ispresent(scope.name) and ispresent(attributes.session.id)
    | filter attributes.session.id = "{session_id}"
    | sort @timestamp asc"""
    return query_logs(log_group_name, query, **kwargs)

def query_agent_runtime_logs(agent_id, endpoint, session_id, **kwargs):
    return query_session_logs(
        f"/aws/bedrock-agentcore/runtimes/{agent_id}-{endpoint}",
        session_id, **kwargs)

def query_aws_spans_logs(session_id, **kwargs):
    return query_session_logs("aws/spans", session_id, **kwargs)

def extract_messages_as_json(query_results):
    return [json.loads(f['value']) for row in query_results
            for f in row if f['field'] == '@message'
            and f['value'].strip().startswith('{')]

def get_session_span_logs():
    agent_runtime_logs = query_agent_runtime_logs(
        agent_id=agent_id, endpoint="DEFAULT", session_id=session_id
    )
    print(f"Downloaded {len(agent_runtime_logs)} runtime-log entries")

    aws_span_logs = query_aws_spans_logs(session_id=session_id)
    print(f"Downloaded {len(aws_span_logs)} aws/span entries")

    session_span_logs = extract_messages_as_json(aws_span_logs) + extract_messages_as_json(agent_runtime_logs)
    print(f"Returning {len(aws_span_logs) + len(agent_runtime_logs)} total records")
    return session_span_logs

# get the spans from cloudwatch
session_span_logs = get_session_span_logs()

# optional (dump in a json file for reuse)
session_span_logs_file_name = "ace-demo-session.json"
with open(session_span_logs_file_name, "w") as f:
    json.dump(session_span_logs, f, indent=2)

Chiama Evaluate

Una volta ottenuti gli intervalli di input, puoi richiamare l'EvaluateAPI. Tieni presente che le risposte potrebbero richiedere alcuni istanti poiché un modello linguistico di grandi dimensioni sta valutando le tue tracce.

# initialise client
ace_dp_client = boto3.client('bedrock-agentcore', region_name = region)

# call evaluate
response = ace_dp_client.evaluate(
    evaluatorId = "Builtin.Helpfulness", # can be a custom evaluator id as well
    evaluationInput = {"sessionSpans": session_span_logs})

print(response["evaluationResults"])

Se usi quanto sopra e scarichi gli intervalli di sessione in un file json, puoi anche successivamente eseguire evaluate come segue

with open(session_span_logs_file_name, "r") as f:
    session_span_logs = json.load(f)

# initialise client
ace_dp_client = boto3.client('bedrock-agentcore', region_name = region)

# call evaluate
response = ace_dp_client.evaluate(
    evaluatorId = "Builtin.ToolSelectionAccuracy", # can be a custom evaluator id as well
    evaluationInput = {"sessionSpans": session_span_logs})

print(response["evaluationResults"])

Utilizzo degli obiettivi di valutazione

Per valutare una traccia o uno strumento specifico all'interno di una sessione, puoi specificare l'obiettivo utilizzando il evaluationTarget parametro nella richiesta.

Session-level valutatore

Poiché il servizio supporta solo una sessione per valutazione, non è necessario impostare esplicitamente l'obiettivo di valutazione.

Trace-level valutatore

Per i valutatori a livello di traccia (come Builtin.Helpfulness orBuiltin.Correctness), imposta gli ID di traccia nel parametro: evaluationTarget

response = ace_dp_client.evaluate(
    evaluatorId = "Builtin.Helpfulness",
    evaluationInput = {"sessionSpans": session_span_logs},
    evaluationTarget = {"traceIds": ["trace-id-1", "trace-id-2"]}
)

Strumento di valutazione del livello di chiamata

Per i valutatori a livello di intervallo (ad esempioBuiltin.ToolSelectionAccuracy), imposta gli ID di intervallo nel parametro: evaluationTarget

response = ace_dp_client.evaluate(
    evaluatorId = "Builtin.ToolSelectionAccuracy",
    evaluationInput = {"sessionSpans": session_span_logs},
    evaluationTarget = {"spanIds": ["span-id-1", "span-id-2"]}
)

Fase 4: Risultati della valutazione

Ogni chiamata Evaluate API restituisce una risposta contenente un elenco di risultati del valutatore. Poiché una singola sessione può includere più tracce e chiamate a strumenti, questi elementi vengono valutati come entità separate. Di conseguenza, una singola chiamata API può restituire più risultati di valutazione.

{
    "evaluationResults": [ {evaluation-result-1}, {evaluation-result_2},.... ]
}

Limite di risultati

Il numero di valutazioni restituite per chiamata API è limitato a 10 risultati. Ad esempio, se si valuta una sessione contenente 15 tracce utilizzando un valutatore a livello di traccia, la risposta include un massimo di 10 risultati. Per impostazione predefinita, l'API restituisce le ultime 10 valutazioni, poiché in genere contengono il contesto più rilevante per la qualità della valutazione.

Guasti parziali

Una chiamata API può elaborare nessuna valutazione mentre nessuna di esse ha esito negativo. Gli errori possono verificarsi per vari motivi, tra cui:

In caso di fallimento parziale, la risposta include sia le valutazioni positive che quelle non riuscite. I risultati non riusciti includono un codice di errore e un messaggio di errore per aiutarti a diagnosticare il problema.

Contesto Span

Ogni risultato del valutatore ha un spanContext campo che identifica l'entità valutata:

Esempio di inserimento riuscito dei risultati

Questa è solo una voce. Se una sessione ha più tracce, vedrai più di queste voci, una per ogni traccia. Analogamente, per i valutatori a livello di strumento, se vengono richiamati più strumenti e viene fornito un valutatore di strumenti (ad esempioBuiltin.ToolSelectionAccuracy), si otterrà un risultato per intervallo di utensile.

{
  "evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness",
  "evaluatorId": "Builtin.Helpfulness",
  "evaluatorName": "Builtin.Helpfulness",
  "explanation": ".... evaluation explanation will be added here ...",
  "context": {
    "spanContext": {
      "sessionId": "test-ace-demo-session-18a1dba0-62a0-462e",
      "traceId": "....trace_id......."
    }
  },
  "value": 0.83,
  "label": "Very Helpful",
  "tokenUsage": {
    "inputTokens": 958,
    "outputTokens": 211,
    "totalTokens": 1169
  }
}

Esempio: immissione di risultati non riuscita

{
    "evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness",
    "evaluatorId": "Builtin.Helpfulness",
    "evaluatorName": "Builtin.Helpfulness",
    "context": {
        "spanContext": {
            "sessionId": "test-ace-demo-session-18a1dba0-62a0-462e",
            "traceId": "....trace_id......."
        }
    },
    "errorMessage": ".... details of the error....",
    "errorCode": ".... name/code of the error...."
}