Exemples de code Paramètres de demande Choix d'un évaluateur Modes de saisie rapide du système Réponse Résultat de la recommandation Erreurs

Lancer une recommandation rapide du système

Créez une recommandation afin de générer une invite système optimisée pour votre agent. Le service analyse les traces des agents, identifie les modèles de défaillance et produit une invite système révisée qui améliore les performances de l'évaluateur cible.

Note

Les recommandations sont générées par les LLM. Révisez-les et testez-les avant de les appliquer.

Exemples de code

Exemple

AgentCore CLI

La CLI accepte plusieurs sources de trace et trois modes de saisie rapide du système. Combinez-les selon vos besoins :

Sources de trace : CloudWatch Logs (--lookback), spans en ligne (--spans-file), une analyse locale exécutée (--from-insights <id>— utilise une analyse locale exécutée comme source de trace ; résout l'ARN d'évaluation par lots) ou un ARN d'évaluation par lots directement (--batch-evaluation-arn <arn>— utilise un ARN d'évaluation par lots directement comme source de trace)
Saisie rapide du système : texte en ligne (--inline), fichier d'invite (--prompt-file) ou ensemble de configuration (--bundle-name)
Filtre optionnel : ID de session spécifiques (--session-id) pour affiner les traces analysées

Chiffrement facultatif : une clé KMS (--kms-key <arn>— ARN de clé KMS pour le chiffrement des résultats des recommandations)

Invite système en ligne avec CloudWatch traces :


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant. Help users with their orders and returns." \
  --lookback 7 \
  --wait

run recommendationdémarre une tâche asynchrone et renvoie uniquement un recommendationId état initial PENDING ouIN_PROGRESS. Ajoutez --wait au bloc jusqu'à ce que la recommandation atteigne l'état terminal. Pour récupérer le résultat complet ultérieurement, voir Récupérer le résultat.

Invite système en ligne à partir d'un fichier contenant des CloudWatch traces :


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --prompt-file ./system-prompt.txt \
  --lookback 7

Invite système en ligne avec un fichier spans :


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant." \
  --spans-file agent-traces.json

Invite système en ligne avec des identifiants de session spécifiques :

La CLI collecte les spans pour la session spécifiée côté client et les transmet en tant que spans en ligne.


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant." \
  --session-id <session-id-1> <session-id-2>

Ensemble de configuration avec CloudWatch traces :

La CLI résout automatiquement le chemin JSON complet à partir de l'objet configuration parent de l'ARN d'exécution de l'agent. Il vous suffit de fournir le nom de clé qui contient l'invite du système.


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --system-prompt-json-path "system_prompt" \
  --lookback 7

Récupérez le résultat :

view recommendationÀ utiliser avec l'ID de tâche de recommandation pour récupérer le résultat final. Ajoutez --json pour une sortie lisible par machine contenant recommendedSystemPrompt et. explanation


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Texte en ligne avec CloudWatch traces :


import boto3
import json
import uuid
from datetime import datetime, timedelta, timezone

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

now = datetime.now(timezone.utc)

