Codebeispiele Anforderungsparameter Einen Evaluator auswählen Eingabemodi der Systemaufforderung Antwort Ergebnis der Empfehlung Fehler

Starten Sie eine Systemaufforderungsempfehlung

Starten Sie eine Empfehlung, um eine optimierte Systemaufforderung für Ihren Agenten zu generieren. Der Service analysiert die Agentenverfolgung, identifiziert Fehlermuster und erstellt eine überarbeitete Systemaufforderung, die die Leistung des Ziel-Evaluators verbessert.

Anmerkung

Empfehlungen werden von LLMs generiert. Überprüfen und testen Sie sie, bevor Sie sie anwenden.

Codebeispiele

Beispiel

AgentCore CLI

Die CLI akzeptiert mehrere Trace-Quellen und drei Eingabemodi für Systemeingabeaufforderungen. Kombinieren Sie sie nach Bedarf:

Trace-Quellen: CloudWatch Logs (--lookback), Inline-Spans (--spans-file), ein lokaler Insights-Lauf (--from-insights <id>— verwendet einen lokalen Insights-Lauf als Trace-Quelle; löst den Batch-Eval-ARN auf) oder einen Batch-Evaluierungs-ARN direkt (--batch-evaluation-arn <arn>— verwendet einen Batch-Evaluierungs-ARN direkt als Trace-Quelle)
Eingabe der Systemaufforderung: Inline-Text (--inline), Eingabeaufforderungsdatei (--prompt-file) oder Konfigurationspaket () --bundle-name
Optionaler Filter: spezifische Sitzungs-IDs (--session-id), um einzugrenzen, welche Traces analysiert werden

Optionale Verschlüsselung: ein KMS-Schlüssel (--kms-key <arn>— KMS-Schlüssel-ARN zur Verschlüsselung von Empfehlungsergebnissen)

Inline-Systemaufforderung mit CloudWatch Traces:


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 recommendationstartet einen asynchronen Job und gibt nur den Anfangswert A recommendationId und den IN_PROGRESS Anfangsstatus PENDING oder zurück. Zum --wait Blockieren hinzufügen, bis die Empfehlung einen Terminalstatus erreicht. Informationen zum späteren Abrufen des fertigen Ergebnisses finden Sie unter Ergebnis abrufen.

Inline-Systemaufforderung aus einer Datei mit CloudWatch Traces:


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

Inline-Systemaufforderung mit einer Spans-Datei:


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

Inline-Systemaufforderung mit bestimmten Sitzungs-IDs:

Die CLI sammelt Spans für die angegebene Sitzung clientseitig und übergibt sie als Inline-Spans.


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>

Konfigurationspaket mit Traces: CloudWatch

Die CLI löst automatisch den vollständigen JSON-Pfad aus dem configuration übergeordneten Objekt des Agenten-Runtime-ARN auf. Sie müssen nur den Schlüsselnamen angeben, der die Systemaufforderung enthält.


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

Rufen Sie das Ergebnis ab:

Verwenden Sie es view recommendation zusammen mit der Empfehlungs-Job-ID, um das fertige Ergebnis abzurufen. Fügt --json eine maschinenlesbare Ausgabe hinzu, die und enthält. recommendedSystemPrompt explanation


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

Inline-Text mit Spuren 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']}")

Inline-Text mit Inline-Bereichen:


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()),
)

Konfigurationspaket mit CloudWatch Traces:


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()),
)

Konfigurationspaket mit Inline-Spans:


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()),
)

Anforderungsparameter

Parameter	Typ	Erforderlich	Beschreibung
`name`	Zeichenfolge	Ja	Ein Name für die Empfehlung. Maximal 48 Zeichen. Muster:`[a-zA-Z][a-zA-Z0-9_-]{0,47}`.
`type`	Zeichenfolge	Ja	Der Wert muss `SYSTEM_PROMPT_RECOMMENDATION` sein.
`recommendationConfig`	Objekt	Ja	Enthält `systemPromptRecommendationConfig` die Konfiguration für die Empfehlung.
`description`	Zeichenfolge	Nein	Optionale Beschreibung. Maximal 4096 Zeichen.
`clientToken`	Zeichenfolge	Nein	Idempotenz-Token. Wenn Sie eine Anfrage mit demselben Client-Token erneut versuchen, gibt der Dienst die bestehende Empfehlung zurück, anstatt eine neue zu erstellen.

Systemfelder PromptRecommendationConfig

Feld	Typ	Erforderlich	Description
`systemPrompt`	Union	Ja	Das aktuelle System fordert zur Optimierung auf. Geben Sie entweder `text` (Inline-Zeichenfolge, maximal 20.000 Zeichen) oder `configurationBundle` (Paketreferenz) an.
`agentTraces`	Union	Ja	Verfolgen Sie die Quelle für die Analyse. Empfehlungen finden Sie unter Trace-Quellen.
`evaluationConfig`	Objekt	Ja	Evaluierungskonfiguration unter Angabe des Ziel-Evaluators. Enthält eine `evaluators` Liste mit genau einer Evaluator-Referenz.

Einen Evaluator auswählen

