# One-time laporan wawasan
<a name="insights-one-time-report"></a>

Gunakan `StartBatchEvaluation` untuk menjalankan analisis wawasan sesuai permintaan selama sesi agen Anda. Ini berguna saat Anda ingin menyelidiki perilaku agen setelah penerapan, lonjakan kegagalan, atau sebagai pemeriksaan manual berkala.

**Topics**
+ [Mulai analisis](#insights-one-time-start)
+ [Polling untuk hasil](#insights-one-time-poll)
+ [Tinjau temuan analisis kegagalan](#insights-one-time-review)
+ [Hasil maksud pengguna](#insights-one-time-user-intent)
+ [Hasil ringkasan eksekusi](#insights-one-time-execution-summary)
+ [Menafsirkan hasil](#insights-one-time-interpreting)
+ [Aturan validasi](#insights-one-time-validation)

## Mulai analisis
<a name="insights-one-time-start"></a>

**Example**  

```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json
```
CLI adalah async secara default - ia mencetak ID pekerjaan dan keluar. Gunakan `--wait` untuk memblokir sampai pekerjaan selesai:  

```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json
```
Jika Anda memiliki konfigurasi evaluasi online yang sudah diterapkan, Anda dapat mewarisi pengaturannya:  

```
agentcore run insights --online-eval-config-arn <arn> --json
```

1. Jalankan `agentcore` untuk membuka TUI, lalu pilih **jalankan** dan pilih **Wawasan**:  
![Jalankan menu: pilih Wawasan](http://docs.aws.amazon.com/id_id/bedrock-agentcore/latest/devguide/images/tui/insights-run-select.png)

1. Pilih sumber sesi:  
![Jalankan Wizard Wawasan: pilih sumber sesi](http://docs.aws.amazon.com/id_id/bedrock-agentcore/latest/devguide/images/tui/insights-run-source.png)

1. Pilih wawasan yang akan dijalankan:  
![Jalankan Wizard Wawasan: pilih wawasan](http://docs.aws.amazon.com/id_id/bedrock-agentcore/latest/devguide/images/tui/insights-run-insights.png)

   Lanjutkan melalui langkah-langkah wizard yang tersisa (sesi, periode lookback, nama) dan konfirmasi.

```
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}")
```
Anda juga dapat:  
+ Persempit analisis ke rentang waktu tertentu dengan menambahkan `filterConfig.timeRange` 
+ Analisis sesi tertentu dengan ID menggunakan `filterConfig.sessionIds` 

## Polling untuk hasil
<a name="insights-one-time-poll"></a>

**Example**  
Daftar semua lowongan wawasan:  

```
agentcore view insights --json
```
Lihat detail untuk pekerjaan tertentu:  

```
agentcore view insights <id> --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)
```

## Tinjau temuan analisis kegagalan
<a name="insights-one-time-review"></a>

```
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']}")
```


| Bidang | Tipe | Deskripsi | 
| --- | --- | --- | 
|  `failures[].name`  | String | Nama kategori kegagalan (misalnya, “Kesalahan eksekusi”, “Halusinasi”). | 
|  `failures[].affectedSessionCount`  | Bilangan Bulat | Jumlah sesi yang dipengaruhi oleh kategori ini. | 
|  `failures[].subCategories[].name`  | String | Nama subkategori (misalnya, “Pembatasan tarif”, “Pelanggaran skema alat”). | 
|  `failures[].subCategories[].affectedSessionCount`  | Bilangan Bulat | Jumlah sesi yang dipengaruhi oleh subkategori ini. | 
|  `failures[].subCategories[].rootCauses[].name`  | String | Nama cluster akar penyebab. | 
|  `failures[].subCategories[].rootCauses[].recommendation`  | String | Perbaikan yang disarankan untuk akar penyebab ini. | 
|  `failures[].subCategories[].rootCauses[].affectedSessionCount`  | Bilangan Bulat | Jumlah sesi yang dipengaruhi oleh akar penyebab ini. | 
|  `failures[].subCategories[].rootCauses[].affectedSessions`  | Daftar | Sesi di cluster ini, masing-masing dengan`sessionId`. | 

## Hasil maksud pengguna
<a name="insights-one-time-user-intent"></a>

`userIntentResult`Bidang berisi maksud pengguna yang dikelompokkan:

```
if "userIntentResult" in result:
    for cluster in result["userIntentResult"]["userIntents"]:
        print(f"  {cluster['name']} ({cluster['affectedSessionCount']} sessions)")
        print(f"    {cluster['description']}")
```


| Bidang | Tipe | Deskripsi | 
| --- | --- | --- | 
|  `userIntents[].clusterId`  | Bilangan Bulat | Pengidentifikasi cluster. | 
|  `userIntents[].name`  | String | Nama cluster yang menggambarkan maksud umum. | 
|  `userIntents[].description`  | String | Penjelasan rinci tentang pola maksud. | 
|  `userIntents[].affectedSessionCount`  | Bilangan Bulat | Jumlah sesi dengan maksud ini. | 
|  `userIntents[].affectedSessions`  | Daftar | Sesi di cluster ini, masing-masing dengan `sessionId` dan`userMessages`. | 

## Hasil ringkasan eksekusi
<a name="insights-one-time-execution-summary"></a>

`executionSummaryResult`Bidang berisi pola eksekusi berkerumun:


| Bidang | Tipe | Deskripsi | 
| --- | --- | --- | 
|  `executionSummaries[].clusterId`  | Bilangan Bulat | Pengidentifikasi cluster. | 
|  `executionSummaries[].name`  | String | Nama cluster yang menggambarkan pola eksekusi. | 
|  `executionSummaries[].description`  | String | Penjelasan rinci tentang pola. | 
|  `executionSummaries[].affectedSessionCount`  | Bilangan Bulat | Jumlah sesi dengan pola ini. | 
|  `executionSummaries[].affectedSessions`  | Daftar | Sesi di cluster ini, masing-masing dengan`sessionId`,`approachTaken`, dan`finalOutcome`. | 

## Menafsirkan hasil
<a name="insights-one-time-interpreting"></a>
+  **Mulailah dengan analisis kegagalan:** Fokus pada kategori dengan yang tertinggi`affectedSessionCount`. Ini mewakili masalah yang paling berdampak.
+  **Telusuri akar penyebab:** Dalam setiap subkategori, kluster akar penyebab memberi tahu Anda dengan tepat apa yang salah dan bagaimana memperbaikinya. Setiap cluster mencakup `recommendation` bidang.
+  **Gunakan maksud pengguna untuk memprioritaskan:** kategori Cross-reference kegagalan dengan kluster maksud pengguna. Kegagalan yang memengaruhi maksud pengguna Anda yang paling umum harus menjadi prioritas tertinggi.
+  **Lacak pola eksekusi:** Ringkasan eksekusi mengungkapkan bagaimana agen Anda mendekati masalah — berguna untuk memahami apakah kegagalan berasal dari strategi agen versus tool/environment masalah.

## Aturan validasi
<a name="insights-one-time-validation"></a>
+  `insights`dan `evaluators` saling eksklusif - berikan satu atau yang lain, bukan keduanya.
+ Maksimal 10 wawasan per permintaan.
+  `dataSourceConfig`diperlukan dan harus menyertakan setidaknya satu grup log dan satu nama layanan.
+ Jika menggunakan`onlineEvaluationConfigSource`, jangan berikan `insights` atau `evaluators` (konfigurasi diwarisi).
+ Jika `filterConfig.timeRange` ditentukan, `startTime` harus lebih awal dari`endTime`.
+ Stempel waktu harus dalam format ISO 8601 yang valid.
+ Hanya satu evaluasi batch yang dapat aktif per akun pada satu waktu.
+ Maksimal 500 sesi dianalisis per wawasan dijalankan.