View a markdown version of this page

Avviare una raccomandazione rapida di sistema - Amazon Bedrock AgentCore

Avviare una raccomandazione rapida di 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 dello strumento di valutazione target.

Nota

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

Esempi di codice

Esempio
AgentCore CLI

La CLI accetta diverse sorgenti di traccia e tre modalità di input del prompt di sistema. Combinali secondo necessità:

  • Fonti di tracciamento: CloudWatch Logs (--lookback), inline spans (--spans-file), un'esecuzione di analisi locale (--from-insights <id>: utilizza un'esecuzione di analisi locale come origine di traccia; risolve l'ARN di valutazione del batch) o un ARN di valutazione in batch direttamente (--batch-evaluation-arn <arn>— utilizza un ARN di valutazione batch direttamente come origine di traccia)

  • Immissione del prompt di sistema: testo in linea (), file di richiesta () o pacchetto di configurazione (--inline) --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 delle raccomandazioni)

    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 lavoro asincrono e restituisce solo uno stato o uno recommendationId stato iniziale. PENDING IN_PROGRESS Aggiungi --wait al blocco finché la raccomandazione non raggiunge lo stato terminale. Per recuperare il risultato completo in un secondo momento, consulta Recuperare 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 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'agente runtime ARN. 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

    Recuperate il risultato:

    view recommendationUtilizzalo con l'ID del lavoro consigliato per recuperare il risultato completato. Aggiungi --json per 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

Un nome per la raccomandazione. Massimo 48 caratteri. Motivo:[a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

Stringa

Deve essere SYSTEM_PROMPT_RECOMMENDATION.

recommendationConfig

Oggetto

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

Campo Tipo Campo obbligatorio Description

systemPrompt

Union

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

agentTraces

Union

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

evaluationConfig

Oggetto

Configurazione di valutazione che specifica il valutatore di destinazione. 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 l'obiettivo in base al quale la raccomandazione deve essere ottimizzata; l'ottimizzatore indirizza il prompt verso il quale il valutatore ottiene un punteggio elevato.

È possibile utilizzare un valutatore integrato o fornire un ARN di valutazione personalizzato. Utilizza le seguenti linee guida per scegliere:

  • Se il tuo agente ha un compito chiaro da completare (prenotazione, recupero, 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 migliore.

  • Se la qualità che ti interessa è specifica del dominio o non viene rilevata da uno strumento di valutazione integrato, utilizza uno strumento di valutazione 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.

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 --evaluator flag:

--evaluator Builtin.GoalSuccessRate

Modalità di input del prompt di 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 della raccomandazione.

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 ottimizzato del prompt di sistema.

configurationBundle

Oggetto

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

explanation

Stringa

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

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 .