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 tidak” MMDSv2-enabled ValidationException

Ketika ini terjadi: Saat menjalankan runtime agen melaluiInvokeAgentRuntime,,, ExecuteCommandInvokeAgentRuntimeWithWebSocketStream, InvokeAgentRuntimeCommandShell atau GetAgentCard

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

Solusi: Panggil UpdateAgentRuntimedengan requireMMDSV2 disetel 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: Entah login ke ECR Public atau logout 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 menjalankan Amazon Bedrock AgentCore API menggunakan boto3 SDK

Mengapa ini terjadi: Pustaka boto3 usang — masalah umum karena sebagian besar instalasi tidak memiliki SDK terbaru

Solusi: Perbarui ke versi boto3 dan botocore terbaru:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

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

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

Mengapa ini terjadi: Entah 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 kontainer untuk penyebaran Amazon Bedrock AgentCore

Mengapa ini terjadi: Membangun kontainer ARM64 pada sistem x86 tanpa pengaturan lintas platform yang tepat

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

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

Tinjau persyaratan Amazon Bedrock AgentCore Runtime untuk detail selengkapnya.

Singkatnya, wadah Docker Anda harus memenuhi persyaratan ini:

Alat saya yang sudah lama berjalan terganggu setelah 15 menit

Untuk selengkapnya, lihat Menangani agen asinkron dan berjalan lama dengan Amazon Bedrock Amazon Bedrock Runtime untuk detail selengkapnya. AgentCore

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 diperlakukan sebagai Healthy tidak memenuhi syarat dan waktu idle diukur dari saat yang 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 kustom, pastikan ping handler Anda kembali HealthyBusy saat memproses.

Sesi idle saya tidak dirilis dan kuota sesi saya habis

Ketika ini terjadi: Jumlah sesi naik terus menerus di bawah pemuatan dan sesi tidak dirilis setelah batas waktu idle (misalnya,ServiceQuotaExceededException/maxVmskesalahan selama ledakan pemanggilan), meskipun setiap sesi menganggur.

Mengapa ini terjadi: Ketika sesi melaporkanHealthy, platform mengukur berapa lama sesi telah menganggur dari time_of_last_update lapangan dalam /ping respons Anda, yang harus mencerminkan kapan yang status terakhir berubah. Jika penangan ping Anda menyetel time_of_last_update ke waktu saat ini pada setiap ping, waktu idle yang dilaporkan akan terus mengatur ulang, yang mencegah waktu tunggu idle diaktifkan. Sesi kemudian hidup sampai MaxLifetime dan dapat menghabiskan kuota sesi Anda.

Solusi: Perbarui time_of_last_update hanya ketika status benar-benar berubah, atau hilangkan sepenuhnya sehingga platform melacak perubahan statusnya sendiri:

{"status": "Healthy"}

Jika Anda menggunakan Bedrock AgentCore SDK, tingkatkan ke versi terbaru, di mana respons ping ditangani dengan benar. Sebagai pengganti sementara, memanggil StopRuntimeSession rilis macet sesi.

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

Jika 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 kustom

ID sesi runtime diteruskan di header HTTP ini. Parse dari permintaan yang 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 untuk memanggil runtime agen Anda.

Penyebab

Kesalahan ini biasanya terjadi karena:

Resolusi

Ikuti langkah-langkah ini untuk mengatasi masalah:

Saya memiliki CloudWatch Log yang hilang atau kosong

Masalah

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

Solusi

Cobalah pendekatan ini untuk mendiagnosis masalah ini:

Saya memiliki masalah format payload

Masalah

Pemanggilan runtime agen Anda gagal meskipun penampung berhasil dimulai.

Resolusi

Ikuti langkah-langkah ini 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 payloads

Pastikan konsistensi antar lingkungan:

Saya butuh bantuan men-debug masalah wadah

Jika Anda mencurigai masalah terkait kontainer:

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 keluaran kontainer 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 tambahan

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 tersebut sampai sesi berakhir, bahkan ketika aset kode diperbarui sebagai bagian dari melakukan UpdateAgentRuntimeoperasi.

Solusi

Untuk mengakses kode yang diperbarui, gunakan ID sesi baru.

Rentang hilang saat runtime saya dipanggil dari fungsi Lambda

Ketika ini terjadi: Saat menjalankan AgentCore Runtime dari fungsi Lambda

Mengapa ini terjadi: Lambda menghasilkan tajuknya sendiriX-Amzn-Trace-Id. Jika jejak Lambda memilikiSampled=0, konteks tanpa sampel ini menyebar ke AgentCore Runtime dan runtime melewatkan pembuatan rentang untuk pemanggilan itu.

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: Peran eksekusi tidak memiliki izin sistem file yang diperlukan. Untuk informasi selengkapnya tentang mengonfigurasi penyimpanan persisten, lihat Konfigurasi sistem berkas 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>"
    }
  }
}

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

Waktu pemasangan File S3 atau EFS saya habis

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

Mengapa ini terjadi: Konfigurasi 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 dipasang

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

Mengapa ini terjadi: Entah peran IAM tidak memiliki izin tulis, atau izin POSIX pada direktori yang disetel 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: InvokeAgentRuntime Panggilan Anda mengembalikan HTTP 424 (Ketergantungan Gagal) dan log agen Anda ditampilkan. Failed 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, USER myuser bukan). USER 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 ini:

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

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:

Pantau kinerja

Siapkan pemantauan untuk agen Anda: