Exemplos de código Parâmetros de solicitação Fonte da sessão Saída de resultados Resposta Erros

Iniciar avaliação em lote

Inicie uma avaliação em lote para executar avaliadores em várias sessões de agentes. O serviço descobre sessões a partir do CloudWatch Logs, compara cada avaliador a cada sessão e produz resultados agregados.

Exemplos de código

exemplo

AgentCore CLI

A CLI é resolvida logGroupNames automaticamente serviceNames a partir da configuração do projeto quando você usa: --runtime


agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness

Com bandeiras opcionais:


# Custom name and lookback window
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --name my_baseline_eval \
  --lookback-days 1

# Specific sessions
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --session-ids session-abc123 session-def456

# With ground truth
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Correctness \
  --ground-truth ground-truth.json

Por padrão, o comando inicia o trabalho e retorna imediatamente. Passe --wait para o bloco até que o trabalho atinja um estado terminal (COMPLETED,, ouSTOPPED)FAILED, após o qual a CLI exibe as pontuações médias por avaliador e salva os resultados em. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationtambém suporta os seguintes sinalizadores:

--wait— bloqueie até que o trabalho atinja um estado terminal.
--json— emite saída JSON legível por máquina.
--kms-key <arn>— criptografe os resultados da avaliação em lote com uma chave KMS gerenciada pelo cliente.
--dataset <name>/--dataset-version <version>— invoca o agente com cenários de conjuntos de dados antes da avaliação em lote (omita a versão de um arquivo local ou useN/). DRAFT
--endpoint <name>— segmente um endpoint de tempo de execução específico (por exemplo,PROMPT_V1); então, assume como padrão a variável de AGENTCORE_RUNTIME_ENDPOINT ambiente. DEFAULT
--evaluator-arn <arns…>— avaliadores de referência por ARN em vez de. -e

A maioria dos sinalizadores tem aliases curtos: -r (--runtime), -e (--evaluator), -n (--name), (), -d (--lookback-days), -s (--session-ids) e -g (--ground-truth).

Para gerenciar um trabalho após seu início, execute agentcore stop batch-evaluation -i <id> para interromper um trabalho em execução e agentcore archive batch-evaluation -i <id> arquivar um registro de trabalho.

AWS SDK (boto3)


import boto3
import uuid
import time
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

# All sessions in the log group
response = client.start_batch_evaluation(
    batchEvaluationName=f"baseline_eval_{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
        {"evaluatorId": "Builtin.Helpfulness"},
        {"evaluatorId": "Builtin.Faithfulness"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
        }
    },
    clientToken=str(uuid.uuid4()),
)

batch_eval_id = response["batchEvaluationId"]
print(f"Started: {batch_eval_id}")

# Poll until complete
while True:
    result = client.get_batch_evaluation(batchEvaluationId=batch_eval_id)
    status = result["status"]
    print(f"Status: {status}")

    if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"):
        break
    time.sleep(30)

print(json.dumps(result, indent=4, default=str))

Com a filtragem de ID de sessão:


