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

Memecahkan masalah AgentCore Runtime

Topik pemecahan masalah ini membantu Anda mengidentifikasi dan menyelesaikan masalah umum saat bekerja dengan AgentCore Runtime. Dengan mengikuti solusi ini, Anda dapat dengan cepat mendiagnosis dan memperbaiki masalah dengan runtime agen Anda.

Pemanggilan agen saya gagal dengan “Runtime ini bukan" MMDSv2-enabled ValidationException

Ketika ini terjadi: Saat memanggil runtime agen melaluiInvokeAgentRuntime,,ExecuteCommand, InvokeAgentRuntimeWithWebSocketStreamInvokeAgentRuntimeCommandShell, atau GetAgentCard

Mengapa ini terjadi: Mulai 30 Juni 2026, Amazon Bedrock Runtime mengharuskan semua AgentCore runtime agen menggunakan mmDSv2 (MicroVM Metadata Service Version 2). Layanan menolak pemanggilan yang menargetkan runtime tanpa metadataConfiguration set, atau dengan disetel ke requireMMDSV2 atau. false null

Solusi: Pang gil UpdateAgentRuntime dengan dis requireMMDSV2 etel ke true dalammetadataConfiguration:

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

Setelah Anda memperbarui, pemanggilan baru akan berhasil. Sesi yang ada tidak terpengaruh.

Pemanggilan agen saya gagal dengan kesalahan 504 Gateway Timeout

Ketika ini terjadi: Selama pemanggilan agen melalui SDK atau konsol

Mengapa ini terjadi: Beberapa faktor dapat mencegah agen Anda merespons dalam periode batas waktu

Beberapa faktor dapat menyebabkan ini:

Build Docker saya gagal dengan “403 Forbidden” saat menarik gambar dasar Python

Ketika ini terjadi: Selama docker build atau docker run saat menggunakan gambar public.ecr.aws dasar

Mengapa ini terjadi: Masalah otentikasi publik ECR - otentikasi kedaluwarsa atau hilang adalah masalah umum.

Solusi: Login ke ECR Public atau keluar sepenuhnya:

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

Saya mendapatkan kesalahan “Layanan tidak dikenal: 'bedrock-agent-core-runtime'” saat menggunakan boto3

Ketika ini terjadi: Saat memanggil AgentCore API Amazon Bedrock menggunakan boto3 SDK

Mengapa ini terjadi: P ustaka boto3 usang - masalah umum karena sebagian besar instalasi tidak memiliki SDK terbaru

Solusi: Per barui ke versi boto3 dan botocore terbaru:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Saya mendapatkan "AccessDeniedException" ketika mencoba membuat Amazon Bedrock Runtime AgentCore

Ketika ini terjadi: Selama pembuatan agen melalui konsol, SDK, atau CLI

Mengapa ini terjadi: Pengguna Anda tidak memiliki izin, atau peran eksekusi tidak dikonfigurasi dengan benar untuk Amazon Bedrock AgentCore

Solusi: Beberapa faktor dapat menyebabkan ini:

Build Docker saya gagal dengan “exec/bin/sh: exec format error”

Ketika ini terjadi: Saat membangun wadah untuk penyebaran Amazon Bedrock AgentCore

Mengapa ini terjadi: Mem bangun wadah ARM64 pada sistem x86 tanpa pengaturan lintas platform yang tepat

Solusi: Bangun wadah yang kompatibel dengan ARM64. Anda dapat mempertimbangkan untuk menggunakan buildx untuk build lintas platform. Atau, Anda dapat menggunakan CodeBuild. Misalnya kode, lihat Sampel Amazon Bedrock AgentCore .

Apa persyaratan untuk wadah Docker yang digunakan dengan Amazon Bedrock AgentCore Runtime?

Tinjau persyaratan AgentCore Runtime Amazon Bedrock untuk detail selengkapnya.

Singkatnya, wadah Docker Anda harus memenuhi persyaratan ini:

Alat saya yang berjalan lama terganggu setelah 15 menit

