View a markdown version of this page

Raccomandazioni - Amazon Bedrock AgentCore
Modalità di input di configurazioneFonti di tracciamento degli agenti

Raccomandazioni

I consigli utilizzano l'intelligenza artificiale per generare configurazioni di agenti ottimizzate a partire da tracce di sessioni reali. Invece di riscrivere manualmente le istruzioni o le descrizioni degli strumenti, indirizzate il servizio alle tracce dell'agente, specificate un valutatore target come segnale di ricompensa e ricevete una configurazione ottimizzata.

Nota

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

Amazon Bedrock AgentCore supporta due tipi di raccomandazioni:

  • Raccomandazione rapida del sistema: analizza le tracce degli agenti e genera un prompt di sistema ottimizzato che migliora le prestazioni del valutatore target. Il servizio identifica i modelli di errore e aggiunge istruzioni comportamentali specifiche.

  • Raccomandazione sulla descrizione dell'utensile: analizza le tracce degli agenti e genera descrizioni degli utensili più nitide che riducono la confusione nella selezione degli utensili. Ciò è utile quando gli agenti selezionano lo strumento sbagliato per richieste ambigue.

Ogni raccomandazione richiede due input: la configurazione corrente dell'agente da ottimizzare e le tracce degli agenti da analizzare.

Argomenti

Modalità di input di configurazione

È possibile fornire la configurazione corrente in due modi:

  • Testo in linea: fornisci la configurazione direttamente come stringa nella richiesta API. Per consigli sui prompt di sistema, inserite il testo del prompt nel campo. systemPrompt.text Per consigli sulla descrizione dello strumento, inserite il nome e la descrizione di ogni strumento nell'toolDescription.toolDescriptionText.toolselenco. Questa modalità è utile per una rapida sperimentazione, quando desideri testare un prompt su cui stai iterando attivamente o quando la configurazione non è archiviata in un pacchetto.

    Tipo di raccomandazione bandiere CLI Campo API

    Prompt di sistema

    --inline "prompt text" o --prompt-file ./path.txt

    systemPrompt.text

    Descrizione dello strumento

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: elenco di oggetti con toolName e toolDescription

  • Pacchetto di configurazione: fa riferimento a una versione del pacchetto di configurazione esistente. Il servizio legge la configurazione corrente dal bundle utilizzando il percorso JSON specificato, genera la versione ottimizzata e riscrive il risultato in una nuova versione del pacchetto. In questo modo la cronologia di ottimizzazione viene mantenuta aggiornata insieme al pacchetto. Questa modalità è utile quando si gestiscono le configurazioni centralmente con i pacchetti di configurazione e si desidera che l'output ottimizzato venga riscritto automaticamente nel pacchetto.

    Tipo di raccomandazione bandiere CLI Campo API

    Prompt di sistema

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundlecon bundleArnversionId, systemPromptJsonPath

    Descrizione dell'utensile

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (ripetere per ogni strumento)

    toolDescription.configurationBundlecon bundleArnversionId, e un tools elenco contenente toolName e toolDescriptionJsonPath

    Quando si utilizza un pacchetto di configurazione, il risultato della raccomandazione include un configurationBundle campo con bundleArn e un nuovo che versionId rimanda alla versione del pacchetto che contiene la configurazione ottimizzata.

Fonti di tracciamento degli agenti

