Esempi di codice Parametri della richiesta Modalità di immissione della descrizione dello strumento Risposta Risultato della raccomandazione Errori

Avviare una raccomandazione sulla descrizione dell'utensile

Avvia 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 più nitide che riducono l'ambiguità quando l'agente sceglie tra gli strumenti.

Nota

I consigli vengono generati dai LLM. Esaminali e testali prima di applicarli.

Esempi di codice

Esempio

AgentCore CLI

Nota

A differenza dei suggerimenti dei prompt di sistema, che ne richiedono esattamente uno-e/--evaluator, la descrizione dello strumento viene eseguita interamente omit-e/--evaluator.

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 CloudWatch tracce:


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 --spans-file--session-id, and agentcore run recommendation accetta altre due fonti di traccia: --from-insights <id> (utilizza un'esecuzione locale di Insights come origine 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, consulta Trace sources per i consigli. Puoi anche --kms-key <arn> crittografare i risultati dei consigli con una chiave KMS gestita dal cliente.

Per bloccare fino a quando 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, conagentcore view recommendation:


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Descrizioni degli strumenti in linea con CloudWatch tracce:


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 la raccomandazione.
`description`	Stringa	No	Descrizione facoltativa. Massimo 4096 caratteri.
`clientToken`	Stringa	No	Token di idempotenza. Se riprovi 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 attuali descrizioni degli strumenti da ottimizzare. Fornisci `toolDescriptionText` (elenco in linea delle coppie di nomi e descrizioni dello strumento) o `configurationBundle` (riferimento in bundle con percorsi JSON per ogni descrizione dello strumento).
`agentTraces`	Union	Sì	Trace la fonte per l'analisi. Consulta Trace sources per consigli.

Nota

I consigli sulla descrizione degli strumenti non richiedono unevaluationConfig. A differenza delle raccomandazioni tempestive di sistema, che utilizzano un valutatore come segnale di ottimizzazione, le raccomandazioni 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 più nitide.

Modalità di immissione della descrizione dello strumento

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 ottimizzate degli strumenti 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 della raccomandazione.

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 `toolNamerecommendedToolDescription`, 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 consigli simultanei.
`ThrottlingException`	429	Frequenza di richiesta superata. Riprova con 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 rapida del sistema

Ottieni consigli