View a markdown version of this page

One-time laporan wawasan - Batuan Dasar Amazon AgentCore
Mulai analisisPolling untuk hasilTinjau temuan analisis kegagalanHasil maksud penggunaHasil ringkasan eksekusiMenafsirkan hasilAturan validasi

One-time laporan wawasan

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.

Mulai analisis

contoh
AgentCore CLI
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
Interactive

  1. Jalankan agentcore untuk membuka TUI, lalu pilih jalankan dan pilih Wawasan:

    Jalankan menu: pilih Wawasan

  2. Pilih sumber sesi:

    Jalankan Wizard Wawasan: pilih sumber sesi

  3. Pilih wawasan yang akan dijalankan:

    Jalankan Wizard Wawasan: pilih wawasan

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

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}")

Anda juga dapat:

  • Persempit analisis ke rentang waktu tertentu dengan menambahkan filterConfig.timeRange

  • Analisis sesi tertentu dengan ID menggunakan filterConfig.sessionIds

Polling untuk hasil

contoh
AgentCore CLI

Daftar semua lowongan wawasan:

agentcore view insights --json

Lihat detail untuk pekerjaan tertentu:

agentcore view insights <id> --json
AWS SDK (boto3)
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

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 dengansessionId.

Hasil maksud pengguna

userIntentResultBidang 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 danuserMessages.

Hasil ringkasan eksekusi

executionSummaryResultBidang 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 dengansessionId,approachTaken, danfinalOutcome.

Menafsirkan hasil

  • Mulailah dengan analisis kegagalan: Fokus pada kategori dengan yang tertinggiaffectedSessionCount. 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

  • insightsdan evaluators saling eksklusif - berikan satu atau yang lain, bukan keduanya.

  • Maksimal 10 wawasan per permintaan.

  • dataSourceConfigdiperlukan dan harus menyertakan setidaknya satu grup log dan satu nama layanan.

  • Jika menggunakanonlineEvaluationConfigSource, jangan berikan insights atau evaluators (konfigurasi diwarisi).

  • Jika filterConfig.timeRange ditentukan, startTime harus lebih awal dariendTime.

  • 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.