View a markdown version of this page

Empfehlungen - Amazon Grundgestein AgentCore
Eingabemodi für die KonfigurationAgent-Trace-Quellen

Empfehlungen

Empfehlungen verwenden KI, um optimierte Agentenkonfigurationen aus echten Sitzungsablaufverfolgungen zu generieren. Anstatt Eingabeaufforderungen oder Toolbeschreibungen manuell neu zu schreiben, verweisen Sie den Service auf die Traces Ihres Agenten, geben einen Ziel-Evaluator als Belohnungssignal an und erhalten eine optimierte Konfiguration.

Anmerkung

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

Amazon Bedrock AgentCore unterstützt zwei Empfehlungstypen:

  • Empfehlung zur Systemaufforderung: Analysiert die Agentenverfolgung und generiert eine optimierte Systemaufforderung, die die Leistung des Ziel-Evaluators verbessert. Der Service identifiziert Fehlermuster und fügt spezifische Verhaltensanweisungen hinzu.

  • Empfehlung zur Beschreibung des Tools: Analysiert die Ablaufverfolgung der Agenten und generiert genauere Werkzeugbeschreibungen, um Unklarheiten bei der Auswahl der Tools zu vermeiden. Dies ist nützlich, wenn Agenten bei mehrdeutigen Anfragen das falsche Tool auswählen.

Für jede Empfehlung sind zwei Eingaben erforderlich: die aktuelle Agentenkonfiguration zur Optimierung und die zu analysierenden Agenten-Traces.

Themen

Eingabemodi für die Konfiguration

Sie geben die aktuelle Konfiguration auf eine von zwei Arten an:

  • Inline-Text: Geben Sie die Konfiguration direkt als Zeichenfolge in der API-Anfrage an. Für Empfehlungen zur Systemaufforderung geben Sie den Eingabeaufforderungstext in das systemPrompt.text Feld ein. Für Empfehlungen zur Werkzeugbeschreibung geben Sie den Namen und die Beschreibung der einzelnen Tools in der toolDescription.toolDescriptionText.tools Liste an. Dieser Modus ist nützlich für schnelles Experimentieren, wenn Sie eine Aufforderung testen möchten, an der Sie gerade iterieren, oder wenn Ihre Konfiguration nicht in einem Paket gespeichert ist.

    Art der Empfehlung CLI-Flaggen API-Feld

    System-Prompt

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

    systemPrompt.text

    Beschreibung des Tools

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

    toolDescription.toolDescriptionText.tools: Liste der Objekte mit toolName und toolDescription

  • Konfigurationspaket: Verweisen Sie auf eine vorhandene Version des Konfigurationspakets. Der Dienst liest die aktuelle Konfiguration mithilfe des von Ihnen angegebenen JSON-Pfads aus dem Bundle, generiert die optimierte Version und schreibt das Ergebnis in eine neue Bundle-Version zurück. Dadurch wird Ihr Optimierungsverlauf zusammen mit Ihrem Bundle versioniert. Dieser Modus ist nützlich, wenn Sie Konfigurationen zentral mit Konfigurationspaketen verwalten und möchten, dass die optimierte Ausgabe automatisch in das Bundle zurückgeschrieben wird.

    Art der Empfehlung CLI-Flaggen API-Feld

    System-Prompt

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

    systemPrompt.configurationBundlemit bundleArnversionId, systemPromptJsonPath

    Beschreibung des Tools

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (für jedes Werkzeug wiederholen)

    toolDescription.configurationBundlemit bundleArnversionId, und einer tools Liste, die toolName und enthält toolDescriptionJsonPath

    Wenn Sie ein Konfigurationspaket verwenden, enthält das Empfehlungsergebnis ein configurationBundle Feld mit dem bundleArn und ein neues Feld, das auf die Bundle-Version versionId verweist, die die optimierte Konfiguration enthält.

Agent-Trace-Quellen