response = client.start_batch_evaluation(
    batchEvaluationName=f"targeted-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "sessionIds": ["session-001", "session-002", "session-003"]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Com filtragem por intervalo de tempo:


from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
response = client.start_batch_evaluation(
    batchEvaluationName=f"weekly-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "timeRange": {
                    "startTime": (now - timedelta(days=7)).isoformat(),
                    "endTime": now.isoformat(),
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`batchEvaluationName`	String	Sim	Um nome para o trabalho de avaliação em lote. Padrão: começa com uma letra, alfanumérica e sublinhados, máximo de 48 caracteres.
`dataSourceConfig`	Objeto	Sim	Onde encontrar sessões de agentes. Especifique uma `cloudWatchLogs` fonte com o nome do serviço do seu agente e os nomes exatos dos grupos de registros ou os prefixos dos nomes dos grupos de registros. Consulte Fonte da sessão abaixo.
`evaluators`	Lista	Sim	Lista de avaliadores. Cada entrada tem um `evaluatorId` campo (por exemplo,`Builtin.GoalSuccessRate`). Máximo de 10 avaliadores.
`evaluationMetadata`	Objeto	Não	Contém `sessionMetadata` uma lista de informações básicas e metadados por sessão. Máximo de 500 inscrições.
`outputConfig`	Objeto	Não	CloudWatch Destino opcional para resultados por sessão e métricas de pontuação. Especifique a `cloudWatchConfig` para escolher o grupo de registros de resultados e o namespace de métricas. Consulte Saída de resultados abaixo.
`clientToken`	String	Não	Símbolo de idempotência. Se você tentar novamente uma solicitação com o mesmo token de cliente, o serviço retornará o trabalho existente em vez de criar um novo.

Fonte da sessão

O dataSourceConfig parâmetro especifica o local do CloudWatch Logs em que o serviço descobre as sessões do agente.

Campos obrigatórios

Campo	Tipo	Description
`cloudWatchLogs.serviceNames`	Lista de sequências de caracteres (exatamente 1)	O nome do serviço que identifica os rastros do seu agente. CloudWatch Convenção:`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Lista de sequências de caracteres (1—5)	Uma forma de selecionar grupos de registros de entrada. Especifique os nomes exatos dos grupos de CloudWatch registros em que a telemetria do agente está armazenada. Mutuamente exclusivo com `logGroupNamePrefixes`.
`cloudWatchLogs.logGroupNamePrefixes`	Lista de sequências de caracteres (1—5)	Uma forma de selecionar grupos de registros de entrada. O serviço descobre sessões de cada grupo de registros cujo nome começa com um desses prefixos, portanto, os grupos de registros correspondentes recém-criados são selecionados automaticamente. Mutuamente exclusivo com `logGroupNames`.

Especifique exatamente um dos logGroupNames oulogGroupNamePrefixes. Em ambos os casos, serviceNames é necessário identificar os rastros do seu agente nos grupos de registros selecionados.

Se você usa logGroupNamePrefixes para combinar grupos de logs do Amazon Bedrock AgentCore Runtime, certifique-se de que seu tempo de execução envie períodos para o próprio grupo de logs do agente. Para agentes que ainda usam o grupo de aws/spans log compartilhado, UNIFIED_TRACES_DESTINATION_ENABLED=true defina o tempo de execução. Para obter mais informações, consulte Destino de Span para agentes hospedados no tempo de AgentCore execução do Amazon Bedrock.


# Match input log groups by prefix instead of exact names
dataSourceConfig={
    "cloudWatchLogs": {
        "logGroupNamePrefixes": ["/aws/bedrock-agentcore/runtimes/MyAgent-"],
        "serviceNames": ["MyAgent.DEFAULT"]
    }
}

Campos opcionais

Campo	Tipo	Description
`cloudWatchLogs.filterConfig.sessionIds`	Lista de strings	Avalie somente esses IDs de sessão específicos. Quando omitido, o serviço descobre todas as sessões no grupo de registros.
`cloudWatchLogs.filterConfig.timeRange.startTime`	Data e hora ISO 8601	Filtre as sessões criadas após esse período.
`cloudWatchLogs.filterConfig.timeRange.endTime`	Data e hora ISO 8601	Filtre as sessões criadas antes desse horário.

Saída de resultados

Por padrão, os resultados da avaliação em lote vão para um grupo de registros dedicado e gerenciado pelo serviço. Use outputConfig.cloudWatchConfig para controlar onde os resultados por sessão são gravados e qual namespace de CloudWatch métricas recebe pontuações de avaliação.

Escolha onde os resultados são escritos

DEDICATED_LOG_GROUP(padrão) — Grava os resultados em um grupo dedicado de registros de resultados. Se você não definirlogGroupName, o serviço gerenciará o grupo para você. Para usar seu próprio grupo, defina logGroupName (consulteUse um grupo de registros de saída personalizado).
SOURCE_LOG_GROUP— Grava os resultados no mesmo grupo de registros do qual os rastreamentos do agente foram lidos. Ao usar esse valor, não definalogGroupName.

Use um grupo de registros de saída personalizado

ParaDEDICATED_LOG_GROUP, logGroupName defina para gravar resultados em um grupo de registros que você escolher. Um grupo de registros existente é usado como está; se não existir, o serviço o cria, o que exige a concessão logs:CreateLogGroup da função de execução. O nome não pode estar no /aws/bedrock-agentcore/evaluations/ namespace reservado pelo serviço, além do grupo padrão gerenciado pelo serviço.


# Write results back to the trace source log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "SOURCE_LOG_GROUP"
    }
}

# Write results to a custom dedicated log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "DEDICATED_LOG_GROUP",
        "logGroupName": "/my/team/batch-evaluation-results"
    }
}

Publicar métricas em um namespace personalizado

metricsNamespaceDefina para publicar métricas de pontuação em seu próprio CloudWatch namespace em vez de. Bedrock-AgentCore/Evaluations O valor não pode começar comAWS/.


outputConfig={
    "cloudWatchConfig": {
        "metricsNamespace": "MyTeam/Evaluations"
    }
}

Resposta

Campo	Tipo	Description
`batchEvaluationId`	String	Identificador exclusivo para a avaliação do lote.
`batchEvaluationArn`	String	ARN da avaliação do lote.
`batchEvaluationName`	String	O nome que você especificou.
`status`	String	Status inicial. Um dos:`PENDING`,`IN_PROGRESS`.
`evaluators`	Lista	Os avaliadores usaram.
`createdAt`	Timestamp	Quando o trabalho foi criado.
`outputConfig`	Objeto	CloudWatch destino para resultados por sessão e métricas de pontuação.

Erros

Erro	Status HTTP	Description
`ValidationException`	400	Parâmetros de solicitação inválidos. Verifique as restrições de campo e os campos obrigatórios.
`AccessDeniedException`	403	Permissões insuficientes. Verifique as políticas do IAM.
`ConflictException`	409	Já existe uma avaliação em lote com o mesmo token de cliente com parâmetros diferentes.
`ThrottlingException`	429	Taxa de solicitações excedida. Novas tentativas com recuo exponencial.
`InternalServerException`	500	Service-side erro. Repetir a solicitação .

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Introdução

Obtenha resultados de avaliação em lote