View a markdown version of this page

Obtenha recomendação - Amazon Bedrock AgentCore
Exemplos de códigoParâmetros de solicitaçãoRespostaExemplos de respostaErros

Obtenha recomendação

Recupere o status e os resultados de uma recomendação. Pesquise essa operação até que a recomendação atinja um estado terminal (COMPLETEDouFAILED).

Exemplos de código

exemplo
AgentCore CLI

agentcore run recommendationenvia um trabalho de atirar e esquecer. Passe --wait para o bloco até que ele atinja um estado terminal ou verifique-o posteriormente pelo ID:

agentcore view recommendation <recommendation-id>

Liste todos os trabalhos de recomendação ou visualize como JSON:

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

Faça uma pesquisa até a conclusão e extraia o resultado:

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']}")

Extraia a referência do pacote de configuração para uso em A/B testes:

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}")

Parâmetros de solicitação

Parâmetro Tipo Obrigatório Descrição

recommendationId

String

Sim

O ID da recomendação retornado porStartRecommendation. Passado como parâmetro de caminho.

Resposta

Campo Tipo Description

recommendationId

String

Identificador exclusivo da recomendação.

recommendationArn

String

ARN da recomendação.

name

String

O nome da recomendação.

type

String

SYSTEM_PROMPT_RECOMMENDATION ou TOOL_DESCRIPTION_RECOMMENDATION.

status

String

Status atual:PENDING,IN_PROGRESS,COMPLETED,FAILED, ouDELETING.

recommendationConfig

Objeto

A configuração que você enviou.

recommendationResult

Objeto

Presente quando o status éCOMPLETED. Contém a configuração otimizada. O formato depende do tipo de recomendação.

createdAt

Timestamp

Quando a recomendação foi criada.

updatedAt

Timestamp

Quando a recomendação foi atualizada pela última vez.

Campos de resultados do prompt do sistema

Presente recommendationResult.systemPromptRecommendationResult quando o tipo éSYSTEM_PROMPT_RECOMMENDATION:

Campo Tipo Description

recommendedSystemPrompt

String

O texto otimizado do prompt do sistema.

configurationBundle

Objeto

Presente quando a entrada era um pacote de configuração. Contém bundleArn e versionId para a nova versão do pacote.

explanation

String

Uma explicação do motivo pelo qual a recomendação foi gerada e o raciocínio por trás das mudanças sugeridas.

errorCode

String

Presente em caso de falha. Código de erro.

errorMessage

String

Presente em caso de falha. Human-readable descrição.

Campos de resultados da descrição da ferramenta

Presente recommendationResult.toolDescriptionRecommendationResult quando o tipo éTOOL_DESCRIPTION_RECOMMENDATION:

Campo Tipo Description

tools

Lista

Per-tool resultados. Cada entrada contém toolNamerecommendedToolDescription, explanation e.

configurationBundle

Objeto

Presente quando a entrada era um pacote de configuração. Contém bundleArn e versionId para a nova versão do pacote.

errorCode

String

Presente em caso de falha. Código de erro.

errorMessage

String

Presente em caso de falha. Human-readable descrição.

Exemplos de resposta

Recomendação imediata do sistema concluída (entrada em linha):

{
    "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"
}

Recomendação de alerta do sistema concluída (entrada do pacote de configuração):

{
    "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"
}

Recomendação completa da descrição da ferramenta:

{
    "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"
}

Recomendação falhada:

{
    "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"
}

Erros

Erro Status HTTP Description

ResourceNotFoundException

404

Nenhuma recomendação encontrada com o ID especificado.

ValidationException

400

Formato de ID de recomendação inválido.

AccessDeniedException

403

Permissões insuficientes.

ThrottlingException

429

Taxa de solicitações excedida.

InternalServerException

500

Service-side erro.