View a markdown version of this page

Avvia una raccomandazione tempestiva del sistema - Fondamento Amazon AgentCore

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

Avvia una raccomandazione tempestiva del sistema

Avvia una raccomandazione per generare un prompt di sistema ottimizzato per il tuo agente. Il servizio analizza le tracce degli agenti, identifica i modelli di errore e produce un prompt di sistema rivisto che migliora le prestazioni del valutatore target.

Nota

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

Esempi di codice

Esempio
AgentCore CLI

La CLI accetta diverse fonti di tracciamento e tre modalità di immissione del prompt del sistema. Combinali secondo necessità:

  • Traccia le fonti: CloudWatch Logs (--lookback), inline spans (--spans-file), un'esecuzione locale di approfondimenti (--from-insights <id>— utilizza un'analisi locale eseguita come fonte di traccia; risolve l'ARN di valutazione batch) o direttamente un ARN di valutazione batch (--batch-evaluation-arn <arn>— utilizza un ARN di valutazione batch direttamente come fonte di traccia)

  • Inserimento del prompt di sistema: testo in linea (), file di prompt (--inline) o pacchetto di configurazione () --prompt-file --bundle-name

  • Filtro opzionale: ID di sessione specifici (--session-id) per restringere le tracce da analizzare

  • Crittografia opzionale: una chiave KMS (--kms-key <arn>— chiave KMS ARN per crittografare i risultati dei consigli)

    Prompt di sistema in linea con tracce: CloudWatch

    agentcore run recommendation \ --type system-prompt \ --run my-prompt-rec \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --inline "You are a helpful customer support assistant. Help users with their orders and returns." \ --lookback 7 \ --wait

    run recommendationavvia un processo asincrono e restituisce solo un valore iniziale o uno recommendationId stato. PENDING IN_PROGRESS Aggiungi --wait al blocco finché la raccomandazione non raggiunge lo stato terminale. Per recuperare il risultato completato in un secondo momento, consulta Recupera il risultato.

    Richiesta di sistema in linea da un file con tracce: CloudWatch

    agentcore run recommendation \ --type system-prompt \ --run my-prompt-rec \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --prompt-file ./system-prompt.txt \ --lookback 7

    Prompt di sistema in linea con un file spans:

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

    Prompt di sistema in linea con ID di sessione specifici:

    La CLI raccoglie gli intervalli per la sessione specificata 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 customer support assistant." \ --session-id <session-id-1> <session-id-2>

    CloudWatch Pacchetto di configurazione con tracce:

    La CLI risolve automaticamente il percorso JSON completo dall'oggetto principale dell'ARN del runtime dell'agente. configuration È sufficiente fornire il nome della chiave che contiene il prompt di sistema.

    agentcore run recommendation \ --type system-prompt \ --run my-prompt-rec \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --bundle-name <bundle-name> \ --bundle-version <bundle-version> \ --system-prompt-json-path "system_prompt" \ --lookback 7

    Recupera il risultato:

    Usalo view recommendation con l'ID del lavoro consigliato per recuperare il risultato completato. Aggiungi --json per ottenere un output leggibile dalla macchina contenente e. recommendedSystemPrompt explanation

    agentcore view recommendation <recommendation-id> --json
AWS SDK (boto3)

Testo 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-prompt-rec", type="SYSTEM_PROMPT_RECOMMENDATION", recommendationConfig={ "systemPromptRecommendationConfig": { "systemPrompt": { "text": "You are a helpful customer support assistant. Help users with their orders and returns." }, "agentTraces": { "cloudwatchLogs": { "logGroupArns": [ "<log-group-arn>" ], "serviceNames": ["<service-name>"], "startTime": now - timedelta(days=7), "endTime": now, } }, "evaluationConfig": { "evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"} ] }, } }, clientToken=str(uuid.uuid4()), ) recommendation_id = response["recommendationId"] print(f"Started recommendation: {recommendation_id}") print(f"Status: {response['status']}")

Testo in linea con intervalli in linea:

with open("agent-traces.json") as f: spans = json.load(f) response = client.start_recommendation( name="my-prompt-rec-spans", type="SYSTEM_PROMPT_RECOMMENDATION", recommendationConfig={ "systemPromptRecommendationConfig": { "systemPrompt": { "text": "You are a helpful customer support assistant." }, "agentTraces": { "sessionSpans": spans }, "evaluationConfig": { "evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"} ] }, } }, clientToken=str(uuid.uuid4()), )

Pacchetto di configurazione con tracce: CloudWatch

