Esempi di codice Parametri della richiesta Modalità di immissione della descrizione dell'utensile Risposta Risultato della raccomandazione Errori

Avvia una raccomandazione sulla descrizione dello strumento

Crea una raccomandazione per generare descrizioni ottimizzate degli strumenti per il tuo agente. Il servizio analizza le tracce degli agenti per identificare la confusione nella selezione degli strumenti e produce descrizioni nitide che riducono l'ambiguità quando l'agente sceglie tra gli strumenti.

Nota

I consigli vengono generati dagli LLM. Rivedi e prova prima di applicarli.

Esempi di codice

Esempio

AgentCore CLI

Nota

A differenza dei suggerimenti di sistema, che ne richiedono esattamente uno-e/--evaluator, la descrizione dello strumento viene -e/--evaluator completamente omessa.

Descrizioni degli strumenti in linea con tracce: CloudWatch


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

Descrizioni degli strumenti in linea con un file 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

Descrizioni degli strumenti in linea con ID di sessione specifici:


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

Pacchetto di configurazione con tracce: CloudWatch


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

Pacchetto di configurazione con un file 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

Inoltre--lookback, e --spans-file--session-id, agentcore run recommendation accetta altre due fonti di traccia: --from-insights <id> (usa un codice di analisi locale eseguito come fonte di traccia; la CLI risolve l'ARN di valutazione batch) e --batch-evaluation-arn <arn> (usa direttamente un ARN di valutazione batch). Per una panoramica di tutte le fonti di traccia, vedi Trace sources per consigli. Puoi anche aggiungere o --kms-key <arn> crittografare i risultati dei consigli con una chiave KMS gestita dal cliente.

Per bloccarla finché la raccomandazione non raggiunge lo stato terminale, aggiungi: --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

Recupera il risultato completo, incluse le descrizioni ottimizzate degli strumenti, con: agentcore view recommendation


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Descrizioni degli utensili in linea con tracce: CloudWatch


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

Descrizioni degli strumenti in linea con intervalli in linea:


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

Pacchetto di configurazione con tracce: CloudWatch


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

Pacchetto di configurazione con intervalli in linea:


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

Parametri della richiesta

Parametro	Tipo	Campo obbligatorio	Descrizione
`name`	Stringa	Sì	Un nome per la raccomandazione. Massimo 48 caratteri. Motivo:`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	Stringa	Sì	Deve essere `TOOL_DESCRIPTION_RECOMMENDATION`.
`recommendationConfig`	Oggetto	Sì	Contiene `toolDescriptionRecommendationConfig` la configurazione per il consiglio.
`description`	Stringa	No	Descrizione facoltativa. Massimo 4096 caratteri.
`clientToken`	Stringa	No	Token di idempotenza. Se ritenti una richiesta con lo stesso token client, il servizio restituisce il consiglio esistente invece di crearne uno nuovo.

campi degli strumenti DescriptionRecommendationConfig

Campo	Tipo	Campo obbligatorio	Description
`toolDescription`	Union	Sì	Le descrizioni degli strumenti correnti da ottimizzare. Fornisci `toolDescriptionText` (elenco in linea delle coppie di nome e descrizione dello strumento) o `configurationBundle` (riferimento raggruppato con percorsi JSON a ciascuna descrizione dello strumento).
`agentTraces`	Union	Sì	Traccia la fonte per l'analisi. Vedi Trace sources per consigli.

Nota

I consigli sulla descrizione degli strumenti non richiedono unevaluationConfig. A differenza dei suggerimenti di sistema, che utilizzano un valutatore come segnale di ottimizzazione, i consigli sulla descrizione degli strumenti analizzano i modelli di selezione degli strumenti direttamente dalle tracce degli agenti per identificare le ambiguità tra gli strumenti e generare descrizioni nitide.

Modalità di immissione della descrizione dell'utensile

Modalità	Bandiere CLI	Campo API
Testo in linea	`--tools "name:description"`(ripetere per ogni strumento)	`toolDescription.toolDescriptionText.tools`. Elenco di oggetti con `toolName` e `toolDescription`
Pacchetto di configurazione	`--bundle-name <bundle-name>`+ `--bundle-version <bundle-version>` + `--tool-desc-json-path "name:field"` (ripetere per ogni strumento)	`toolDescription.configurationBundle`con `bundleArnversionId`, e un `tools` elenco contenente `toolName` e `toolDescriptionJsonPath`

Quando si utilizza un pacchetto di configurazione, il risultato include una nuova versione del pacchetto con le descrizioni degli strumenti ottimizzate applicate.

Risposta

Campo	Tipo	Description
`recommendationId`	Stringa	Identificatore univoco per la raccomandazione.
`recommendationArn`	Stringa	ARN della raccomandazione.
`name`	Stringa	Il nome che hai specificato.
`type`	Stringa	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	Stringa	Stato iniziale: `PENDING` o`IN_PROGRESS`.
`createdAt`	Time stamp	Quando è stata creata la raccomandazione.
`updatedAt`	Time stamp	Data dell'ultimo aggiornamento del consiglio.

Risultato della raccomandazione

Quando la raccomandazione raggiunge COMPLETED lo stato (recuperato tramite Ottieni una raccomandazione), il risultato contiene:

Campo	Tipo	Description
`tools`	List	Per-tool risultati. Ogni voce contiene`toolName`,`recommendedToolDescription`, e`explanation`.
`configurationBundle`	Oggetto	Presente quando l'input era un pacchetto di configurazione. Contiene `bundleArn` e `versionId` rimanda a una nuova versione del pacchetto con le descrizioni ottimizzate applicate.
`errorCode`	Stringa	Presente se la raccomandazione non è riuscita. Codice di errore che descrive l'errore.
`errorMessage`	Stringa	Presente se la raccomandazione non è riuscita. Human-readable descrizione dell'errore.

Errori

Errore	Stato HTTP	Description
`ValidationException`	400	Parametri di richiesta non validi. Controlla i vincoli dei campi e i campi obbligatori.
`AccessDeniedException`	403	Autorizzazioni insufficienti. Verifica le politiche IAM.
`ConflictException`	409	Esiste già una raccomandazione con lo stesso token client con parametri diversi.
`ServiceQuotaExceededException`	402	Hai superato il numero massimo di raccomandazioni simultanee.
`ThrottlingException`	429	Percentuale di richieste superata. Riprova con un backoff esponenziale.
`InternalServerException`	500	Service-side errore. Riprova la richiesta .

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Raccomandazione immediata del sistema

Ottieni consigli