Der agentTraces Parameter akzeptiert eine von zwei Quellen:

  • CloudWatch Protokolle: Wird verwendet, wenn Ihre Agenten-Runtime Telemetrie in CloudWatch schreibt. Der Dienst liest innerhalb eines erforderlichen Zeitraums Traces direkt aus den angegebenen Protokollgruppen. Sie müssenlogGroupArns, serviceNamesstartTime, und angebenendTime. Ein optionales rule Feld ermöglicht es Ihnen, Traces zu filtern (indem Sie beispielsweise nur Sitzungen auswählen, deren goal_success_rate Wert unter einem Schwellenwert liegt).

    Anmerkung

    Die Empfehlungs-API verwendet Protokollgruppen-ARNs (logGroupArns), keine Protokollgruppennamen. Dies unterscheidet sich von Batch-Auswertungen, die verwendenlogGroupNames.

    Feld Typ Erforderlich Description

    cloudwatchLogs.logGroupArns

    Liste von Zeichenfolgen

    Ja

    CloudWatch Protokolliert Gruppen-ARNs, in denen die Agententelemetrie gespeichert ist. Format:. arn:aws:logs:{region}:{account}:log-group:{log-group-name}

    cloudwatchLogs.serviceNames

    Liste von Zeichenfolgen

    Ja

    Dienstnamen, die die Spuren Ihres Agenten in identifizieren CloudWatch. Konvention:{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    ISO 8601 Datum/Uhrzeit

    Ja

    Beginn des Fensters zur Erfassung von Traces. Nur Traces, die nach dieser Zeit liegen, sind enthalten.

    cloudwatchLogs.endTime

    ISO 8601 Datum/Uhrzeit

    Ja

    Ende des Fensters zur Erfassung von Traces. Nur Traces vor diesem Zeitpunkt sind enthalten.

    cloudwatchLogs.rule

    Objekt

    Nein

    Optionale Filterregel zur Eingrenzung der Trace-Auswahl. Enthält eine filters Liste, in der jeder Filter einkey, operator (z. B.LESS_THAN) und value (z. B.{"doubleValue": 0.5}) angibt.
    Beispiel
    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,
    }
}

    Mit einem optionalen Regelfilter, um nur Sitzungen mit geringer Leistung auszuwählen:

    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}
                }
            ]
        },
    }
}

  • Inline-Sitzungsspannen: Wird verwendet, wenn Traces lokal verfügbar sind (z. B. von einem lokalen Testlauf, einer CI/CD Pipeline oder einer bestimmten Sitzung, für die Sie optimieren möchten). Sie geben die Spans direkt im Hauptteil der API-Anfrage als Liste von OpenTelemetry-compatible Span-Objekten an.

    Feld Typ Erforderlich Description

    sessionSpans

    Liste von Objekten

    Ja

    Agenten-Trace-Spans im OpenTelemetry-compatible Format. Jeder Bereich umfasst Trace-ID, Span-ID, Namen, Zeitstempel und Attribute.
    Beispiel
    AgentCore CLI

    Spans-Datei (liest Spans aus einer lokalen JSON-Datei 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 assistant..." \
  --spans-file agent-traces.json

    Spezifische Sitzungs-IDs (die CLI sammelt Spans 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 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
}
Anmerkung

agentcore run recommendationist asynchron. Ohne diese --wait Option leitet der Befehl den Empfehlungsauftrag weiter und kehrt sofort zurück. Der Job wird in einem Zustand gestartet, der kein Terminal ist (z. B. PENDING oderIN_PROGRESS), und Sie rufen das Ergebnis später ab. Gehen Sie --wait zum Blockieren über, bis die Empfehlung einen Terminalstatus erreicht hat. Um das Ergebnis eines gesendeten Jobs abzufragen oder abzurufen, führen Sie den Befehlagentcore view recommendation <id>, where id is the Recommendation Job ID, aus.

Die AgentCore CLI bietet praktische Flags, die den zugrunde liegenden API-Trace-Quelltypen zugeordnet sind:

CLI-Flagge API-Zuweisungen Description

--lookback <days>

cloudwatchLogsmit berechneten startTime und endTime

Sammelt Spuren der letzten N Tage über CloudWatch Logs. Die CLI löst Protokollgruppen-ARNs und Dienstnamen aus der Laufzeitkonfiguration auf.

--session-id <id>

sessionSpans(inline)

Sammelt Bereiche für die angegebene Sitzung auf der Clientseite und übergibt sie als Inline-Sitzungsspannen. Die Empfehlungs-API selbst unterstützt keine Sitzungs-ID-Filterung nach Quellen. CloudWatch

--spans-file <path>

sessionSpans(inline)

Liest Spans aus einer lokalen JSON-Datei und übergibt sie als Inline-Session-Spans.

--wait

n/a (clientseitige Abfrage)

Blockiert, bis die Empfehlung einen Endstatus erreicht hat.