View a markdown version of this page

Mendiagnosis masalah AgentCore Evaluasi dengan asisten pengkodean AI - Batuan Dasar Amazon AgentCore
Apa yang didiagnosis keterampilanPrasyaratSalin keterampilanMuat keterampilan ke asisten pengkodean AI AndaJalankan diagnosisContoh interaksiMemecahkan masalah keterampilan itu sendiriDokumentasi terkait

Mendiagnosis masalah AgentCore Evaluasi dengan asisten pengkodean AI

Jika konfigurasi AgentCore Evaluasi Anda tidak menghasilkan hasil — atau jika Anda melihat kesalahan sepertiLogEventMissingException,AgentSpanMappingException, atau skor evaluasi kosong — Anda dapat menggunakan Keterampilan Diagnostik AgentCore Evaluasi untuk memecahkan masalah sendiri.

Keterampilannya adalah file penurunan harga yang bekerja dengan asisten pengkodean AI apa pun. Anda memuatnya ke asisten, memberikan AWS Wilayah, jenis penerapan, dan ID sesi secara opsional, dan asisten memandu Anda melalui diagnosis langkah demi langkah. Keterampilan ini bekerja dengan agen yang digunakan di AgentCore Runtime dan agen yang dihosting di infrastruktur pihak ketiga (Amazon ECS, Amazon EKS, AWS Lambda, atau lingkungan lainnya). Asisten menanyakan grup CloudWatch log Amazon Anda sendiri untuk mengidentifikasi akar penyebab dan merekomendasikan perbaikan.

Apa yang didiagnosis keterampilan

Keterampilan mencakup masalah evaluasi yang paling umum:

  • Hasil evaluasi kosong — tidak ada skor yang muncul meskipun konfigurasi evaluasi diaktifkan.

  • LogEventMissingException— evaluasi melaporkan bahwa rentang tidak memiliki peristiwa log yang sesuai.

  • AgentSpanMappingExceptionatau ToolSpanMappingException— evaluasi tidak dapat mengekstrak kueri pengguna atau output alat dari rentang.

  • SpanEventParsingException— evaluasi tidak dapat mengurai tubuh suatu peristiwa.

  • Gateway Timeout (504)Waktu evaluasi habis.

  • ValidationExceptionon evaluatorId — format ID evaluator salah.

  • Multi-agent masalah pelingkupan evaluasi — evaluator menargetkan agen yang salah dalam jejak multi-agen.

Prasyarat

  • AWS CLI dikonfigurasi dengan kredensil untuk akun tempat agen berjalan. Kredensialnya memerlukan izin berikut:

    • logs:DescribeLogGroups,logs:DescribeLogStreams,logs:StartQuery, logs:GetQueryResults — untuk menanyakan CloudWatch Log

    • bedrock-agentcore:GetOnlineEvaluationConfig, bedrock-agentcore:ListOnlineEvaluationConfigs — untuk membaca konfigurasi evaluasi (hanya evaluasi online)

  • Python 3.9 atau yang lebih baru dengan boto3 perpustakaan direkomendasikan tetapi tidak sepenuhnya diperlukan - kueri diagnostik juga dapat dijalankan melalui CLI secara langsung. AWS

  • Asisten pengkodean AI yang mendukung standar Keterampilan Agen atau yang dapat menerima instruksi penurunan harga.

  • Agen yang telah dipanggil setidaknya sekali dengan observabilitas diaktifkan.

Salin keterampilan

Sumber keterampilan tersedia dalam sumber keterampilan Diagnostik. Salin seluruh blok kode dari topik itu dan simpan seperti SKILL.md di dalam folder baru bernama agentcore-eval-diagnostic/ di mesin Anda.

Keterampilannya adalah file penurunan harga biasa. Ini hanya berisi informasi publik dan hanya berjalan terhadap akun Anda sendiri — tidak diperlukan akses sisi layanan.

Muat keterampilan ke asisten pengkodean AI Anda

Simpan sumber keterampilan dari sumber keterampilan Diagnostik seperti SKILL.md di dalam folder bernama agentcore-eval-diagnostic/ di mesin Anda, lalu pindahkan atau salin folder itu ke direktori keterampilan untuk asisten pengkodean AI Anda. Keterampilan mengikuti standar Keterampilan Agen terbuka, sehingga setiap alat menemukannya dari folder keterampilan khusus sendiri - jangan menambahkan konten keterampilan ke file instruksi generik sepertiAGENTS.md,, CLAUDE.md atau. GEMINI.md

Kiro CLI

Tempatkan folder keterampilan di .kiro/skills/agentcore-eval-diagnostic/ dalam proyek Anda, atau di ~/.kiro/skills/agentcore-eval-diagnostic/ untuk membuatnya tersedia di semua ruang kerja. Untuk detail penyiapan, lihat dokumentasi keterampilan CLI Kiro.

