Exemples de code Paramètres de demande Source de la session Résultat de sortie Réponse Erreurs

Commencer l'évaluation par lots

Lancez une évaluation par lots pour exécuter des évaluateurs sur plusieurs sessions d'agent. Le service découvre les sessions à partir CloudWatch des journaux, exécute chaque évaluateur pour chaque session et produit des résultats agrégés.

Exemples de code

Exemple

AgentCore CLI

La CLI résout serviceNames logGroupNames automatiquement à partir de la configuration du projet lorsque vous utilisez --runtime :


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

Avec drapeaux en option :


# 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

Par défaut, la commande démarre la tâche et revient immédiatement. Passez --wait au bloc jusqu'à ce que la tâche atteigne l'état terminal (COMPLETEDFAILED, ouSTOPPED), après quoi la CLI affiche les scores moyens par évaluateur et enregistre les résultats dans. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationprend également en charge les drapeaux suivants :

--wait— bloquez jusqu'à ce que la tâche atteigne un état terminal.
--json— émet une sortie JSON lisible par machine.
--kms-key <arn>— chiffrez les résultats de l'évaluation par lots à l'aide d'une clé KMS gérée par le client.
--dataset <name>/--dataset-version <version>— invoque l'agent avec des scénarios d'ensemble de données avant l'évaluation par lots (omettez la version d'un fichier local ou utilisezN/DRAFT).
--endpoint <name>— cible un point de terminaison d'exécution spécifique (par exemple,PROMPT_V1) ; la valeur par défaut est alors DEFAULT la variable d'AGENTCORE_RUNTIME_ENDPOINTenvironnement.
--evaluator-arn <arns…>— évaluateurs de référence par ARN au lieu de. -e

La plupart des drapeaux ont des alias courts : -r (--runtime), -e (--evaluator), -n (--name), -d (--lookback-days), -s (--session-ids) et -g (--ground-truth).

Pour gérer une tâche après son démarrage, exécutez agentcore stop batch-evaluation -i <id> pour arrêter une tâche en cours et agentcore archive batch-evaluation -i <id> archiver un enregistrement de tâche.

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))

Avec le filtrage des identifiants de session :


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()),
)

Avec filtrage par plage de temps :


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()),
)

Paramètres de demande

Paramètre	Type	Obligatoire	Description
`batchEvaluationName`	Chaîne	Oui	Nom de la tâche d'évaluation par lots. Motif : commence par une lettre, des caractères alphanumériques et des traits de soulignement, 48 caractères maximum.
`dataSourceConfig`	Objet	Oui	Où trouver les sessions des agents. Spécifiez une `cloudWatchLogs` source avec le nom de service de votre agent et soit les noms exacts des groupes de journaux, soit les préfixes des noms des groupes de journaux. Reportez-vous à Source de la session ci-dessous.
`evaluators`	List	Oui	Liste des évaluateurs. Chaque entrée possède un `evaluatorId` champ (par exemple,`Builtin.GoalSuccessRate`). Maximum de 10 évaluateurs.
`evaluationMetadata`	Objet	Non	Contient `sessionMetadata` une liste des informations de base et des métadonnées par session. Maximum de 500 entrées.
`outputConfig`	Objet	Non	CloudWatch Destination facultative pour les résultats par session et les mesures de score. Spécifiez a `cloudWatchConfig` pour choisir le groupe de journaux de résultats et l'espace de noms des métriques. Reportez-vous à Résultat de sortie ci-dessous.
`clientToken`	Chaîne	Non	Jeton d'idempotence. Si vous réessayez une demande avec le même jeton client, le service renvoie la tâche existante au lieu d'en créer une nouvelle.

Source de la session

Le dataSourceConfig paramètre spécifie l'emplacement CloudWatch des journaux où le service découvre les sessions des agents.

Champs obligatoires

