View a markdown version of this page

Recommandations - Base rocheuse de l'Amazonie AgentCore
Modes de saisie de configurationSources de trace des agents

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 d'outils, vous dirigez le service vers les traces de votre agent, vous spécifiez un évaluateur cible comme signal de récompense et vous bénéficiez d'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 d'invite 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 relative à la description des outils : 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. Ceci est utile lorsque les agents sélectionnent le mauvais outil pour répondre à des demandes ambiguës.

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

Rubriques

Modes de saisie de configuration

Vous pouvez fournir la configuration actuelle de l'une des deux manières suivantes :

  • Texte en ligne : Fournissez la configuration directement sous forme de chaîne dans la demande d'API. Pour obtenir des recommandations rapides sur le système, transmettez le texte de l'invite dans le systemPrompt.text champ. Pour les recommandations relatives à la description des outils, indiquez le nom et la description de chaque outil dans la toolDescription.toolDescriptionText.tools liste. Ce mode est utile pour des expérimentations rapides, 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 des objets avec toolName et toolDescription

  • Ensemble de configuration : faites référence à une version existante du bundle de configuration. Le service lit la configuration actuelle du bundle à l'aide du 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 la version de votre historique d'optimisation en même temps que votre bundle. 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éter pour chaque outil)

    toolDescription.configurationBundleavecbundleArn,versionId, et tools liste contenant toolName et toolDescriptionJsonPath

    Lors de l'utilisation d'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 qui contient la configuration optimisée.

Sources de trace des agents

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

  • CloudWatch Journaux : à utiliser lorsque l'environnement d'exécution de votre agent écrit des données télémétriques 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 la valeur goal_success_rate est inférieure à 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 Enregistre les ARN des groupes de journaux 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

    Des 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 des traces. Seules les traces postérieures à cette période sont incluses.

    cloudwatchLogs.endTime

    Date/heure ISO 8601

    Oui

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

    cloudwatchLogs.rule

    Objet

    Non

    Règle de filtre optionnelle 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 optionnel permettant de 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}
                }
            ]
        },
    }
}

  • Périodes de session 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 par rapport à laquelle vous souhaitez optimiser). Vous fournissez les spans directement dans le corps de la demande d'API sous la forme d'une liste d'objets OpenTelemetry-compatible span.

    Champ Type Obligatoire Description

    sessionSpans

    Liste d’objets

    Oui

    La trace de l'agent s'étend sur plusieurs OpenTelemetry-compatible formats. Chaque plage comprend un identifiant de trace, un identifiant de span, un nom, des horodatages et des attributs.
    Exemple
    AgentCore CLI

    Fichier Spans (lit les spans d'un fichier JSON local 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 assistant..." \
  --spans-file agent-traces.json

    Identifiants de session spécifiques (la CLI collecte les spans 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 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

Les sources de suivi de l'évaluation par lots et de l'évaluation en ligne sont disponibles uniquement pour les recommandations rapides du système.

  • Évaluation par lots : à utiliser lorsque vous avez terminé une tâche d'évaluation par lots dont vous souhaitez réutiliser les sessions à des fins d'optimisation. Au lieu de collecter à nouveau des traces CloudWatch ou de fournir des spans en ligne, vous référencez l'évaluation du lot directement par son ARN. Cette source est uniquement disponible pour les recommandations rapides du système.

    • Si les évaluateurs utilisés dans le travail d'évaluation par lots correspondent aux évaluateurs spécifiés dans la demande de recommandation, le service réutilise les scores existants.

    • Si les évaluateurs ne correspondent pas, le service effectue de nouvelles évaluations pour les évaluateurs demandés par rapport aux sessions d'évaluation par lots.

      Champ Type Obligatoire Description

      batchEvaluation.batchEvaluationArn

      Chaîne

      Oui

      ARN d'une tâche d'évaluation par lots terminée. Le service réutilise les sessions de cette tâche en tant qu'entrée de trace. Format :arn:aws:bedrock-agentcore:{region}:{account}:batch-evaluation/{id}.
      Exemple
      AWS SDK (boto3)
      agent_traces = {
    "batchEvaluation": {
        "batchEvaluationArn": "<batch-evaluation-arn>"
    }
}

  • Évaluation en ligne : à utiliser lorsque vous disposez d'une configuration d'évaluation en ligne qui évalue en permanence les sessions des agents en direct. L'évaluation en ligne étant un flux continu, vous devez spécifier une fenêtre temporelle (startTimeetendTime) à laquelle la recommandation s'appuie pour délimiter les sessions évaluées. Le service réutilise les notes d'évaluation des sessions d'évaluation en ligne dans la fenêtre spécifiée. Cette source est uniquement disponible pour les recommandations rapides du système.

    Champ Type Obligatoire Description

    onlineEvaluation.onlineEvaluationConfigArn

    Chaîne

    Oui

    ARN d'une configuration d'évaluation en ligne. Le service utilise les sessions évaluées à partir de cette configuration comme entrée de trace. Format :arn:aws:bedrock-agentcore:{region}:{account}:online-evaluation-config/{id}.

    onlineEvaluation.startTime

    Date/heure ISO 8601

    Oui

    Début de la fenêtre d'évaluation. Seules les sessions évaluées après cette période sont incluses.

    onlineEvaluation.endTime

    Date/heure ISO 8601

    Oui

    Fin de la fenêtre d'évaluation. Seules les sessions évaluées avant cette date sont incluses.
    Exemple
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "onlineEvaluation": {
        "onlineEvaluationConfigArn": "<online-evaluation-config-arn>",
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}
Note

agentcore run recommendationest asynchrone. Dans le --wait cas contraire, la commande soumet la tâche de recommandation et la renvoie 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 mode bloc jusqu'à ce que la recommandation atteigne un état terminal. Pour interroger 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 recommandée.

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

Drapeau CLI Mappage d’API Description

--lookback <days>

cloudwatchLogsavec calcul et startTime endTime

Collecte les traces des N derniers jours via CloudWatch Logs. 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 périodes pour la session spécifiée côté client et les transmet en tant que périodes 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 en tant que spans de session en ligne.

--wait

n/a (sondage côté client)

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