Il agentTraces parametro accetta una delle due fonti:

  • CloudWatch Registri: da utilizzare quando il runtime dell'agente scrive dati di telemetria su. CloudWatch Il servizio legge le tracce direttamente dai gruppi di log specificati entro un intervallo di tempo richiesto. È necessario fornirelogGroupArns, serviceNamesstartTime, eendTime. Un rule campo opzionale consente di filtrare le tracce (ad esempio, selezionando solo le goal_success_rate sessioni al di sotto di una soglia).

    Nota

    L'API delle raccomandazioni utilizza ARNs (logGroupArns) dei gruppi di log, non i nomi dei gruppi di log. Ciò differisce dalle valutazioni in batch, che utilizzano. logGroupNames

    Campo Tipo Campo obbligatorio Description

    cloudwatchLogs.logGroupArns

    Elenco di stringhe

    Sì

    CloudWatch Registra gli ARN dei gruppi di log in cui è archiviata la telemetria degli agenti. Formato:. arn:aws:logs:{region}:{account}:log-group:{log-group-name}

    cloudwatchLogs.serviceNames

    Elenco di stringhe

    Sì

    Nomi di servizi che identificano le tracce del tuo agente in CloudWatch. Convenzione:{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    Data/ora ISO 8601

    Sì

    Inizio della finestra di raccolta delle tracce. Sono incluse solo le tracce trascorse dopo questo periodo.

    cloudwatchLogs.endTime

    Data/ora ISO 8601

    Sì

    Fine della finestra di raccolta delle tracce. Sono incluse solo le tracce precedenti a questo orario.

    cloudwatchLogs.rule

    Oggetto

    No

    Regola di filtro opzionale per restringere la selezione delle tracce. Contiene un filters elenco in cui ogni filtro specifica unkey, operator (ad esempioLESS_THAN) e value (come{"doubleValue": 0.5}).
    Esempio
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    Con un filtro di regole opzionale per selezionare solo le sessioni a basso rendimento:

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • Intervalli di sessione in linea: da utilizzare quando sono disponibili tracce localmente (ad esempio, da un'esecuzione di test locale, una CI/CD pipeline o una sessione specifica in base alla quale si desidera eseguire l'ottimizzazione). Fornisci gli span direttamente nel corpo della richiesta API come elenco di oggetti span. OpenTelemetry-compatible

    Campo Tipo Campo obbligatorio Description

    sessionSpans

    Elenco di oggetti

    Sì

    L'agente trace si estende nel formato. OpenTelemetry-compatible Ogni intervallo include trace ID, span ID, nome, timestamp e attributi.
    Esempio
    AgentCore CLI

    Estende il file (legge gli intervalli da un file JSON locale e li passa come intervalli in linea):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --spans-file agent-traces.json

    ID di sessione specifici (la CLI raccoglie gli intervalli lato client e li passa come intervalli in linea):

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

with open("agent-traces.json") as f:
    spans = json.load(f)

agent_traces = {
    "sessionSpans": spans
}
Nota

agentcore run recommendationè asincrono. Senza--wait, il comando invia il processo di raccomandazione e lo restituisce immediatamente; il processo viene avviato in uno stato non terminale (ad esempio PENDING orIN_PROGRESS) e il risultato viene recuperato in un secondo momento. Passa --wait al blocco finché la raccomandazione non raggiunge lo stato terminale. Per verificare o recuperare il risultato di un lavoro inviato, eseguiagentcore view recommendation <id>, where id è l'ID del lavoro consigliato.

La AgentCore CLI fornisce flag di convenienza che si associano ai tipi di sorgenti di traccia dell'API sottostanti:

Bandiera CLI Mappatura API Description

--lookback <days>

cloudwatchLogscon computerizzato startTime e endTime

Raccoglie le tracce degli ultimi N giorni tramite CloudWatch Logs. La CLI risolve gli ARN dei gruppi di log e i nomi dei servizi dalla configurazione di runtime.

--session-id <id>

sessionSpans(in linea)

Raccoglie gli intervalli per la sessione specificata lato client e li passa come intervalli di sessioni in linea. La stessa API di raccomandazione non supporta il filtraggio degli ID di sessione sulle sorgenti. CloudWatch

--spans-file <path>

sessionSpans(in linea)

Legge gli intervalli da un file JSON locale e li passa come intervalli di sessione in linea.

--wait

n/a (sondaggi lato client)

Blocca finché la raccomandazione non raggiunge lo stato terminale.