Untuk informasi, lihat Men angani agen asinkron dan yang berjalan lama dengan Amazon Bedrock AgentCore Runtime untuk detail selengkapnya.

Ketika ini terjadi: Selama operasi agen yang berjalan lama atau alur kerja yang kompleks

Mengapa ini terjadi: Amazon Bedrock AgentCore secara otomatis menghentikan sesi setelah 15 menit tidak aktif. Platform menentukan aktivitas dari /ping respons: pelaporan HealthyBusy sesi tetap hidup, sementara pelaporan sesi Healthy diperlakukan sebagai memenuhi syarat idle dan waktu siangnya diukur dari saat status terakhir diubah (lihat time_of_last_update bidang di bawah).

Solusi: Pastikan /ping titik akhir Anda kembali HealthyBusy saat pekerjaan latar belakang sedang berlangsung:

{"status": "HealthyBusy"}

Jika Anda menggunakan Bedrock AgentCore SDK, respons ping ditangani secara otomatis. Untuk implementasi khusus, pastikan ping handler Anda kembali HealthyBusy saat memproses.

Sesi idle saya tidak dirilis dan saya menghabiskan kuota sesi saya

Ketika ini terjadi: Jumlah sesi naik terus menerus di bawah beban dan sesi tidak dilepaskan setelah batas waktu idle (misalnya,ServiceQuotaExceededException/maxVmserror selama ledakan pemanggilan), meskipun setiap sesi tidak aktif.

Mengapa ini terjadi: Ketika sesi melaporkanHealthy, platform mengukur berapa lama telah menganggur dari time_of_last_update lapangan dalam /ping tanggapan Anda, yang harus mencerminkan kapan status terakhir diubah. Jika pengendali ping Anda menyetel time_of_last_update ke waktu saat ini pada setiap ping, waktu idle yang dilaporkan terus disetel ulang, yang mencegah batas waktu idle diaktifkan. Sesi kemudian ditayangkan sampai MaxLifetime dan dapat menghabiskan kuota sesi Anda.

Solusi: Perbarui time_of_last_update hanya ketika status benar-benar berubah, atau hilangkan seluruhnya sehingga platform melacak perubahan status dengan sendirinya:

{"status": "Healthy"}

Jika Anda menggunakan Bedrock AgentCore SDK, tingkatkan ke versi terbaru, di mana respons ping ditangani dengan benar. Sebagai penghalang, panggilan mer StopRuntimeSession ilis sesi macet.

Bagaimana cara mengakses runtime SessionId dalam kode agen saya untuk memberi tag atau mengelompokkan sumber daya?

Bila ini berlaku: Anda ingin mengelompokkan, menandai, atau melacak sumber daya (misalnya, objek S3, log) dengan sesi runtime agen saat ini.

Solusi:

Solusi 1: Untuk agen yang menggunakan Bedrock Amazon Bedrock AgentCore SDK, gunakan context.session_id dari titik masuk agen Anda

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

Solusi 2: Untuk server HTTP runtime khusus

ID sesi runtime diteruskan di header HTTP ini. Parsi dari permintaan masuk dan gunakan untuk penandaan, korelasi, atau propagasi hilir.

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

Saya memiliki RuntimeClientError (403) masalah

Masalah

Anda menerima 403 "RuntimeClientError" ketika mencoba memanggil runtime agen Anda.

Penyebab

Kesalahan ini biasanya terjadi karena:

Resolusi

Ikuti langkah-langkah berikut untuk mengatasi masalah ini:

Saya memiliki Log yang hilang atau kosong CloudWatch

Masalah

Anda mengalami kesalahan tetapi tidak melihat log masuk yang relevan CloudWatch.

Solusi

Coba pendekatan ini untuk mendiagnosis masalah:

Saya memiliki masalah format payload

Masalah

Pemanggilan runtime agen Anda gagal meskipun kontainer berhasil dimulai.

Resolusi

Ikuti langkah-langkah berikut untuk mengatasi masalah format payload:

Saya butuh bantuan untuk memahami kode kesalahan HTTP

Masalah

Agen Anda mengembalikan kode kesalahan HTTP yang sulit ditafsirkan.

