# One-time Insights-Bericht Verwenden Sie diese `StartBatchEvaluation` Option, um eine On-Demand-Analyse von Erkenntnissen über die Sitzungen Ihres Agenten durchzuführen. Dies ist nützlich, wenn Sie das Verhalten von Agenten nach einer Bereitstellung, einer Zunahme von Ausfällen oder als regelmäßige manuelle Überprüfung untersuchen möchten. **Topics** + [Starten Sie die Analyse](#insights-one-time-start) + [Umfrage nach Ergebnissen](#insights-one-time-poll) + [Überprüfen Sie die Ergebnisse der Fehleranalyse](#insights-one-time-review) + [Ergebnisse der Benutzerabsicht](#insights-one-time-user-intent) + [Zusammenfassung der Ergebnisse der Ausführung](#insights-one-time-execution-summary) + [Ergebnisse interpretieren](#insights-one-time-interpreting) + [Regeln für die Validierung](#insights-one-time-validation) ## Starten Sie die Analyse **Example** ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json ``` Die CLI ist standardmäßig asynchron — sie druckt die Job-ID und wird beendet. Verwenden Sie diese `--wait` Option, um zu blockieren, bis der Job abgeschlossen ist: ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json ``` Wenn Sie bereits eine Konfiguration für die Online-Evaluierung bereitgestellt haben, können Sie deren Einstellungen übernehmen: ``` agentcore run insights --online-eval-config-arn --json ``` 1. Starten Sie`agentcore`, um die TUI zu öffnen, wählen Sie dann **Ausführen** und anschließend **Insights** aus: ![Menü ausführen: Wählen Sie Insights](http://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/insights-run-select.png) 1. Wählen Sie die Sitzungsquelle aus: ![Insights-Assistenten ausführen: Sitzungsquelle wählen](http://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/insights-run-source.png) 1. Wählen Sie die Insights aus, die ausgeführt werden sollen: ![Insights-Assistenten ausführen: Wählen Sie Insights aus](http://docs.aws.amazon.com/de_de/bedrock-agentcore/latest/devguide/images/tui/insights-run-insights.png) Fahren Sie mit den verbleibenden Schritten des Assistenten fort (Sitzungen, Lookback-Zeitraum, Name) und bestätigen Sie. ``` import boto3 import uuid client = boto3.client("bedrock-agentcore", region_name="us-west-2") response = client.start_batch_evaluation( batchEvaluationName=f"insights-run-{uuid.uuid4().hex[:8]}", insights=[ {"insightId": "Builtin.Insight.FailureAnalysis"}, {"insightId": "Builtin.Insight.UserIntent"}, ], dataSourceConfig={ "cloudWatchLogs": { "serviceNames": ["MyAgent.DEFAULT"], "logGroupNames": [ "/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT" ], } }, # Optional: narrow to a specific time range filterConfig={ "timeRange": { "startTime": "2026-05-27T00:00:00Z", "endTime": "2026-06-03T00:00:00Z", }, # Or analyze specific sessions by ID "sessionIds": ["session-001", "session-002", "session-003"] }, clientToken=str(uuid.uuid4()), ) batch_eval_id = response["batchEvaluationId"] print(f"Started: {batch_eval_id}") ``` Sie können auch: + Grenzen Sie die Analyse auf einen bestimmten Zeitraum ein, indem Sie Folgendes hinzufügen `filterConfig.timeRange` + Analysieren Sie bestimmte Sitzungen anhand ihrer ID mit `filterConfig.sessionIds` ## Umfrage nach Ergebnissen **Example** Alle Insights-Jobs auflisten: ``` agentcore view insights --json ``` Details für einen bestimmten Job anzeigen: ``` agentcore view insights --json ``` ``` import time while True: result = client.get_batch_evaluation(batchEvaluationId=batch_eval_id) status = result["status"] print(f"Status: {status}") if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"): break time.sleep(30) ``` ## Überprüfen Sie die Ergebnisse der Fehleranalyse ``` if "failureAnalysisResult" in result: for category in result["failureAnalysisResult"]["failures"]: print(f"\nCategory: {category['name']} ({category['affectedSessionCount']} sessions)") for sub in category.get("subCategories", []): print(f" Subcategory: {sub['name']} ({sub['affectedSessionCount']} sessions)") for rc in sub.get("rootCauses", []): print(f" Root cause: {rc['name']}") print(f" Recommendation: {rc['recommendation']}") print(f" Affected sessions: {rc['affectedSessionCount']}") ``` | Feld | Typ | Description | | --- | --- | --- | | `failures[].name` | Zeichenfolge | Name der Fehlerkategorie (z. B. „Ausführungsfehler“, „Halluzinationen“). | | `failures[].affectedSessionCount` | Ganzzahl | Anzahl der von dieser Kategorie betroffenen Sitzungen. | | `failures[].subCategories[].name` | Zeichenfolge | Name der Unterkategorie (z. B. „Ratenbegrenzung“, „Verstöße gegen das Toolschema“). | | `failures[].subCategories[].affectedSessionCount` | Ganzzahl | Anzahl der von dieser Unterkategorie betroffenen Sitzungen. | | `failures[].subCategories[].rootCauses[].name` | Zeichenfolge | Clustername der Grundursache. | | `failures[].subCategories[].rootCauses[].recommendation` | Zeichenfolge | Vorgeschlagene Lösung für diese Hauptursache. | | `failures[].subCategories[].rootCauses[].affectedSessionCount` | Ganzzahl | Anzahl der Sitzungen, die von dieser Grundursache betroffen sind. | | `failures[].subCategories[].rootCauses[].affectedSessions` | Auflisten | Sitzungen in diesem Cluster, jeweils mit`sessionId`. | ## Ergebnisse der Benutzerabsicht Das `userIntentResult` Feld enthält gruppierte Benutzerabsichten: ``` if "userIntentResult" in result: for cluster in result["userIntentResult"]["userIntents"]: print(f" {cluster['name']} ({cluster['affectedSessionCount']} sessions)") print(f" {cluster['description']}") ``` | Feld | Typ | Description | | --- | --- | --- | | `userIntents[].clusterId` | Ganzzahl | Cluster-ID. | | `userIntents[].name` | Zeichenfolge | Clustername, der die gemeinsame Absicht beschreibt. | | `userIntents[].description` | Zeichenfolge | Detaillierte Beschreibung des Absichtsmusters. | | `userIntents[].affectedSessionCount` | Ganzzahl | Anzahl der Sitzungen mit dieser Absicht. | | `userIntents[].affectedSessions` | Auflisten | Sitzungen in diesem Cluster, jeweils mit `sessionId` und`userMessages`. | ## Zusammenfassung der Ergebnisse der Ausführung Das `executionSummaryResult` Feld enthält geclusterte Ausführungsmuster: | Feld | Typ | Description | | --- | --- | --- | | `executionSummaries[].clusterId` | Ganzzahl | Cluster-ID. | | `executionSummaries[].name` | Zeichenfolge | Clustername, der das Ausführungsmuster beschreibt. | | `executionSummaries[].description` | Zeichenfolge | Detaillierte Beschreibung des Musters. | | `executionSummaries[].affectedSessionCount` | Ganzzahl | Anzahl der Sitzungen mit diesem Muster. | | `executionSummaries[].affectedSessions` | Auflisten | Sitzungen in diesem Cluster, jeweils mit `sessionId``approachTaken`, und`finalOutcome`. | ## Ergebnisse interpretieren + **Beginnen Sie mit der Fehleranalyse:** Konzentrieren Sie sich auf die Kategorien mit den höchsten Werten`affectedSessionCount`. Dies sind die wichtigsten Probleme. + **Gehen Sie den Ursachen auf den Grund:** In jeder Unterkategorie erfahren Sie anhand von Ursachenclustern genau, was falsch läuft und wie Sie es beheben können. Jeder Cluster umfasst ein `recommendation` Feld. + **Verwenden Sie Benutzerabsichten, um Prioritäten zu setzen: Cross-reference Fehlerkategorien** mit Benutzerabsichtsclustern. Fehler, die sich auf Ihre häufigsten Benutzerabsichten auswirken, sollten höchste Priorität haben. + **Ausführungsmuster verfolgen: Anhand** von Ausführungszusammenfassungen wird aufgezeigt, wie Ihr Agent Probleme angeht. So können Sie nachvollziehen, ob Fehler eher auf die Strategie des Agenten als auf Probleme zurückzuführen sind. tool/environment ## Regeln für die Validierung + `insights`und schließen `evaluators` sich gegenseitig aus — geben Sie das eine oder das andere an, nicht beides. + Maximal 10 Erkenntnisse pro Anfrage. + `dataSourceConfig`ist erforderlich und muss mindestens eine Protokollgruppe und einen Dienstnamen enthalten. + Wenn Sie es verwenden`onlineEvaluationConfigSource`, geben Sie `insights` oder nicht an `evaluators` (die Konfiguration wird vererbt). + Wenn `filterConfig.timeRange` angegeben, `startTime` muss es früher als sein`endTime`. + Zeitstempel müssen ein gültiges ISO 8601-Format haben. + Pro Konto kann jeweils nur eine Batch-Auswertung aktiv sein. + Pro Insights-Run werden maximal 500 Sitzungen analysiert.