View a markdown version of this page

Recommandations - Amazon Bedrock AgentCore
Modes de saisie de configurationSources de traçage des agents

Recommandations

Les recommandations utilisent l'IA pour générer des configurations d'agents optimisées à partir de traces de session réelles. Au lieu de réécrire manuellement les instructions ou les descriptions des outils, vous redirigez le service sur les traces de votre agent, vous spécifiez un évaluateur cible comme signal de récompense et vous recevez une configuration optimisée.

Note

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

Amazon Bedrock AgentCore prend en charge deux types de recommandations :

  • Recommandation rapide du système : analyse les traces des agents et génère une invite système optimisée qui améliore les performances de l'évaluateur cible. Le service identifie les modèles de défaillance et ajoute des instructions comportementales spécifiques.

  • Recommandation concernant la description de l'outil : analyse les traces des agents et génère des descriptions d'outils plus précises afin de réduire la confusion lors de la sélection des outils. Cela est utile lorsque les agents sélectionnent le mauvais outil pour des demandes ambiguës.

Chaque recommandation nécessite deux entrées : la configuration actuelle de l'agent à optimiser et les traces de l'agent à analyser.

Rubriques

Modes de saisie de configuration

Vous pouvez fournir la configuration actuelle de deux manières :

  • Texte intégré : fournissez la configuration directement sous forme de chaîne dans la demande d'API. Pour les recommandations d'invite du système, transmettez le texte de l'invite dans le systemPrompt.text champ. Pour les recommandations relatives à la description des outils, transmettez le nom et la description de chaque outil dans la toolDescription.toolDescriptionText.tools liste. Ce mode est utile pour une expérimentation rapide, lorsque vous souhaitez tester une invite sur laquelle vous êtes en train d'itérer activement ou lorsque votre configuration n'est pas stockée dans un bundle.

    Type de recommandation Drapeaux CLI Champ API

    Invite système

    --inline "prompt text" ou --prompt-file ./path.txt

    systemPrompt.text

    Description de l'outil

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: liste d'objets avec toolName et toolDescription

  • Ensemble de configuration : faites référence à une version d'ensemble de configuration existante. Le service lit la configuration actuelle à partir du bundle en utilisant le chemin JSON que vous spécifiez, génère la version optimisée et réécrit le résultat dans une nouvelle version du bundle. Cela permet de conserver votre historique d'optimisation versionné en même temps que votre offre groupée. Ce mode est utile lorsque vous gérez les configurations de manière centralisée avec des ensembles de configuration et que vous souhaitez que la sortie optimisée soit automatiquement réécrite dans le bundle.

    Type de recommandation Drapeaux CLI Champ API

    Invite système

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundleavec bundleArnversionId, systemPromptJsonPath

    Description de l'outil

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (répétez pour chaque outil)

    toolDescription.configurationBundleavec bundleArnversionId, et une tools liste contenant toolName et toolDescriptionJsonPath

    Lorsque vous utilisez un bundle de configuration, le résultat de la recommandation inclut un configurationBundle champ avec le bundleArn et un nouveau versionId pointant vers la version du bundle contenant la configuration optimisée.

Sources de traçage des agents

Le agentTraces paramètre accepte l'une des deux sources suivantes :

  • CloudWatch Journaux : à utiliser lorsque l'environnement d'exécution de votre agent écrit des données de télémétrie dans. CloudWatch Le service lit les traces directement à partir des groupes de journaux spécifiés dans un intervalle de temps requis. Vous devez fournir logGroupArnsserviceNames,startTime, etendTime. Un rule champ facultatif vous permet de filtrer les traces (par exemple, en sélectionnant uniquement les sessions dont le chiffre goal_success_rate est inférieur à un seuil).

    Note

    L'API de recommandations utilise des ARN de groupes de journaux (logGroupArns), et non des noms de groupes de journaux. Cela diffère des évaluations par lots, qui utilisentlogGroupNames.

    Champ Type Obligatoire Description

    cloudwatchLogs.logGroupArns

    Liste de chaînes

    Oui

    CloudWatch Les journaux enregistrent les ARN des groupes dans lesquels la télémétrie de l'agent est stockée. Format :arn:aws:logs:{region}:{account}:log-group:{log-group-name}.

    cloudwatchLogs.serviceNames

    Liste de chaînes

    Oui

    Noms de service qui identifient les traces de votre agent dans CloudWatch. Convention :{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    Date/heure ISO 8601

    Oui

    Début de la fenêtre de collecte de traces. Seules les traces passées ce délai sont incluses.

    cloudwatchLogs.endTime

    Date/heure ISO 8601

    Oui

    Fin de la fenêtre de collecte de traces. Seules les traces antérieures à cette heure sont incluses.

    cloudwatchLogs.rule

    Objet

    Non

    Règle de filtre facultative pour affiner la sélection des traces. Contient une filters liste dans laquelle chaque filtre spécifie unkey, operator (tel queLESS_THAN), et value (tel que{"doubleValue": 0.5}).
    Exemple
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    Avec un filtre de règles facultatif pour sélectionner uniquement les sessions peu performantes :

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • Durée des sessions en ligne : à utiliser lorsque des traces sont disponibles localement (par exemple, à partir d'un test local, d'un CI/CD pipeline ou d'une session spécifique pour laquelle vous souhaitez optimiser). Vous fournissez les intervalles directement dans le corps de la demande d'API sous forme de liste d'objets OpenTelemetry-compatible span.

    Champ Type Obligatoire Description

    sessionSpans

    Liste d’objets

    Oui

    La trace de l'agent s'étend au OpenTelemetry-compatible format. Chaque intervalle inclut l'ID de trace, l'ID de l'intervalle, le nom, les horodatages et les attributs.
    Exemple
    AgentCore CLI

    S'étend sur le fichier (lit les intervalles à partir d'un fichier JSON local et les transmet sous forme de plages intégrées) :

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

    Identifiants de session spécifiques (la CLI collecte les spans côté client et les transmet sous forme de spans intégrés) :

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

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

agent_traces = {
    "sessionSpans": spans
}
Note

agentcore run recommendationest asynchrone. Sans--wait, la commande soumet la tâche de recommandation et revient immédiatement ; la tâche démarre dans un état non terminal (tel que PENDING ouIN_PROGRESS), et vous récupérez le résultat ultérieurement. Passez --wait au bloc jusqu'à ce que la recommandation atteigne un état terminal. Pour rechercher ou récupérer le résultat d'une tâche soumise, exécutezagentcore view recommendation <id>, où se id trouve l'ID de la tâche de recommandation.

La AgentCore CLI fournit des indicateurs pratiques qui correspondent aux types de sources de suivi de l'API sous-jacents :

Drapeau CLI Mappage d’API Description

--lookback <days>

cloudwatchLogsavec calculateur startTime et endTime

Collecte les traces des N derniers jours via CloudWatch les journaux. La CLI résout les ARN des groupes de journaux et les noms de service à partir de la configuration d'exécution.

--session-id <id>

sessionSpans(en ligne)

Collecte les intervalles pour la session spécifiée côté client et les transmet sous forme d'intervalles de session en ligne. L'API de recommandation elle-même ne prend pas en charge le filtrage des identifiants de session sur les CloudWatch sources.

--spans-file <path>

sessionSpans(en ligne)

Lit les spans à partir d'un fichier JSON local et les transmet sous forme d'intervalles de session en ligne.

--wait

n/a (sondage côté client)

Bloquez jusqu'à ce que la recommandation atteigne un état terminal.