View a markdown version of this page

Obtenir une recommandation - Amazon Bedrock AgentCore
Exemples de codeParamètres de demandeRéponseExemple de réponsesErreurs

Obtenir une recommandation

Récupérez le statut et les résultats d'une recommandation. Interrogez cette opération jusqu'à ce que la recommandation atteigne un état terminal (COMPLETEDouFAILED).

Exemples de code

Exemple
AgentCore CLI

agentcore run recommendationsoumet une tâche de type « fire and forget ». Passez --wait au bloc jusqu'à ce qu'il atteigne un état terminal, ou vérifiez-le plus tard par identifiant :

agentcore view recommendation <recommendation-id>

Répertoriez toutes les tâches recommandées ou affichez-les au format JSON :

agentcore view recommendation
agentcore view recommendation <recommendation-id> --json
AWS SDK (boto3)

Sondez jusqu'à la fin et extrayez le résultat :

import time
import boto3

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

# Poll until terminal state
while True:
    result = client.get_recommendation(recommendationId=recommendation_id)
    status = result["status"]
    print(f"Status: {status}")

    if status in ("COMPLETED", "FAILED"):
        break
    time.sleep(15)

# Extract system prompt result
if status == "COMPLETED":
    rec_result = result.get("recommendationResult", {})

    if "systemPromptRecommendationResult" in rec_result:
        sys_result = rec_result["systemPromptRecommendationResult"]
        print(f"Recommended prompt:\n{sys_result['recommendedSystemPrompt']}")

        if "explanation" in sys_result:
            print(f"Explanation:\n{sys_result['explanation']}")

        if "configurationBundle" in sys_result:
            bundle = sys_result["configurationBundle"]
            print(f"New bundle version: {bundle['versionId']}")

    elif "toolDescriptionRecommendationResult" in rec_result:
        tool_result = rec_result["toolDescriptionRecommendationResult"]
        for tool in tool_result.get("tools", []):
            print(f"{tool['toolName']}: {tool['recommendedToolDescription']}")
            if "explanation" in tool:
                print(f"  Explanation: {tool['explanation']}")

elif status == "FAILED":
    rec_result = result.get("recommendationResult", {})
    r = rec_result.get("systemPromptRecommendationResult") or rec_result.get("toolDescriptionRecommendationResult")
    print(f"Error: [{r['errorCode']}] {r['errorMessage']}")

Extrayez la référence du bundle de configuration à utiliser lors A/B des tests :

result = client.get_recommendation(recommendationId=recommendation_id)

if result["status"] == "COMPLETED":
    rec_result = result["recommendationResult"]
    sys_result = rec_result.get("systemPromptRecommendationResult", {})

    if "configurationBundle" in sys_result:
        bundle_arn = sys_result["configurationBundle"]["bundleArn"]
        version_id = sys_result["configurationBundle"]["versionId"]
        print(f"Use in A/B test: bundle={bundle_arn}, version={version_id}")

Paramètres de demande

Paramètre Type Obligatoire Description

recommendationId

String

Oui

L'ID de recommandation renvoyé parStartRecommendation. Transmis en tant que paramètre de chemin.

Réponse

Champ Type Description

recommendationId

String

Identifiant unique de la recommandation.

recommendationArn

String

ARN de la recommandation.

name

String

Le nom de la recommandation.

type

String

SYSTEM_PROMPT_RECOMMENDATION ou TOOL_DESCRIPTION_RECOMMENDATION.

status

String

État actuel : PENDINGIN_PROGRESS,COMPLETED,FAILED, ouDELETING.

recommendationConfig

Objet

La configuration que vous avez soumise.

recommendationResult

Objet

Présent lorsque le statut l'estCOMPLETED. Contient la configuration optimisée. La forme dépend du type de recommandation.

createdAt

Horodatage

Date à laquelle la recommandation a été créée.

updatedAt

Horodatage

Date de dernière mise à jour de la recommandation.

Champs de résultats instantanés du système

Présent recommendationResult.systemPromptRecommendationResult lorsque le type est SYSTEM_PROMPT_RECOMMENDATION :

