Exemples de code Paramètres de demande Modes de saisie des descriptions de l'outil Réponse Résultat de la recommandation Erreurs

Commencer une recommandation de description d'outil

Créez 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 la confusion lors de la sélection des outils et produit des descriptions 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 en nécessitent exactement 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--session-id, et agentcore run recommendation accepte deux autres sources de trace : --from-insights <id> (utilisez une exécution locale d'insights comme source de trace ; la CLI résout l'ARN d'évaluation par lots) et --batch-evaluation-arn <arn> (utilise directement un ARN d'évaluation par lots). Pour une vue d'ensemble de toutes les sources de trace, voir Sources de trace 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 final, y compris les descriptions optimisées des outils, 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 en ligne avec des étendues en ligne :


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 spans en ligne :


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`	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 `TOOL_DESCRIPTION_RECOMMENDATION`.
`recommendationConfig`	Objet	Oui	Contient `toolDescriptionRecommendationConfig` 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.

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 chemins JSON vers la description de chaque 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 des outils 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.

Modes de saisie des descriptions de l'outil

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éter pour chaque outil)	`toolDescription.configurationBundle`avec`bundleArn`,`versionId`, et `tools` 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`	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	`TOOL_DESCRIPTION_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
`tools`	List	Per-tool résultats. Chaque entrée contient `toolNamerecommendedToolDescription`, et`explanation`.
`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 les descriptions optimisées appliqué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

Recommandation rapide du système

Obtenir une recommandation