response = client.start_recommendation(
    name="my-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant. Help users with their orders and returns."
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

recommendation_id = response["recommendationId"]
print(f"Started recommendation: {recommendation_id}")
print(f"Status: {response['status']}")

Texte en ligne avec étendues intégrées :


with open("agent-traces.json") as f:
    spans = json.load(f)

response = client.start_recommendation(
    name="my-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant."
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Ensemble de configuration avec CloudWatch traces :


response = client.start_recommendation(
    name="my-bundle-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Ensemble de configuration avec spans en ligne :


response = client.start_recommendation(
    name="my-bundle-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Paramètres de demande

Paramètre	Type	Obligatoire	Description
`name`	Chaîne	Oui	Nom de la recommandation. 48 caractères maximum. Motif :`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	Chaîne	Oui	Doit indiquer `SYSTEM_PROMPT_RECOMMENDATION`.
`recommendationConfig`	Objet	Oui	Contient `systemPromptRecommendationConfig` la configuration de la recommandation.
`description`	Chaîne	Non	Description facultative. 4 096 caractères maximum.
`clientToken`	Chaîne	Non	Jeton d'idempotence. Si vous réessayez une demande avec le même jeton client, le service renvoie la recommandation existante au lieu d'en créer une nouvelle.

PromptRecommendationConfig champs du système

Champ	Type	Obligatoire	Description
`systemPrompt`	Union	Oui	Le système actuel est invité à optimiser. Indiquez soit `text` (chaîne en ligne, 20 000 caractères maximum) soit `configurationBundle` (référence du bundle).
`agentTraces`	Union	Oui	Source de trace à des fins d'analyse. Consultez la section Sources de suivi pour obtenir des recommandations.
`evaluationConfig`	Objet	Oui	Configuration d'évaluation spécifiant l'évaluateur cible. Contient une `evaluators` liste contenant exactement une référence d'évaluateur.

Choix d'un évaluateur

Sélectionnez un évaluateur correspondant à la direction que vous souhaitez améliorer. L'évaluateur que vous sélectionnez détermine vers quoi la recommandation est optimisée ; quel que soit le score le plus élevé obtenu, c'est vers quoi l'optimiseur pousse l'invite.

Vous pouvez utiliser un évaluateur intégré ou fournir un ARN d'évaluation personnalisé. Suivez les instructions suivantes pour choisir :

Si votre agent a une tâche claire à accomplir (réservation, récupération, flux de travail en plusieurs étapes), Builtin.GoalSuccessRate c'est le bon signal.
Si votre agent est plus ouvert et que vous vous souciez de la qualité de l'interaction elle-même, Builtin.Helpfulness c'est une meilleure solution.
Si la qualité qui vous intéresse est spécifique à un domaine ou n'est pas capturée par un évaluateur intégré, utilisez un évaluateur personnalisé pour représenter au mieux la mesure.

Note

Les recommandations prennent en charge les évaluateurs intégrés LLM-as-judge, personnalisés et basés sur du code, mais nécessitent que l'évaluateur renvoie une valeur numérique en tant que signal d'optimisation. Pour les LLM-as-judge évaluateurs personnalisés, configurez le ratingScale avec une numerical échelle (pascategorical). Pour les évaluateurs basés sur le code, incluez le value champ dans le schéma de réponse.

Dans l'API, spécifiez l'évaluateur dans la evaluationConfig.evaluators liste avec exactement une référence d'évaluateur :


"evaluationConfig": {
    "evaluators": [
        {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
    ]
}

Dans l'interface de ligne de commande, utilisez l'--evaluatorindicateur :


--evaluator Builtin.GoalSuccessRate

Modes de saisie rapide du système

Mode	Drapeaux CLI	Champ API
Texte en ligne	`--inline "prompt text"` ou `--prompt-file ./path.txt`	`systemPrompt.text`
Ensemble de configuration	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` + `--system-prompt-json-path <path>`	`systemPrompt.configurationBundle`avec `bundleArnversionId`, `systemPromptJsonPath`

Lorsque vous utilisez un bundle de configuration, le résultat inclut une nouvelle version du bundle avec l'invite système optimisée appliquée.

Réponse

Champ	Type	Description
`recommendationId`	Chaîne	Identifiant unique de la recommandation.
`recommendationArn`	Chaîne	ARN de la recommandation.
`name`	Chaîne	Le nom que vous avez indiqué.
`type`	Chaîne	`SYSTEM_PROMPT_RECOMMENDATION`.
`status`	Chaîne	Statut initial : `PENDING` ou`IN_PROGRESS`.
`createdAt`	Horodatage	Date à laquelle la recommandation a été créée.
`updatedAt`	Horodatage	Date à laquelle la recommandation a été mise à jour pour la dernière fois.

Résultat de la recommandation

Lorsque la recommandation atteint le COMPLETED statut (extrait via Obtenir une recommandation), le résultat contient :

Champ	Type	Description
`recommendedSystemPrompt`	Chaîne	Le texte d'invite optimisé du système.
`configurationBundle`	Objet	Présent lorsque l'entrée était un ensemble de configuration. Contient `bundleArn` et `versionId` pointe vers une nouvelle version du bundle avec l'invite optimisée appliquée.
`explanation`	Chaîne	Une explication de la raison pour laquelle la recommandation a été générée et du raisonnement qui sous-tend les modifications proposées.
`errorCode`	Chaîne	Présent en cas d'échec de la recommandation. Code d'erreur décrivant la panne.
`errorMessage`	Chaîne	Présent en cas d'échec de la recommandation. Human-readable description de l'erreur.

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 recommandation avec le même jeton client existe déjà avec différents paramètres.
`ServiceQuotaExceededException`	402	Vous avez dépassé le nombre maximum de recommandations simultanées.
`ThrottlingException`	429	Le taux de demandes a été 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

Recommandations

Recommandation de description de l'outil