# One-time rapporto di approfondimento
Utilizzalo `StartBatchEvaluation` per eseguire un'analisi approfondita su richiesta delle sessioni del tuo agente. Ciò è utile quando si desidera analizzare il comportamento degli agenti dopo una distribuzione, un picco di guasti o come controllo manuale periodico.
**Topics**
+ [Avviate l'analisi](#insights-one-time-start)
+ [Sondaggio per visualizzare i risultati](#insights-one-time-poll)
+ [Esamina i risultati dell'analisi degli errori](#insights-one-time-review)
+ [Risultati delle intenzioni dell'utente](#insights-one-time-user-intent)
+ [Riepilogo dei risultati dell'esecuzione](#insights-one-time-execution-summary)
+ [Interpretazione dei risultati](#insights-one-time-interpreting)
+ [Regole di convalida](#insights-one-time-validation)
## Avviate l'analisi
**Example**
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json
```
La CLI è asincrona per impostazione predefinita: stampa l'ID del lavoro ed esce. Utilizzalo `--wait` per bloccare fino al completamento del lavoro:
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json
```
Se disponi già di una configurazione di valutazione online, puoi ereditarne le impostazioni:
```
agentcore run insights --online-eval-config-arn --json
```
1. **Esegui `agentcore` per aprire la TUI, quindi seleziona **esegui** e scegli Insights:**
1. Scegli la fonte della sessione:
1. Seleziona gli approfondimenti da eseguire:
Continua con i passaggi rimanenti della procedura guidata (sessioni, periodo di lookback, nome) e conferma.
```
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}")
```
Puoi anche:
+ Restringi l'analisi a un intervallo di tempo specifico aggiungendo `filterConfig.timeRange`
+ Analizza sessioni specifiche per ID utilizzando `filterConfig.sessionIds`
## Sondaggio per visualizzare i risultati
**Example**
Elenca tutti i lavori in Insights:
```
agentcore view insights --json
```
Visualizza i dettagli di un lavoro specifico:
```
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)
```
## Esamina i risultati dell'analisi degli errori
```
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']}")
```
| Campo | Tipo | Description |
| --- | --- | --- |
| `failures[].name` | Stringa | Nome della categoria di errore (ad es. «Errori di esecuzione», «Allucinazioni»). |
| `failures[].affectedSessionCount` | Numero intero | Numero di sessioni interessate da questa categoria. |
| `failures[].subCategories[].name` | Stringa | Nome della sottocategoria (ad esempio, «Rate limiting», «Violazioni dello schema degli strumenti»). |
| `failures[].subCategories[].affectedSessionCount` | Numero intero | Numero di sessioni interessate da questa sottocategoria. |
| `failures[].subCategories[].rootCauses[].name` | Stringa | Nome della causa principale del cluster. |
| `failures[].subCategories[].rootCauses[].recommendation` | Stringa | Correzione consigliata per questa causa principale. |
| `failures[].subCategories[].rootCauses[].affectedSessionCount` | Numero intero | Numero di sessioni interessate da questa causa principale. |
| `failures[].subCategories[].rootCauses[].affectedSessions` | List | Sessioni in questo cluster, ciascuna con`sessionId`. |
## Risultati delle intenzioni dell'utente
Il `userIntentResult` campo contiene intenti utente raggruppati:
```
if "userIntentResult" in result:
for cluster in result["userIntentResult"]["userIntents"]:
print(f" {cluster['name']} ({cluster['affectedSessionCount']} sessions)")
print(f" {cluster['description']}")
```
| Campo | Tipo | Description |
| --- | --- | --- |
| `userIntents[].clusterId` | Numero intero | Identificatore del cluster. |
| `userIntents[].name` | Stringa | Nome del cluster che descrive l'intento comune. |
| `userIntents[].description` | Stringa | Descrizione dettagliata del modello di intento. |
| `userIntents[].affectedSessionCount` | Numero intero | Numero di sessioni con questo intento. |
| `userIntents[].affectedSessions` | List | Sessioni in questo cluster, ognuna con `sessionId` e`userMessages`. |
## Riepilogo dei risultati dell'esecuzione
Il `executionSummaryResult` campo contiene modelli di esecuzione raggruppati:
| Campo | Tipo | Description |
| --- | --- | --- |
| `executionSummaries[].clusterId` | Numero intero | Identificatore del cluster. |
| `executionSummaries[].name` | Stringa | Nome del cluster che descrive il modello di esecuzione. |
| `executionSummaries[].description` | Stringa | Descrizione dettagliata del pattern. |
| `executionSummaries[].affectedSessionCount` | Numero intero | Numero di sessioni con questo schema. |
| `executionSummaries[].affectedSessions` | List | Sessioni in questo cluster, ciascuna con `sessionId``approachTaken`, e`finalOutcome`. |
## Interpretazione dei risultati
+ **Inizia con l'analisi degli errori:** concentrati sulle categorie con i risultati più elevati`affectedSessionCount`. Queste sono le questioni più importanti.
+ **Approfondisci le cause principali:** all'interno di ogni sottocategoria, i cluster di cause principali indicano esattamente cosa non va e come risolverlo. Ogni cluster include un campo. `recommendation`
+ **Usa le intenzioni degli utenti per stabilire le priorità: categorie di Cross-reference errori con i cluster di intenti** degli utenti. Gli errori che influiscono sulle intenzioni degli utenti più comuni dovrebbero avere la massima priorità.
+ **Tieni traccia dei modelli di esecuzione:** i riepiloghi dell'esecuzione rivelano come l'agente affronta i problemi, utili per capire se gli errori derivano dalla strategia dell'agente o dai problemi. tool/environment
## Regole di convalida
+ `insights`e `evaluators` si escludono a vicenda: fornisci l'una o l'altra, non entrambe.
+ Massimo 10 approfondimenti per richiesta.
+ `dataSourceConfig`è obbligatorio e deve includere almeno un gruppo di log e un nome di servizio.
+ Se si utilizza`onlineEvaluationConfigSource`, non fornire `insights` o `evaluators` (la configurazione è ereditata).
+ Se `filterConfig.timeRange` specificato, `startTime` deve essere precedente a. `endTime`
+ I timestamp devono essere in formato ISO 8601 valido.
+ Può essere attiva una sola valutazione in batch per account alla volta.
+ Vengono analizzate un massimo di 500 sessioni per ogni analisi approfondita.