분석 시작 결과에 대한 폴링 실패 분석 결과 검토 사용자 의도 결과 실행 요약 결과 결과 해석 검증 규칙

일회성 인사이트 보고서

StartBatchEvaluation를 사용하여 에이전트의 세션에 대한 온디맨드 인사이트 분석을 실행합니다. 이는 배포, 실패 급증 또는 정기적인 수동 확인 후 에이전트 동작을 조사하려는 경우에 유용합니다.

주제

분석 시작
결과에 대한 폴링
실패 분석 결과 검토
사용자 의도 결과
실행 요약 결과
결과 해석
검증 규칙

분석 시작

예

AgentCore CLI


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 <arn> --json

Interactive

를 실행agentcore하여 TUI를 연 다음 실행을 선택하고 인사이트를 선택합니다.
세션 소스를 선택합니다.
실행할 인사이트를 선택합니다.

나머지 마법사 단계(세션, 룩백 기간, 이름)를 계속 진행하고 확인합니다.

AWS SDK (boto3)


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

결과에 대한 폴링

예

실패 분석 결과 검토


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개의 세션이 분석됩니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

사전 조건

반복 보고서