View a markdown version of this page

Inicie uma recomendação de descrição da ferramenta - Base da Amazônia AgentCore
Exemplos de códigoParâmetros de solicitaçãoModos de entrada da descrição da ferramentaRespostaResultado da recomendaçãoErros

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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

Comece uma recomendação para gerar descrições de ferramentas otimizadas para seu agente. O serviço analisa os traços do agente para identificar a confusão na seleção de ferramentas e produz descrições nítidas 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á-los.

Exemplos de código

exemplo
AgentCore CLI
nota

Ao contrário das recomendações de prompt do sistema, que exigem exatamente uma-e/--evaluator, a descrição da ferramenta é -e/--evaluator totalmente omitida.

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 em linha 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 rastreamentos:

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--session-id, e agentcore run recommendation aceita mais duas fontes de rastreamento: --from-insights <id> (use uma execução de insights local como fonte de rastreamento; a CLI resolve o ARN de avaliação de lote) e --batch-evaluation-arn <arn> (use um ARN de avaliação de 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 em linha:

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 rastreamentos:

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 com 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ê tentar novamente 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 das ferramentas para otimizar. Forneça toolDescriptionText (lista em linha de pares de nome e descrição da ferramenta) ou configurationBundle (referência de pacote com caminhos JSON para cada descrição da ferramenta).

agentTraces

Union

Sim

Rastreie a fonte para análise. Consulte Trace sources para obter recomendações.
nota

As recomendações de descrição da ferramenta não exigem umevaluationConfig. Diferentemente das recomendações de aviso do sistema, que usam um avaliador como sinal de otimização, as recomendações de descrição de ferramentas analisam os padrões de seleção de ferramentas diretamente dos traços do agente para identificar ambigüidades entre as ferramentas e gerar descrições nítidas.

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 das ferramentas 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 (recuperada 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

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

errorMessage

String

Presente 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 .