Contoh pesan kesalahan

Anda mungkin melihat kesalahan seperti:

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

Resolusi

Berikut adalah kode kesalahan yang paling umum dan artinya:

Saya perlu rekomendasi untuk menguji agen saya

Untuk men-debug masalah runtime agen secara sistematis:

Uji secara lokal terlebih dahulu

Sebelum menerapkan ke AgentCore Runtime:

Bandingkan muatan

Pastikan konsistensi antar lingkungan:

Saya butuh bantuan untuk men-debug masalah wadah

Jika Anda mencurigai masalah terkait wadah:

Tarik dan jalankan secara lokal

Uji gambar kontainer Anda di mesin lokal Anda:

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

Uji dengan ikal

Kirim permintaan pengujian ke wadah lokal Anda:

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

Periksa log kontainer

Periksa output wadah untuk kesalahan:

docker logs <container-id>

Saya butuh bantuan pemecahan masalah agen protokol MCP

Untuk agen protokol MCP, ikuti langkah-langkah pemecahan masalah khusus ini:

Verifikasi jalur titik akhir

Server MCP harus mendengarkan 0.0.0.0:8000/mcp/

Gunakan MCP Inspector

Uji dengan alat MCP Inspector:

Masalah otentikasi

Periksa konfigurasi otentikasi:

Saya butuh bantuan untuk memecahkan masalah streaming dua arah menggunakan WebSocket

Untuk streaming dua arah menggunakan WebSocket agen, ikuti langkah-langkah pemecahan masalah khusus ini:

Verifikasi konfigurasi titik akhir

WebSocket agen harus berjalan di port 8080 dan melayani WebSocket koneksi di jalur /ws

Uji secara lokal dengan kompleksitas inkremental

Mulailah dengan pengujian lokal sederhana sebelum menerapkan:

Masalah otentikasi

Periksa konfigurasi otentikasi untuk agen yang digunakan:

Masalah koneksi umum

Mengatasi masalah WebSocket koneksi umum:

Perubahan kode saya tidak tercermin dalam sesi yang ada

Masalah

Anda telah memperbarui runtime agen Anda dengan kode baru, tetapi sesi yang ada terus menggunakan versi lama.

Mengapa ini terjadi

Setiap sesi MicroVM dibuat dengan aset kode (agentRuntimeArtifact) yang digunakan pada saat pembuatan sesi. Setelah sesi dibuat, ia terus menggunakan versi kode itu sampai sesi berakhir, bahkan ketika aset kode diperbarui sebagai bagian dari melakukan UpdateAgentRuntime operasi.

Solusi

Untuk mengakses kode yang diperbarui, gunakan ID sesi baru.

Rentang hilang ketika runtime saya dipanggil dari fungsi Lambda

Ketika ini terjadi: Saat memanggil AgentCore Runtime dari fungsi Lambda

Mengapa ini terjadi: Lambda menghasilkan X-Amzn-Trace-Id header sendiri. Jika jejak Lambda memilikiSampled=0, konteks yang tidak disampel ini menyebar ke AgentCore Runtime dan runtime melewatkan pembuatan rentang untuk pemanggilan tersebut.

Solusi:

File S3 atau pemasangan EFS saya gagal dengan “Akses ditolak”

Ketika ini terjadi: Selama pemanggilan agen dengan File S3 atau penyimpanan EFS dikonfigurasi

Mengapa ini terjadi: Per an eksekusi tidak memiliki izin sistem file yang diperlukan. Untuk informasi selengkapnya tentang mengonfigurasi penyimpanan persisten, lihat Konfigurasi sistem file untuk AgentCore Runtime.

Solusi:

Untuk File S3, pastikan peran eksekusi Anda memiliki:

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Untuk EFS, pastikan peran eksekusi Anda memiliki:

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Hilangkan s3files:ClientWrite atau elasticfilesystem:ClientWrite jika agen Anda hanya membutuhkan akses baca.

File S3 atau pemasangan EFS saya gagal dengan "ResourceNotFound”

Ketika ini terjadi: Selama pemanggilan agen dengan File S3 atau penyimpanan EFS dikonfigurasi

