Exemples de code Paramètres de demande Description de l'outil : modes de saisie Réponse Résultat de la recommandation Erreurs

Lancer une recommandation de description d'outil

Lancez une recommandation afin de générer des descriptions d'outils optimisées pour votre agent. Le service analyse les traces des agents pour identifier toute confusion lors de la sélection des outils et produit des descriptions plus précises qui réduisent l'ambiguïté lorsque l'agent choisit entre les outils.

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

Note

Contrairement aux recommandations rapides du système, qui n'en nécessitent qu'une-e/--evaluator, la description de l'outil est -e/--evaluator totalement omise.

Descriptions des outils en ligne avec CloudWatch traces :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7

Descriptions des outils en ligne avec un fichier Spans :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --spans-file agent-traces.json

Descriptions des outils en ligne avec des identifiants de session spécifiques :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --session-id 12345678-1234-1234-1234-123456789012

Ensemble de configuration avec CloudWatch traces :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --lookback 7

Ensemble de configuration avec un fichier spans :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --spans-file agent-traces.json

En outre --lookback--spans-file, et--session-id, agentcore run recommendation accepte deux autres sources de trace : --from-insights <id> (utilisez une analyse locale exécutée comme source de trace ; la CLI résout l'ARN d'évaluation par lots) et --batch-evaluation-arn <arn> (utilisez directement un ARN d'évaluation par lots). Pour une vue d'ensemble de toutes les sources de suivi, consultez la section Sources de suivi pour obtenir des recommandations. Vous pouvez également ajouter ou chiffrer --kms-key <arn> les résultats des recommandations à l'aide d'une clé KMS gérée par le client.

Pour bloquer jusqu'à ce que la recommandation atteigne un état terminal, ajoutez --wait :


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7 \
  --wait

Récupérez le résultat complet, y compris les descriptions des outils optimisés, avec agentcore view recommendation :


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Descriptions des outils 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-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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

Descriptions des outils intégrés avec des étendues intégrées :


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

response = client.start_recommendation(
    name="my-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Ensemble de configuration avec CloudWatch traces :


response = client.start_recommendation(
    name="my-bundle-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Ensemble de configuration avec plages intégrées :


response = client.start_recommendation(
    name="my-bundle-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Paramètres de demande

Paramètre	Type	Obligatoire	Description
`name`	String	Oui	Nom de la recommandation. 48 caractères maximum. Motif :`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	String	Oui	Doit indiquer `TOOL_DESCRIPTION_RECOMMENDATION`.
`recommendationConfig`	Objet	Oui	Contient `toolDescriptionRecommendationConfig` la configuration de la recommandation.
`description`	String	Non	Description facultative. 4096 caractères maximum.
`clientToken`	String	Non	Jeton d'impuissance. 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.

DescriptionRecommendationConfig champs d'outils

Champ	Type	Obligatoire	Description
`toolDescription`	Union	Oui	Les descriptions actuelles des outils à optimiser. Fournissez soit `toolDescriptionText` (liste en ligne des paires nom et description de l'outil), soit `configurationBundle` (référence du bundle avec des chemins JSON vers chaque description d'outil).
`agentTraces`	Union	Oui	Source de trace à des fins d'analyse. Consultez la section Sources de suivi pour obtenir des recommandations.

Note

Les recommandations relatives à la description de l'outil ne nécessitent pas deevaluationConfig. Contrairement aux recommandations rapides du système, qui utilisent un évaluateur comme signal d'optimisation, les recommandations de description des outils analysent les modèles de sélection des outils directement à partir des traces des agents afin d'identifier les ambiguïtés entre les outils et de générer des descriptions plus précises.

Description de l'outil : modes de saisie

Mode	Drapeaux CLI	Champ API
Texte en ligne	`--tools "name:description"`(répétez l'opération pour chaque outil)	`toolDescription.toolDescriptionText.tools`. Liste des objets avec `toolName` et `toolDescription`
Ensemble de configuration	`--bundle-name <bundle-name>`+ `--bundle-version <bundle-version>` + `--tool-desc-json-path "name:field"` (répétez pour chaque outil)	`toolDescription.configurationBundle`avec`bundleArn`,`versionId`, et `tools` une liste contenant `toolName` et `toolDescriptionJsonPath`

Lorsque vous utilisez un bundle de configuration, le résultat inclut une nouvelle version du bundle avec les descriptions d'outils optimisées appliquées.

Réponse

Champ	Type	Description
`recommendationId`	String	Identifiant unique de la recommandation.
`recommendationArn`	String	ARN de la recommandation.
`name`	String	Le nom que vous avez spécifié.
`type`	String	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	String	Statut initial : `PENDING` ou`IN_PROGRESS`.
`createdAt`	Horodatage	Date à laquelle la recommandation a été créée.
`updatedAt`	Horodatage	Date de dernière mise à jour de la recommandation.

Résultat de la recommandation

Lorsque la recommandation atteint le COMPLETED statut (récupéré via Get a recommendation), le résultat contient :

Champ	Type	Description
`tools`	List	Per-tool résultats. Chaque entrée contient `toolNamerecommendedToolDescription`, et`explanation`.
`configurationBundle`	Objet	Présent lorsque l'entrée était un bundle de configuration. Contient `bundleArn` et `versionId` pointe vers une nouvelle version du bundle avec les descriptions optimisées appliquées.
`errorCode`	String	Présent en cas d'échec de la recommandation. Code d'erreur décrivant l'échec.
`errorMessage`	String	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 de 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 des paramètres différents.
`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 recul 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

Recommandation rapide du système

Obtenir une recommandation