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 OnDemand valutazione delle AgentCore valutazioni, è necessario:

Framework supportati

AgentCore Attualmente Evaluations supporta i seguenti framework agentici e librerie di strumentazione:

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

Invoca 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: Valutare l'agente

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

Esempi di codice per AgentCore CLI e SDK AgentCore

I seguenti esempi di codice mostrano 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 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. Ciò semplifica 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 che hai gli intervalli di input, puoi richiamare l'EvaluateAPI. Tieni presente che le risposte potrebbero richiedere alcuni istanti poiché un modello linguistico di grandi dimensioni assegna un punteggio alle 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 si utilizza l'opzione precedente e si esegue il dump degli intervalli di sessione in un file json, è possibile eseguire anche successivamente assessment come indicato di seguito

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 di obiettivi di valutazione

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

Session-level valutatore

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

Trace-level valutatore

Per i valutatori a livello di traccia (come Builtin.Helpfulness oBuiltin.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 estensione (comeBuiltin.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 dei risultati del valutatore. Poiché una singola sessione può includere più tracce e chiamate agli 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 dei 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 n valutazioni mentre molte di esse hanno esito negativo. Gli errori possono verificarsi per vari motivi, tra cui:

In caso di fallimento parziale, la risposta include sia le valutazioni riuscite che quelle non riuscite. I risultati non riusciti includono un codice e un messaggio di errore per facilitare la diagnosi del problema.

Amplia il contesto

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, verranno visualizzate più voci di questo tipo, una per ogni traccia. Analogamente, per i valutatori a livello di strumento, se ci sono più chiamate allo strumento e viene fornito un valutatore di strumenti (ad esempioBuiltin.ToolSelectionAccuracy), ci sarà un risultato per intervallo di strumenti.

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