Wählen Sie einen Gutachter aus, der auf die Richtung ausgerichtet ist, in der Sie sich verbessern möchten. Der Evaluator, den Sie auswählen, bestimmt, in welche Richtung die Empfehlung optimiert wird. Was auch immer der Evaluator gut abschneidet, ist das Ziel, in das der Optimierer die Aufforderung weiterleitet.

Sie können einen integrierten Evaluator verwenden oder einen benutzerdefinierten Evaluator-ARN bereitstellen. Verwenden Sie bei der Auswahl die folgenden Richtlinien:

Wenn Ihr Agent eine klare Aufgabe zu erledigen hat (Buchung, Abruf, mehrstufiger Workflow), Builtin.GoalSuccessRate ist das das richtige Signal.
Wenn Ihr Agent offener ist und Ihnen die Qualität der Interaktion selbst am Herzen Builtin.Helpfulness liegt, ist das eine bessere Lösung.
Wenn die Qualität, die Ihnen wichtig ist, domänenspezifisch ist oder nicht von einem integrierten Evaluator erfasst wird, verwenden Sie einen benutzerdefinierten Evaluator, um die Messung am besten darzustellen.

Anmerkung

Empfehlungen unterstützen integrierte, benutzerdefinierte und codebasierte Evaluatoren LLM-as-judge, erfordern jedoch, dass der Evaluator einen numerischen Wert als Optimierungssignal zurückgibt. Für benutzerdefinierte LLM-as-judge Evaluatoren konfigurieren Sie das ratingScale mit einer numerical Skala (nicht). categorical Nehmen Sie bei codebasierten Evaluatoren das value Feld in das Antwortschema auf.

Geben Sie in der API den Evaluator in der evaluationConfig.evaluators Liste mit genau einer Evaluator-Referenz an:


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

Verwenden Sie in der CLI das --evaluator Flag:


--evaluator Builtin.GoalSuccessRate

Eingabemodi der Systemaufforderung

Mode	CLI-Flaggen	API-Feld
Inline-Text	`--inline "prompt text"` oder `--prompt-file ./path.txt`	`systemPrompt.text`
Konfigurationspaket	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` + `--system-prompt-json-path <path>`	`systemPrompt.configurationBundle`mit `bundleArnversionId`, `systemPromptJsonPath`

Wenn Sie ein Konfigurationspaket verwenden, enthält das Ergebnis eine neue Bundle-Version mit angewendeter optimierter Systemaufforderung.

Antwort

Feld	Typ	Description
`recommendationId`	Zeichenfolge	Eindeutige ID für die Empfehlung.
`recommendationArn`	Zeichenfolge	ARN der Empfehlung.
`name`	Zeichenfolge	Der Name, den Sie angegeben haben.
`type`	Zeichenfolge	`SYSTEM_PROMPT_RECOMMENDATION`.
`status`	Zeichenfolge	Ursprünglicher Status: `PENDING` oder`IN_PROGRESS`.
`createdAt`	Zeitstempel	Wann die Empfehlung erstellt wurde.
`updatedAt`	Zeitstempel	Wann die Empfehlung zuletzt aktualisiert wurde.

Ergebnis der Empfehlung

Wenn die Empfehlung den COMPLETED Status erreicht (abgerufen über Empfehlung abrufen), enthält das Ergebnis:

Feld	Typ	Description
`recommendedSystemPrompt`	Zeichenfolge	Der optimierte Text der Systemaufforderung.
`configurationBundle`	Objekt	Vorhanden, wenn es sich bei der Eingabe um ein Konfigurationspaket handelte. Enthält `bundleArn` und `versionId` zeigt auf eine neue Bundle-Version mit angewendeter optimierter Eingabeaufforderung.
`explanation`	Zeichenfolge	Eine Erklärung, warum die Empfehlung generiert wurde, und die Gründe für die vorgeschlagenen Änderungen.
`errorCode`	Zeichenfolge	Vorhanden, wenn die Empfehlung fehlgeschlagen ist. Fehlercode, der den Fehler beschreibt.
`errorMessage`	Zeichenfolge	Vorhanden, wenn die Empfehlung fehlgeschlagen ist. Human-readable Beschreibung des Fehlers.

Fehler

Fehler	HTTP-Status	Description
`ValidationException`	400	Ungültige Anforderungsparameter. Überprüfen Sie die Feldbeschränkungen und die erforderlichen Felder.
`AccessDeniedException`	403	Unzureichende Berechtigungen. Überprüfen Sie die IAM-Richtlinien.
`ConflictException`	409	Eine Empfehlung mit demselben Client-Token mit unterschiedlichen Parametern ist bereits vorhanden.
`ServiceQuotaExceededException`	402	Sie haben die maximale Anzahl gleichzeitiger Empfehlungen überschritten.
`ThrottlingException`	429	Die Anforderungsrate wurde überschritten. Versuchen Sie es erneut mit exponentiellem Backoff.
`InternalServerException`	500	Service-side Fehler. Wiederholen Sie die Anforderung.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Empfehlungen

Empfehlung zur Beschreibung des Tools