Kode Claude

Tempatkan folder keterampilan di .claude/skills/agentcore-eval-diagnostic/ dalam proyek Anda, atau di ~/.claude/skills/agentcore-eval-diagnostic/ untuk membuatnya tersedia di semua proyek. Untuk detail penyiapan, lihat dokumentasi keterampilan Kode Claude.

OpenAI Codex CLI

Tempatkan folder keterampilan di .agents/skills/agentcore-eval-diagnostic/ dalam repositori Anda, atau di ~/.agents/skills/agentcore-eval-diagnostic/ untuk membuatnya tersedia di semua repositori. Untuk detail penyiapan, lihat dokumentasi keterampilan Codex CLI.

Kursor

Kursor menggunakan Aturan bukan keterampilan. Simpan konten keterampilan sebagai aturan proyek di.cursor/rules/agentcore-eval-diagnostic.md. Untuk detail penyiapan, lihat dokumentasi Aturan Kursor.

Gemini CLI

Tempatkan folder keterampilan ~/.gemini/skills/agentcore-eval-diagnostic/ untuk membuatnya tersedia di semua ruang kerja, atau di direktori keterampilan proyek Anda untuk penggunaan cakupan proyek. Untuk detail penyiapan, lihat dokumentasi keterampilan CLI Gemini.

Asisten AI lainnya

Jika asisten Anda mendukung standar Keterampilan Agen, letakkan folder keterampilan di direktori yang digunakan asisten Anda untuk menemukan keterampilan. Jika asisten Anda tidak mendukung Keterampilan Agen, muat keterampilan dengan menempelkan konten SKILL.md ke prompt sistem, pesan pengguna, atau file konteks. Keterampilan ini mandiri dan tidak bergantung pada fitur khusus alat apa pun.

Jalankan diagnosis

Setelah memuat keterampilan, mulai obrolan baru dengan asisten AI Anda dan berikan:

  1. AWS Wilayah Anda (misalnya,us-west-2).

  2. Jenis penerapan Anda — agentcore-runtime jika agen Anda diterapkan pada AgentCore Runtime, atau 3p-managed jika agen Anda di-host di Amazon ECS, Amazon EKS, AWS Lambda, atau lingkungan non-lingkungan lainnya. AgentCore

  3. Jenis evaluasi Anda — online (menggunakan konfigurasi evaluasi dengan sampling) atau on-demand (panggilan API Evaluasi langsung).

  4. Secara opsional, ID sesi dari agen Anda melacak (session.idatribut). Jika Anda tidak memilikinya, asisten dapat secara otomatis menemukan sesi terbaru dari grup log Anda.

Asisten menanyakan grup CloudWatch log Anda, mengidentifikasi akar penyebab kegagalan, dan menghasilkan laporan diagnostik terstruktur. Laporan tersebut meliputi:

  • Ringkasan akar penyebabnya.

  • Tabel temuan yang menunjukkan pemeriksaan diagnostik mana yang lulus atau gagal.

  • Daftar rentang dan peristiwa yang terpengaruh.

  • Tautan ke AWS dokumentasi yang relevan.

  • Direkomendasikan langkah selanjutnya.

Asisten menjalankan semua kueri di AWS akun Anda sendiri terhadap grup CloudWatch log Anda sendiri. Itu tidak mengakses log AWS sisi layanan atau data internal apa pun.

Contoh interaksi

Anda: Wilayah Saya adalahus-west-2, saya menggunakan AgentCore Runtime dengan evaluasi online, dan ID sesi saya adalahmy-session-abc123. Evaluasi saya tidak membuahkan hasil. Bisakah Anda mendiagnosisnya?

Asisten AI: 

## AgentCore Evaluation Diagnostic Report

Session: my-session-abc123
Region: us-west-2

Summary: Service name mismatch — spans are emitted under
'my_agent.DEFAULT' but the evaluation configuration expects
'wrong_name.DEFAULT'.

Findings:
| Check                | Status | Details |
| -------------------- | ------ | ------- |
| Eval config status   | OK     | ENABLED, 100% sampling |
| Spans found          | OK     | 15 spans for this session |
| Scope support        | OK     | strands.telemetry.tracer found |
| Service name match   | FAIL   | Config expects wrong_name.DEFAULT |

Recommended fix: Update the evaluation configuration's serviceNames to
match 'my_agent.DEFAULT'.

Memecahkan masalah keterampilan itu sendiri

Jika asisten tidak dapat menanyakan grup log Anda, periksa apakah:

  • AWS Kredensil Anda memiliki izin yang diperlukan.

  • Wilayah yang Anda berikan cocok dengan tempat agen Anda ditempatkan.

  • ID sesi sudah benar (salin dari jejak agen Anda).

  • Agen telah dipanggil dalam 24 jam terakhir.

Topik