Mengapa ini terjadi: Sistem file atau titik akses dihapus setelah agen dibuat, atau ID salah.

Solusi:

File S3 atau EFS saya habis waktu pemasangan

Ketika ini terjadi: Selama pemanggilan agen dengan File S3 atau penyimpanan EFS dikonfigurasi. Pemanggilan mungkin memakan waktu lebih lama dari biasanya sebelum gagal.

Mengapa ini terjadi: Konfigur asi jaringan VPC memblokir lalu lintas NFS (port 2049) antara komputasi agen dan target pemasangan sistem file.

Solusi:

Saya mendapatkan “Izin Ditolak” saat menulis ke sistem file saya yang terpasang

Ketika ini terjadi: Pem anggilan agen berhasil dan agen dapat membaca file dari mount, tetapi penulisan gagal dengan “Izin ditolak”

Mengapa ini terjadi: Peran IAM tidak memiliki izin menulis, atau izin POSIX pada direktori yang ditetapkan selama pembuatan titik akses tidak mengizinkan penulisan untuk pengguna agen.

Solusi:

Wadah saya gagal memulai dengan kesalahan HTTP 424 pada gambar lapisan tinggi

Ketika ini terjadi: Pang InvokeAgentRuntime gilan Anda mengembalikan HTTP 424 (Ketergantungan Gagal) dan log agen Anda ditampilkanFailed to mount overlay: No such file or directory. Ini terjadi ketika gambar kontainer Anda memiliki lebih dari 53 lapisan DAN menggunakan direktif USER non-numerik (misalnya, al USER myuser ih-alihUSER 1000).

Mengapa ini terjadi: Gambar kontainer dengan banyak lapisan yang dikombinasikan dengan arahan USER non-numerik dapat menyebabkan kegagalan inisialisasi.

Solusi: Gunakan salah satu solusi berikut:

docker inspect <image> | jq '.[0].RootFS.Layers | length'

Penyedia kapasitas saya dalam status CREATE_FAILED

Ketika ini terjadi: Setelah Anda memang CreateCapacityProvider gil jenis komputasi Instans, penyedia kapasitas tidak mencapai ACTIVE dan malah masukCREATE_FAILED.

Mengapa hal ini terjadi: Penyedia kapasitas bergantung pada beberapa sumber daya (seperti template peluncuran dan grup Penskalaan Otomatis) yang harus dapat dibuat oleh peran operator penyedia kapasitas. Kehilangan izin pada peran itu menyebabkan kegagalan pembuatan.

Solusi: Pang GetCapacityProvider gil API untuk mengambil alasan kegagalan di statusReason lapangan. statusReasonIdentifikasi sumber daya yang gagal dibuat. Berikan peran operator penyedia kapasitas izin yang diperlukan untuk membuat sumber daya tersebut, lalu buat penyedia kapasitas lagi. Untuk informasi selengkapnya tentang peran operator, lihat Model keamanan dan izin untuk Instans Runtime.

Agen saya di Instans tidak memiliki akses ke kredensialnya

Ketika ini terjadi: Agen yang berjalan pada sesi Instans tidak dapat memperoleh kredenSIAL yang diperlukan untuk memanggil AWS layanan.

Mengapa ini terjadi: Per an eksekusi runtime hilang atau tidak dapat diasumsikan oleh AgentCore.

Solusi: Pastikan peran eksekusi yang Anda konfigurasikan untuk runtime Anda ada dan memungkinkan bedrock-agentcore.amazonaws.com untuk memanggilsts:AssumeRole. Untuk informasi selengkapnya, lihat izin untuk peran eksekusi Amazon Bedrock AgentCore Runtime.

Praktik terbaik

Aktifkan pencatatan komprehensif

Terapkan logging menyeluruh di agen Anda:

Gunakan penanganan kesalahan terstruktur

Menerapkan pelaporan kesalahan yang jelas:

Uji perubahan inkremental

Ikuti pendekatan pengujian metodis:

Memantau kinerja

Siapkan pemantauan untuk agen Anda: