# 일회성 인사이트 보고서 `StartBatchEvaluation`를 사용하여 에이전트의 세션에 대한 온디맨드 인사이트 분석을 실행합니다. 이는 배포, 실패 급증 또는 정기적인 수동 확인 후 에이전트 동작을 조사하려는 경우에 유용합니다. **Topics** + [분석 시작](#insights-one-time-start) + [결과에 대한 폴링](#insights-one-time-poll) + [실패 분석 결과 검토](#insights-one-time-review) + [사용자 의도 결과](#insights-one-time-user-intent) + [실행 요약 결과](#insights-one-time-execution-summary) + [결과 해석](#insights-one-time-interpreting) + [검증 규칙](#insights-one-time-validation) ## 분석 시작 **Example** ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json ``` CLI는 기본적으로 비동기 식으로 , 작업 ID를 인쇄하고 종료합니다. `--wait`를 사용하여 작업이 완료될 때까지 차단합니다. ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json ``` 온라인 평가 구성이 이미 배포된 경우 해당 설정을 상속할 수 있습니다. ``` agentcore run insights --online-eval-config-arn --json ``` 1. 를 실행`agentcore`하여 TUI를 연 다음 **실행**을 선택하고 **인사이트를** 선택합니다. ![실행 메뉴: Insights를 선택합니다.](http://docs.aws.amazon.com/ko_kr/bedrock-agentcore/latest/devguide/images/tui/insights-run-select.png) 1. 세션 소스를 선택합니다. ![인사이트 실행 마법사: 세션 소스 선택](http://docs.aws.amazon.com/ko_kr/bedrock-agentcore/latest/devguide/images/tui/insights-run-source.png) 1. 실행할 인사이트를 선택합니다. ![인사이트 실행 마법사: 인사이트 선택](http://docs.aws.amazon.com/ko_kr/bedrock-agentcore/latest/devguide/images/tui/insights-run-insights.png) 나머지 마법사 단계(세션, 룩백 기간, 이름)를 계속 진행하고 확인합니다. ``` 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}") ``` 다른 방법: + 를 추가하여 분석을 특정 시간 범위로 좁힙니다. `filterConfig.timeRange` + 를 사용하여 ID별로 특정 세션 분석 `filterConfig.sessionIds` ## 결과에 대한 폴링 **Example** 모든 인사이트 작업 나열: ``` agentcore view insights --json ``` 특정 작업에 대한 세부 정보를 봅니다. ``` 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) ``` ## 실패 분석 결과 검토 ``` 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']}") ``` | Field | 유형 | 설명 | | --- | --- | --- | | `failures[].name` | 문자열 | 실패 범주 이름(예: "실행 오류", "할루시네이션"). | | `failures[].affectedSessionCount` | Integer | 이 범주의 영향을 받는 세션 수입니다. | | `failures[].subCategories[].name` | 문자열 | 하위 범주 이름(예: "속도 제한", "도구 스키마 위반"). | | `failures[].subCategories[].affectedSessionCount` | Integer | 이 하위 범주의 영향을 받는 세션 수입니다. | | `failures[].subCategories[].rootCauses[].name` | 문자열 | 근본 원인 클러스터 이름입니다. | | `failures[].subCategories[].rootCauses[].recommendation` | 문자열 | 이 근본 원인에 대한 권장 수정 사항입니다. | | `failures[].subCategories[].rootCauses[].affectedSessionCount` | Integer | 이 근본 원인의 영향을 받는 세션 수입니다. | | `failures[].subCategories[].rootCauses[].affectedSessions` | List | 이 클러스터의 세션, 각각 . `sessionId` | ## 사용자 의도 결과 `userIntentResult` 필드에는 클러스터링된 사용자 의도가 포함됩니다. ``` if "userIntentResult" in result: for cluster in result["userIntentResult"]["userIntents"]: print(f" {cluster['name']} ({cluster['affectedSessionCount']} sessions)") print(f" {cluster['description']}") ``` | Field | 유형 | 설명 | | --- | --- | --- | | `userIntents[].clusterId` | Integer | 클러스터 식별자입니다. | | `userIntents[].name` | 문자열 | 공통 의도를 설명하는 클러스터 이름입니다. | | `userIntents[].description` | 문자열 | 의도 패턴에 대한 자세한 설명입니다. | | `userIntents[].affectedSessionCount` | Integer | 이 의도가 있는 세션 수입니다. | | `userIntents[].affectedSessions` | List | 각각 `sessionId` 및가 있는이 클러스터의 세션`userMessages`. | ## 실행 요약 결과 `executionSummaryResult` 필드에는 클러스터 실행 패턴이 포함됩니다. | Field | 유형 | 설명 | | --- | --- | --- | | `executionSummaries[].clusterId` | Integer | 클러스터 식별자입니다. | | `executionSummaries[].name` | 문자열 | 실행 패턴을 설명하는 클러스터 이름입니다. | | `executionSummaries[].description` | 문자열 | 패턴에 대한 자세한 설명입니다. | | `executionSummaries[].affectedSessionCount` | Integer | 이 패턴이 있는 세션 수입니다. | | `executionSummaries[].affectedSessions` | List | 이 클러스터의 세션으로, 각각 `sessionId`, `approachTaken`및가 있습니다`finalOutcome`. | ## 결과 해석 + **실패 분석으로 시작:**가 가장 높은 범주에 집중합니다`affectedSessionCount`. 이는 가장 큰 영향을 미치는 문제를 나타냅니다. + **근본 원인 심층 분석:** 각 하위 범주 내에서 근본 원인 클러스터는 무엇이 문제인지와 이를 해결하는 방법을 정확히 알려줍니다. 각 클러스터에는 `recommendation` 필드가 포함됩니다. + **사용자 의도를 사용하여 우선 순위 지정:** 사용자 의도 클러스터와 장애 범주를 상호 참조합니다. 가장 일반적인 사용자 의도에 영향을 미치는 장애는 우선 순위가 가장 높아야 합니다. + **실행 패턴 추적:** 실행 요약은 에이전트가 문제에 접근하는 방법을 보여줍니다. 즉, 실패가 에이전트의 전략과 도구/환경 문제에서 비롯되는지 여부를 이해하는 데 유용합니다. ## 검증 규칙 + `insights` 및 `evaluators`는 상호 배타적입니다. 둘 다 제공하지 않고 둘 중 하나를 제공합니다. + 요청당 최대 10개의 인사이트. + `dataSourceConfig`는 필수이며 하나 이상의 로그 그룹과 하나의 서비스 이름을 포함해야 합니다. + 를 사용하는 경우 `insights` 또는를 제공하지 `onlineEvaluationConfigSource`마십시오`evaluators`(구성은 상속됨). + `filterConfig.timeRange`이 지정된 경우는 보다 이전이어야 `startTime` 합니다`endTime`. + 타임스탬프는 유효한 ISO 8601 형식이어야 합니다. + 한 번에 계정당 하나의 배치 평가만 활성화할 수 있습니다. + 인사이트 실행당 최대 500개의 세션이 분석됩니다.