# One-time informe de información
Úselo `StartBatchEvaluation` para realizar un análisis de información a pedido sobre las sesiones de su agente. Esto resulta útil cuando se quiere investigar el comportamiento de los agentes después de una implementación, si se produce un aumento en el número de errores o si se trata de una comprobación manual periódica.
**Topics**
+ [Inicie el análisis](#insights-one-time-start)
+ [Sondeo de resultados](#insights-one-time-poll)
+ [Revise los hallazgos del análisis de fallas](#insights-one-time-review)
+ [Resultados de la intención del usuario](#insights-one-time-user-intent)
+ [Resultados resumidos de la ejecución](#insights-one-time-execution-summary)
+ [Interpretación de los resultados](#insights-one-time-interpreting)
+ [Reglas de validación](#insights-one-time-validation)
## Inicie el análisis
**Example**
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json
```
La CLI es asíncrona de forma predeterminada: imprime el ID del trabajo y sale. Se usa `--wait` para bloquear hasta que se complete el trabajo:
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json
```
Si ya tiene implementada una configuración de evaluación en línea, puede heredar su configuración:
```
agentcore run insights --online-eval-config-arn --json
```
1. **Ejecute `agentcore` para abrir la TUI, luego seleccione **ejecutar** y elija Insights:**
1. Elija la fuente de la sesión:
1. Seleccione las estadísticas que desee ejecutar:
Continúe con los pasos restantes del asistente (sesiones, período retrospectivo, nombre) y confirme.
```
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}")
```
También puede:
+ Limite el análisis a un intervalo de tiempo específico añadiendo `filterConfig.timeRange`
+ Analice sesiones específicas por ID utilizando `filterConfig.sessionIds`
## Sondeo de resultados
**Example**
Enumere todos los trabajos de Insights:
```
agentcore view insights --json
```
Vea los detalles de un trabajo específico:
```
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)
```
## Revise los hallazgos del análisis de fallas
```
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 (Descripción) |
| --- | --- | --- |
| `failures[].name` | Cadena | Nombre de la categoría de error (p. ej., «Errores de ejecución», «Alucinaciones»). |
| `failures[].affectedSessionCount` | Entero | Número de sesiones afectadas por esta categoría. |
| `failures[].subCategories[].name` | Cadena | Nombre de la subcategoría (p. ej., «Limitación de velocidad» o «Infracciones del esquema de herramientas»). |
| `failures[].subCategories[].affectedSessionCount` | Entero | Número de sesiones afectadas por esta subcategoría. |
| `failures[].subCategories[].rootCauses[].name` | Cadena | Nombre del clúster de causa raíz. |
| `failures[].subCategories[].rootCauses[].recommendation` | Cadena | Solución sugerida para esta causa raíz. |
| `failures[].subCategories[].rootCauses[].affectedSessionCount` | Entero | Número de sesiones afectadas por esta causa raíz. |
| `failures[].subCategories[].rootCauses[].affectedSessions` | Enumeración | Sesiones de este clúster, cada una con`sessionId`. |
## Resultados de la intención del usuario
El `userIntentResult` campo contiene las intenciones de los usuarios agrupadas:
```
if "userIntentResult" in result:
for cluster in result["userIntentResult"]["userIntents"]:
print(f" {cluster['name']} ({cluster['affectedSessionCount']} sessions)")
print(f" {cluster['description']}")
```
| Campo | Tipo | Description (Descripción) |
| --- | --- | --- |
| `userIntents[].clusterId` | Entero | Identificador de clúster. |
| `userIntents[].name` | Cadena | Nombre del clúster que describe la intención común. |
| `userIntents[].description` | Cadena | Descripción detallada del patrón de intención. |
| `userIntents[].affectedSessionCount` | Entero | Número de sesiones con esta intención. |
| `userIntents[].affectedSessions` | Enumeración | Sesiones de este grupo, cada una con `sessionId` y`userMessages`. |
## Resultados resumidos de la ejecución
El `executionSummaryResult` campo contiene patrones de ejecución agrupados:
| Campo | Tipo | Description (Descripción) |
| --- | --- | --- |
| `executionSummaries[].clusterId` | Entero | Identificador de clúster. |
| `executionSummaries[].name` | Cadena | Nombre del clúster que describe el patrón de ejecución. |
| `executionSummaries[].description` | Cadena | Descripción detallada del patrón. |
| `executionSummaries[].affectedSessionCount` | Entero | Número de sesiones con este patrón. |
| `executionSummaries[].affectedSessions` | Enumeración | Sesiones de este grupo, cada una con `sessionId``approachTaken`, y`finalOutcome`. |
## Interpretación de los resultados
+ **Comience con el análisis de los errores:** céntrese en las categorías con los valores más altos`affectedSessionCount`. Estos representan los problemas más impactantes.
+ **Profundice en las causas fundamentales:** dentro de cada subcategoría, los clústeres de causas fundamentales indican exactamente qué es lo que está fallando y cómo solucionarlo. Cada clúster incluye un `recommendation` campo.
+ **Utilice las intenciones del usuario para priorizar:** categorías de Cross-reference errores con clústeres de intención del usuario. Los errores que afecten a las intenciones de usuario más comunes deberían ser de máxima prioridad.
+ **Realice un seguimiento de los patrones de ejecución:** los resúmenes de ejecución revelan cómo su agente aborda los problemas, lo que resulta útil para comprender si los errores se deben a la estrategia del agente o a tool/environment problemas.
## Reglas de validación
+ `insights`y `evaluators` se excluyen mutuamente: proporcionan una u otra, no ambas.
+ Máximo 10 estadísticas por solicitud.
+ `dataSourceConfig`es obligatorio y debe incluir al menos un grupo de registros y un nombre de servicio.
+ Si lo usa`onlineEvaluationConfigSource`, no proporcione `insights` o `evaluators` (la configuración se hereda).
+ Si `filterConfig.timeRange` se especifica, `startTime` debe ser anterior a`endTime`.
+ Las marcas horarias deben tener un formato ISO 8601 válido.
+ Solo puede estar activa una evaluación de lote por cuenta a la vez.
+ Se analizan un máximo de 500 sesiones por ejecución de insights.