View a markdown version of this page

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

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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.

Keterampilan ini adalah file penurunan harga yang berfungsi dengan asisten pengkodean AI apa pun. Anda memuatnya ke asisten Anda, memberikan Wil AWS ayah, jenis penerapan, dan secara opsional ID sesi, 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 penyebabnya dan merekomendasikan perbaikan.

Apa yang didiagnosis keterampilan

Keterampilan ini mencakup masalah evaluasi yang paling umum:

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

  • LogEventMissingException— evaluasi melaporkan bahwa suatu rentang kehilangan peristiwa log yang sesuai.

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

  • SpanEventParsingException— evaluasi tidak dapat mengurai tubuh acara.

  • Gateway Timeout (504)- waktu evaluasi habis.

  • ValidationExceptionaktif evaluatorId — format ID evaluator salah.

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

Prasyarat

  • AWS CLI dikonfigurasi dengan kredenSIAL untuk akun tempat agen berjalan. KredenSIAL 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 AWS CLI secara langsung.

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

  • Agen yang telah dipanggil setidaknya sekali dengan pengamatan diaktifkan.

Salin keterampilan

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

Keterampilan 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 umum sepertiAGENTS.md,CLAUDE.md, atauGEMINI.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 Kiro CLI.

Kode Claude

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

OpenAI Codex CLI

Tempatkan folder keterampilan .agents/skills/agentcore-eval-diagnostic/ di 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 alih-alih 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 di ~/.gemini/skills/agentcore-eval-diagnostic/ untuk membuatnya tersedia di semua ruang kerja, atau di direktori keterampilan proyek Anda untuk penggunaan dalam cakupan proyek. Untuk detail penyiapan, lihat dokumentasi keterampilan Gemini CLI.

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 dalam prompt sistem, pesan pengguna, atau file konteks. Keterampilan ini mandiri dan tidak bergantung pada fitur khusus alat apa pun.

Jalankan diagnosis

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

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

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

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

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

Asisten menanyakan CloudWatch grup 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.

  • Langkah selanjutnya yang disarankan.

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 menghasilkan 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:

  • Kre AWS densibilitas 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