View a markdown version of this page

Raccomandazioni - Fondamento Amazon AgentCore
Modalità di immissione della configurazioneFonti di tracciamento degli agenti

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Raccomandazioni

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

Nota

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

Amazon Bedrock AgentCore supporta due tipi di consigli:

  • Raccomandazione del prompt di 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 dello strumento: 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 immissione della configurazione

È possibile fornire la configurazione corrente in due modi:

  • Testo in linea: fornisci la configurazione direttamente come stringa nella richiesta API. Per ricevere consigli sui prompt di sistema, passate il testo della richiesta nel systemPrompt.text campo. Per consigli sulla descrizione degli strumenti, inserite il nome e la descrizione di ogni strumento nell'toolDescription.toolDescriptionText.toolselenco. Questa modalità è utile per una rapida sperimentazione, quando volete testare un prompt su cui state iterando attivamente o quando la configurazione non è memorizzata 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 degli 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 pacchetto utilizzando il percorso JSON specificato, genera la versione ottimizzata e riscrive il risultato in una nuova versione del pacchetto. Ciò mantiene la cronologia delle ottimizzazioni aggiornata insieme al pacchetto. Questa modalità è utile quando gestisci le configurazioni centralmente con i bundle di configurazione e desideri 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 utensile)

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

    Quando si utilizza un pacchetto di configurazione, il risultato del consiglio 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 quattro 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 fornire logGroupArnsserviceNames,startTime, eendTime. Un rule campo opzionale consente di filtrare le tracce (ad esempio, selezionando solo le sessioni in cui goal_success_rate è inferiore a una soglia).

    Nota

    L'API dei consigli utilizza gli ARN dei gruppi di log (logGroupArns), non i nomi dei gruppi di log. Ciò è diverso dalle valutazioni in batch, che utilizzano. logGroupNames

    Campo Tipo Campo obbligatorio Description

    cloudwatchLogs.logGroupArns

    Elenco di stringhe

    Sì

    CloudWatch Registra gli ARN del gruppo in cui è archiviata la telemetria dell'agente. arn:aws:logs:{region}:{account}:log-group:{log-group-name}Formato:.

    cloudwatchLogs.serviceNames

    Elenco di stringhe

    Sì

    Nomi di servizio 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 successive a 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, da una CI/CD pipeline o da una sessione specifica in base alla quale si desidera eseguire l'ottimizzazione). Fornisci gli intervalli direttamente nel corpo della richiesta API come elenco di oggetti span. OpenTelemetry-compatible

    Campo Tipo Campo obbligatorio Description

    sessionSpans

    Elenco di oggetti

    Sì

    La traccia dell'agente si estende nel formato. OpenTelemetry-compatible Ogni intervallo include l'ID di traccia, l'ID dell'intervallo, il nome, i timestamp e gli 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 sul 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

La valutazione in batch e le fonti di tracciamento della valutazione online sono disponibili solo per le raccomandazioni tempestive del sistema.

  • Valutazione in batch: da utilizzare quando è stato completato un processo di valutazione in batch di cui si desidera riutilizzare le sessioni per l'ottimizzazione. Invece di raccogliere nuovamente le tracce CloudWatch o fornire intervalli in linea, fate riferimento alla valutazione del batch direttamente tramite il relativo ARN. Questa fonte è disponibile solo per i consigli richiesti dal sistema.

    • Se i valutatori utilizzati nel processo di valutazione in batch corrispondono ai valutatori specificati nella richiesta di raccomandazione, il servizio riutilizza i punteggi esistenti.

    • Se i valutatori non corrispondono, il servizio esegue nuove valutazioni per i valutatori richiesti rispetto alle sessioni di valutazione in batch.

      Campo Tipo Campo obbligatorio Descrizione

      batchEvaluation.batchEvaluationArn

      Stringa

      Sì

      ARN di un processo di valutazione del batch completato. Il servizio riutilizza le sessioni di questo processo come input di traccia. Formato:arn:aws:bedrock-agentcore:{region}:{account}:batch-evaluation/{id}.
      Esempio
      AWS SDK (boto3)
      agent_traces = {
    "batchEvaluation": {
        "batchEvaluationArn": "<batch-evaluation-arn>"
    }
}

  • Valutazione online: da utilizzare quando si dispone di una configurazione di valutazione online che valuta continuamente le sessioni degli agenti in tempo reale. Poiché la valutazione online è un flusso continuo, è necessario specificare una finestra temporale (startTimeeendTime) per limitare le sessioni valutate da cui attinge la raccomandazione. Il servizio riutilizza i punteggi di valutazione delle sessioni di valutazione online all'interno della finestra specificata. Questa fonte è disponibile solo per i consigli relativi ai prompt del sistema.

    Campo Tipo Campo obbligatorio Descrizione

    onlineEvaluation.onlineEvaluationConfigArn

    Stringa

    Sì

    ARN di una configurazione di valutazione online. Il servizio utilizza le sessioni valutate di questa configurazione come input di traccia. Formato:arn:aws:bedrock-agentcore:{region}:{account}:online-evaluation-config/{id}.

    onlineEvaluation.startTime

    Data/ora ISO 8601

    Sì

    Inizio della finestra di valutazione. Sono incluse solo le sessioni valutate dopo questo periodo.

    onlineEvaluation.endTime

    Data/ora ISO 8601

    Sì

    Fine della finestra di valutazione. Sono incluse solo le sessioni valutate prima di questo orario.
    Esempio
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "onlineEvaluation": {
        "onlineEvaluationConfigArn": "<online-evaluation-config-arn>",
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}
Nota

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

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

Flag CLI Mappatura API Description

--lookback <days>

cloudwatchLogscon calcolato startTime e endTime

Raccoglie 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 sul 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 fonti. CloudWatch

--spans-file <path>

sessionSpans(in linea)

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

--wait

n/a (polling lato client)

Blocca finché la raccomandazione non raggiunge lo stato terminale.