Champ	Type	Description
`cloudWatchLogs.serviceNames`	Liste des chaînes (exactement 1)	Le nom du service qui identifie les traces de votre agent dans CloudWatch. Convention :`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Liste des chaînes (1 à 5)	Une façon de sélectionner les groupes de journaux d'entrée. Spécifiez les noms exacts des groupes de CloudWatch journaux dans lesquels la télémétrie de l'agent est stockée. Mutuellement exclusif avec `logGroupNamePrefixes`.
`cloudWatchLogs.logGroupNamePrefixes`	Liste des chaînes (1 à 5)	Une façon de sélectionner les groupes de journaux d'entrée. Le service découvre les sessions de chaque groupe de journaux dont le nom commence par l'un de ces préfixes, de sorte que les groupes de journaux correspondants nouvellement créés sont automatiquement récupérés. Mutuellement exclusif avec `logGroupNames`.

Spécifiez exactement l'un des logGroupNames oulogGroupNamePrefixes. Dans les deux cas, serviceNames il est nécessaire d'identifier les traces de votre agent dans les groupes de journaux sélectionnés.

Si vous utilisez logGroupNamePrefixes pour faire correspondre les groupes de journaux Amazon Bedrock AgentCore Runtime, assurez-vous que votre environnement d'exécution envoie des spans au propre groupe de journaux de l'agent. Pour les agents qui utilisent toujours le groupe de aws/spans journaux partagé, définissez UNIFIED_TRACES_DESTINATION_ENABLED=true sur le runtime. Pour plus d'informations, consultez Span destination pour les agents hébergés dans l' AgentCore environnement d'exécution Amazon Bedrock.


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

Champs facultatifs

Champ	Type	Description
`cloudWatchLogs.filterConfig.sessionIds`	Liste de chaînes	Evaluez uniquement ces ID de session spécifiques. En cas d'omission, le service découvre toutes les sessions du groupe de journaux.
`cloudWatchLogs.filterConfig.timeRange.startTime`	Date/heure ISO 8601	Filtrez les sessions créées après cette date.
`cloudWatchLogs.filterConfig.timeRange.endTime`	Date/heure ISO 8601	Filtrez les sessions créées avant cette date.

Résultat de sortie

Par défaut, les résultats de l'évaluation par lots sont envoyés à un groupe de journaux dédié géré par les services. Utilisez-le outputConfig.cloudWatchConfig pour contrôler où les résultats par session sont écrits et quel espace de noms de CloudWatch métriques reçoit les scores d'évaluation.

Choisissez où les résultats sont écrits

DEDICATED_LOG_GROUP(par défaut) — Écrit les résultats dans un groupe de journaux de résultats dédié. Si vous ne le définissez paslogGroupName, le service gère le groupe pour vous. Pour utiliser votre propre groupe, configurez logGroupName (voirUtiliser un groupe de journaux de sortie personnalisé).
SOURCE_LOG_GROUP— Réécrit les résultats dans le même groupe de journaux que celui dans lequel les traces de l'agent ont été lues. Lorsque vous utilisez cette valeur, ne la définissez paslogGroupName.

Utiliser un groupe de journaux de sortie personnalisé

PourDEDICATED_LOG_GROUP, configurez logGroupName pour écrire les résultats dans le groupe de journaux de votre choix. Un groupe de journaux existant est utilisé tel quel ; s'il n'existe pas, le service le crée, ce qui nécessite l'attribution logs:CreateLogGroup du rôle d'exécution. Le nom ne peut pas figurer dans l'/aws/bedrock-agentcore/evaluations/espace de noms réservé au service, à l'exception du groupe par défaut géré par le service.


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

Publier des métriques dans un espace de noms personnalisé

Configurez metricsNamespace pour publier les indicateurs de score dans votre propre CloudWatch espace de noms au lieu deBedrock-AgentCore/Evaluations. La valeur ne peut pas commencer parAWS/.


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

Réponse

Champ	Type	Description
`batchEvaluationId`	Chaîne	Identifiant unique pour l'évaluation du lot.
`batchEvaluationArn`	Chaîne	ARN de l'évaluation du lot.
`batchEvaluationName`	Chaîne	Le nom que vous avez indiqué.
`status`	Chaîne	Statut initial. L'un des :`PENDING`,`IN_PROGRESS`.
`evaluators`	List	Les évaluateurs utilisés.
`createdAt`	Horodatage	Quand l'emploi a été créé.
`outputConfig`	Objet	CloudWatch destination pour les résultats par session et les mesures de score.

Erreurs

Erreur	Statut HTTP	Description
`ValidationException`	400	Paramètres de demande non valides. Vérifiez les contraintes des champs et les champs obligatoires.
`AccessDeniedException`	403	Autorisations insuffisantes. Vérifiez les politiques IAM.
`ConflictException`	409	Une évaluation par lots avec le même jeton client existe déjà avec différents paramètres.
`ThrottlingException`	429	Taux de demandes dépassé. Réessayez avec un backoff exponentiel.
`InternalServerException`	500	Service-side erreur. Réitérez la demande.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Prise en main

Obtenir les résultats de l'évaluation par lots