View a markdown version of this page

Inicie uma recomendação de descrição da ferramenta - Amazon Bedrock AgentCore
Exemplos de códigoParâmetros de solicitaçãoModos de entrada da descrição da ferramentaRespostaResultado da recomendaçãoErros

Inicie uma recomendação de descrição da ferramenta

Comece uma recomendação para gerar descrições otimizadas de ferramentas para seu agente. O serviço analisa os rastreamentos do agente para identificar a confusão na seleção de ferramentas e produz descrições detalhadas que reduzem a ambigüidade quando o agente escolhe entre as ferramentas.

nota

As recomendações são geradas pelos LLMs. Revise e teste antes de aplicá-las.

Exemplos de código

exemplo
AgentCore CLI
nota

Ao contrário das recomendações imediatas do sistema, que exigem exatamente uma-e/--evaluator, as execuções de descrição da ferramenta são -e/--evaluator totalmente omitidas.

Descrições de ferramentas em linha com CloudWatch traços:

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

Descrições de ferramentas embutidas com um arquivo de extensões:

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

Descrições de ferramentas em linha com IDs de sessão específicos:

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

Pacote de configuração com CloudWatch traços:

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

Pacote de configuração com um arquivo de extensões:

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

Além disso--lookback,--spans-file, e--session-id, agentcore run recommendation aceita mais duas fontes de rastreamento: --from-insights <id> (use um insight local executado como fonte de rastreamento; a CLI resolve o ARN de avaliação em lote) e --batch-evaluation-arn <arn> (use um ARN de avaliação em lote diretamente). Para obter uma visão geral de todas as fontes de rastreamento, consulte Fontes de rastreamento para obter recomendações. Você também pode adicionar --kms-key <arn> para criptografar os resultados da recomendação com uma chave KMS gerenciada pelo cliente.

Para bloquear até que a recomendação atinja um estado terminal, adicione--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

Recupere o resultado completo, incluindo as descrições otimizadas da ferramenta, comagentcore view recommendation:

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

Descrições de ferramentas em linha com CloudWatch traços:

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

Descrições de ferramentas em linha com extensões embutidas:

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()),
)

Pacote de configuração com CloudWatch traços:

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()),
)

Pacote de configuração com extensões em linha:

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()),
)

Parâmetros de solicitação

Parâmetro Tipo Obrigatório Descrição

name

String

Sim

Um nome para a recomendação. Máximo de 48 caracteres. Padrão:[a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

String

Sim

Deve ser TOOL_DESCRIPTION_RECOMMENDATION.

recommendationConfig

Objeto

Sim

Contém toolDescriptionRecommendationConfig a configuração da recomendação.

description

String

Não

Descrição opcional. Máximo de 4096 caracteres.

clientToken

String

Não

Símbolo de idempotência. Se você repetir uma solicitação com o mesmo token de cliente, o serviço retornará a recomendação existente em vez de criar uma nova.

DescriptionRecommendationConfig campos de ferramentas

Campo Tipo Obrigatório Description

toolDescription

Union

Sim

As descrições atuais da ferramenta para otimizar. Forneça toolDescriptionText (lista em linha de pares de nomes e descrições de ferramentas) ou configurationBundle (referência de pacote com caminhos JSON para cada descrição de ferramenta).

agentTraces

Union

Sim

Fonte de rastreamento para análise. Consulte as fontes do Trace para obter recomendações.
nota

As recomendações de descrição da ferramenta não exigem umevaluationConfig. Diferentemente das recomendações imediatas do sistema, que usam um avaliador como sinal de otimização, as recomendações de descrição da ferramenta analisam os padrões de seleção de ferramentas diretamente dos rastreamentos do agente para identificar a ambigüidade entre as ferramentas e gerar descrições mais precisas.

Modos de entrada da descrição da ferramenta

Modo Sinalizadores CLI Campo da API

Texto embutido

--tools "name:description"(repita para cada ferramenta)

toolDescription.toolDescriptionText.tools. Lista de objetos com toolName e toolDescription

Pacote de configuração

--bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:field" (repita para cada ferramenta)

toolDescription.configurationBundlecombundleArn,versionId, e tools lista contendo toolName e toolDescriptionJsonPath

Ao usar um pacote de configuração, o resultado inclui uma nova versão do pacote com as descrições otimizadas da ferramenta aplicadas.

Resposta

Campo Tipo Description

recommendationId

String

Identificador exclusivo da recomendação.

recommendationArn

String

ARN da recomendação.

name

String

O nome que você especificou.

type

String

TOOL_DESCRIPTION_RECOMMENDATION.

status

String

Status inicial: PENDING ouIN_PROGRESS.

createdAt

Timestamp

Quando a recomendação foi criada.

updatedAt

Timestamp

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

Resultado da recomendação

Quando a recomendação atinge o COMPLETED status (recuperado por meio de Obter uma recomendação), o resultado contém:

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 aponta para uma nova versão do pacote com as descrições otimizadas aplicadas.

errorCode

String

Apresente se a recomendação falhar. Código de erro descrevendo a falha.

errorMessage

String

Apresente se a recomendação falhar. Human-readable descrição do erro.

Erros

Erro Status HTTP Description

ValidationException

400

Parâmetros de solicitação inválidos. Verifique as restrições de campo e os campos obrigatórios.

AccessDeniedException

403

Permissões insuficientes. Verifique as políticas do IAM.

ConflictException

409

Já existe uma recomendação com o mesmo token de cliente com parâmetros diferentes.

ServiceQuotaExceededException

402

Você excedeu o número máximo de recomendações simultâneas.

ThrottlingException

429

Taxa de solicitações excedida. Novas tentativas com recuo exponencial.

InternalServerException

500

Service-side erro. Repetir a solicitação .