Champ Type Description

recommendedSystemPrompt

String

Le texte d'invite du système optimisé.

configurationBundle

Objet

Présent lorsque l'entrée était un bundle de configuration. Contient bundleArn et versionId pour la nouvelle version du bundle.

explanation

String

Une explication de la raison pour laquelle la recommandation a été émise et le raisonnement qui sous-tend les modifications proposées.

errorCode

String

Présent en cas d'échec. Code d’erreur.

errorMessage

String

Présent en cas d'échec. Human-readable description.

Champs de résultats de description de l'outil

Présent recommendationResult.toolDescriptionRecommendationResult lorsque le type est TOOL_DESCRIPTION_RECOMMENDATION :

Champ Type Description

tools

List

Per-tool résultats. Chaque entrée contient toolNamerecommendedToolDescription, etexplanation.

configurationBundle

Objet

Présent lorsque l'entrée était un bundle de configuration. Contient bundleArn et versionId pour la nouvelle version du bundle.

errorCode

String

Présent en cas d'échec. Code d’erreur.

errorMessage

String

Présent en cas d'échec. Human-readable description.

Exemple de réponses

Recommandation rapide du système terminée (saisie en ligne) :

{
    "recommendationId": "MyPromptRec-Ab1Cd2Ef3G",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyPromptRec-Ab1Cd2Ef3G",
    "name": "my-prompt-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "recommendedSystemPrompt": "<optimized system prompt text>",
            "explanation": "<explanation of why the recommendation was generated>"
        }
    },
    "createdAt": "2025-03-15T10:00:00Z",
    "updatedAt": "2025-03-15T10:05:30Z"
}

Recommandation rapide du système terminée (entrée du bundle de configuration) :

{
    "recommendationId": "MyBundleRec-Xy9Zw8Vq1R",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyBundleRec-Xy9Zw8Vq1R",
    "name": "my-bundle-prompt-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "recommendedSystemPrompt": "<optimized system prompt text>",
            "configurationBundle": {
                "bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-Ab1Cd2Ef3G",
                "versionId": "12345678-1234-1234-1234-123456789012"
            },
            "explanation": "<explanation of why the recommendation was generated>"
        }
    },
    "createdAt": "2025-03-15T10:00:00Z",
    "updatedAt": "2025-03-15T10:06:12Z"
}

Recommandation de description de l'outil terminée :

{
    "recommendationId": "MyToolRec-Qr5St6Uv7W",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyToolRec-Qr5St6Uv7W",
    "name": "my-tool-rec",
    "type": "TOOL_DESCRIPTION_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "toolDescriptionRecommendationResult": {
            "tools": [
                {
                    "toolName": "<tool-name-1>",
                    "recommendedToolDescription": "<optimized description for tool 1>",
                    "explanation": "<explanation of why this tool description was changed>"
                },
                {
                    "toolName": "<tool-name-2>",
                    "recommendedToolDescription": "<optimized description for tool 2>",
                    "explanation": "<explanation of why this tool description was changed>"
                }
            ]
        }
    },
    "createdAt": "2025-03-15T11:00:00Z",
    "updatedAt": "2025-03-15T11:04:45Z"
}

Recommandation échouée :

{
    "recommendationId": "MyFailedRec-Mn3Op4Qr5S",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyFailedRec-Mn3Op4Qr5S",
    "name": "my-failed-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "FAILED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "errorCode": "<error-code>",
            "errorMessage": "<human-readable error description>"
        }
    },
    "createdAt": "2025-03-15T12:00:00Z",
    "updatedAt": "2025-03-15T12:01:10Z"
}

Erreurs

Erreur Statut HTTP Description

ResourceNotFoundException

404

Aucune recommandation n'a été trouvée avec l'ID spécifié.

ValidationException

400

Format d'ID de recommandation non valide.

AccessDeniedException

403

Autorisations insuffisantes.

ThrottlingException

429

Le taux de demandes a été dépassé.

InternalServerException

500

Service-side erreur.