response = client.start_recommendation( name="my-bundle-prompt-rec", type="SYSTEM_PROMPT_RECOMMENDATION", recommendationConfig={ "systemPromptRecommendationConfig": { "systemPrompt": { "configurationBundle": { "bundleArn": "<bundle-arn>", "versionId": "<bundle-version>", "systemPromptJsonPath": "$.configuration.system_prompt", } }, "agentTraces": { "cloudwatchLogs": { "logGroupArns": [ "<log-group-arn>" ], "serviceNames": ["<service-name>"], "startTime": now - timedelta(days=7), "endTime": now, } }, "evaluationConfig": { "evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"} ] }, } }, clientToken=str(uuid.uuid4()), )

Pacchetto di configurazione con intervalli in linea:

response = client.start_recommendation( name="my-bundle-prompt-rec-spans", type="SYSTEM_PROMPT_RECOMMENDATION", recommendationConfig={ "systemPromptRecommendationConfig": { "systemPrompt": { "configurationBundle": { "bundleArn": "<bundle-arn>", "versionId": "<bundle-version>", "systemPromptJsonPath": "$.configuration.system_prompt", } }, "agentTraces": { "sessionSpans": spans }, "evaluationConfig": { "evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"} ] }, } }, 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 SYSTEM_PROMPT_RECOMMENDATION.

recommendationConfig

Oggetto

Sì

Contiene systemPromptRecommendationConfig 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 di sistema PromptRecommendationConfig

Campo Tipo Campo obbligatorio Description

systemPrompt

Union

Sì

L'attuale richiesta di ottimizzazione del sistema. Fornisci text (stringa in linea, massimo 20.000 caratteri) o configurationBundle (riferimento al pacchetto).

agentTraces

Union

Sì

Traccia la fonte per l'analisi. Vedi Trace sources per consigli.

evaluationConfig

Oggetto

Sì

Configurazione di valutazione che specifica il valutatore target. Contiene un evaluators elenco con esattamente un riferimento al valutatore.

Scelta di un valutatore

Seleziona un valutatore in linea con la direzione che desideri migliorare. Il valutatore selezionato determina in che direzione viene ottimizzata la raccomandazione; qualunque sia il punteggio più alto ottenuto dal valutatore, è ciò verso cui l'ottimizzatore spinge il prompt.

Puoi utilizzare un valutatore integrato o fornire un ARN di valutazione personalizzato. Usa le seguenti linee guida per scegliere:

  • Se il tuo agente ha un compito chiaro da completare (prenotazione, recupero, un flusso di lavoro in più fasi), Builtin.GoalSuccessRate è il segnale giusto.

  • Se il tuo agente è più aperto e ti interessa la qualità dell'interazione stessa, Builtin.Helpfulness è la soluzione più adatta.

  • Se la qualità che ti interessa è specifica del dominio o non viene acquisita da un valutatore integrato, utilizza un valutatore personalizzato per rappresentare al meglio la misurazione.

Nota

I consigli supportano valutatori integrati LLM-as-judge, personalizzati e basati su codice, ma richiedono che il valutatore restituisca un valore numerico come segnale di ottimizzazione. Per i LLM-as-judge valutatori personalizzati, configurali ratingScale con una scala (non). numerical categorical Per i valutatori basati su codice, includi il value campo nello schema di risposta. Schema di risposta

Nell'API, specifica il valutatore nell'evaluationConfig.evaluatorselenco con esattamente un riferimento al valutatore:

"evaluationConfig": { "evaluators": [ {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"} ] }

Nella CLI, usa il flag: --evaluator

--evaluator Builtin.GoalSuccessRate

Modalità di immissione del prompt del sistema

Modalità Bandiere CLI Campo API

Testo in linea

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

systemPrompt.text

Pacchetto di configurazione

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

systemPrompt.configurationBundleconbundleArn, versionId systemPromptJsonPath

Quando si utilizza un pacchetto di configurazione, il risultato include una nuova versione del pacchetto con il prompt di sistema ottimizzato applicato.

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

SYSTEM_PROMPT_RECOMMENDATION.

status

Stringa

Stato iniziale: PENDING oIN_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

recommendedSystemPrompt

Stringa

Il testo del prompt di sistema ottimizzato.

configurationBundle

Oggetto

Presente quando l'input era un pacchetto di configurazione. Contiene bundleArn e versionId punta a una nuova versione del pacchetto con il prompt ottimizzato applicato.

explanation

Stringa

Una spiegazione del motivo per cui è stata generata la raccomandazione e il ragionamento alla base delle modifiche suggerite.

errorCode

Stringa

Presente se la raccomandazione ha avuto esito negativo. 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 .