Prasyarat Langkah 1: Instal AgentCore CLI Langkah 2: Buat proyek agen Anda Langkah 3: Uji agen Anda secara lokal Langkah 4: Aktifkan observabilitas untuk agen Anda Langkah 5: Terapkan ke Amazon Bedrock AgentCore Runtime Langkah 6: Uji agen yang Anda gunakan Langkah 7: Panggil agen Anda yang dikerahkan Langkah 8: Membersihkan Temukan sumber daya Anda Masalah dan solusi umum Opsi lanjutan (Opsional)

Memulai dengan AgentCore CLI

Tutorial ini menunjukkan cara menggunakan AgentCore CLI untuk membuat, menyebarkan, dan memanggil agen Python di Amazon Bedrock Runtime. AgentCore

AgentCore CLI adalah alat baris perintah yang memproyeksikan agen perancah, menerapkannya ke Amazon Bedrock Runtime, dan memanggilnya. AgentCore Anda dapat menggunakan CLI dengan kerangka kerja agen Python populer seperti Strands Agents, Google ADK LangChain/LangGraph, dan Agen OpenAI. Tutorial ini menggunakan Strands Agents.

Untuk informasi tentang protokol HTTP yang digunakan agen, lihat Kontrak protokol HTTP.

Topik

Prasyarat
Langkah 1: Instal AgentCore CLI
Langkah 2: Buat proyek agen Anda
Langkah 3: Uji agen Anda secara lokal
Langkah 4: Aktifkan observabilitas untuk agen Anda
Langkah 5: Terapkan ke Amazon Bedrock AgentCore Runtime
Langkah 6: Uji agen yang Anda gunakan
Langkah 7: Panggil agen Anda yang dikerahkan
Langkah 8: Membersihkan
Temukan sumber daya Anda
Masalah dan solusi umum
Opsi lanjutan (Opsional)

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

AWS Akun dengan kredensil dikonfigurasi. Untuk mengonfigurasi AWS kredensil Anda, lihat Konfigurasi dan pengaturan file kredenal di CLI. AWS
Node.js 20+ diinstal. AgentCore CLI didistribusikan sebagai paket npm.
Python 3.10+ diinstal. Kode agen yang dihasilkan adalah Python.
AWS CDK diinstal. CLI menggunakan AWS CDK untuk menyebarkan sumber daya. Untuk selengkapnya, lihat Memulai AWS CDK.
AWS Izin: Untuk membuat dan menyebarkan agen dengan AgentCore CLI, Anda harus memiliki izin yang sesuai. Untuk selengkapnya, lihat Menggunakan AgentCore CLI.
Akses model: Anthropic Claude Sonnet 4.0 diaktifkan di konsol Amazon Bedrock (jika menggunakan Bedrock sebagai penyedia model). Untuk informasi tentang penggunaan model yang berbeda dengan Agen Strands, lihat bagian Penyedia Model di dokumentasi Strands Agents SDK.

Langkah 1: Instal AgentCore CLI

Instal AgentCore CLI secara global:


npm install -g @aws/agentcore

Verifikasi instalasi:


agentcore --help

Anda akan melihat output yang serupa dengan yang berikut:


Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

Langkah 2: Buat proyek agen Anda

Gunakan agentcore create perintah untuk membuat perancah proyek agen baru:

contoh

agentcore createPerintah menerima bendera berikut:

--name— Nama proyek (alfanumerik, dimulai dengan huruf, maks 36 karakter).
--framework— Kerangka kerja agen. Nilai yang didukung:Strands,LangChain_LangGraph,GoogleADK,OpenAIAgents.
--protocol— Mode protokol. Nilai yang didukung: HTTP (default),MCP,A2A.
--build— Jenis build. Nilai yang didukung: CodeZip (default),Container.
--model-provider— Penyedia model. Nilai yang didukung:Bedrock,Anthropic,OpenAI,Gemini.
--memory— Konfigurasi memori. Nilai yang didukung:none,shortTerm,longAndShortTerm.

Perintah menghasilkan direktori proyek dengan struktur berikut:


MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

agentcore/agentcore.jsonFile tersebut berisi konfigurasi proyek dan agen Anda. app/MyAgent/main.pyFile berisi kode agen pemula menggunakan kerangka kerja yang Anda pilih.

Untuk menambahkan kemampuan pembayaran ke proyek Anda, jalankan:


agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

Ini mengonfigurasi AgentCorePaymentsPlugin di agen Anda dan menyediakan infrastruktur pembayaran saat digunakan. Lihat Pembayaran mulai cepat untuk alur kerja lengkapnya.

Langkah 3: Uji agen Anda secara lokal

Sebelum menerapkan ke AWS, uji agen Anda secara lokal menggunakan server pengembangan. Pertama, ubah ke direktori proyek:


cd MyAgent

Jika Anda memilih penyedia model yang memerlukan kunci API (OpenAI, Anthropic, atau Gemini), pastikan kunci tersebut dikonfigurasi. agentcore/.env.local

Mulai server pengembangan lokal:

contoh

agentcore devPerintah:

Membuka agen inspektur di browser web Anda
Secara otomatis membuat lingkungan virtual Python dan menginstal dependensi
Memulai server lokal yang meniru lingkungan AgentCore Runtime
Berjalan secara http://localhost:8080 default (gunakan -p untuk mengubah port)

Untuk melihat log server secara real time (mode non-interaktif), gunakan --logs bendera:


agentcore dev --logs

Di terminal terpisah, panggil agen lokal Anda:


agentcore dev "Hello, tell me a joke"

Melewati prompt mengirimkannya ke server pengembangan lokal yang sedang berjalan. Gunakan --stream untuk melihat respons dialirkan secara real time.

Langkah 4: Aktifkan observabilitas untuk agen Anda

Amazon Bedrock AgentCore Observability membantu Anda melacak, men-debug, dan memantau agen yang Anda host di Amazon Bedrock Runtime. AgentCore Pertama aktifkan Penelusuran CloudWatch Transaksi dengan mengikuti petunjuk di Mengaktifkan observabilitas AgentCore runtime Amazon Bedrock. Untuk mengamati agen Anda, lihat Melihat data observabilitas untuk agen Amazon Bedrock AgentCore Anda.

Setelah menerapkan agen, Anda dapat menggunakan AgentCore CLI untuk melakukan streaming log dan melihat jejak:


# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Langkah 5: Terapkan ke Amazon Bedrock AgentCore Runtime

Terapkan agen Anda ke Amazon Bedrock AgentCore Runtime:

contoh

Untuk melihat pratinjau penerapan tanpa membuat perubahan, gunakan --dry-run tanda:


agentcore deploy --dry-run

agentcore deployPerintah:

Membaca agentcore/agentcore.json dan agentcore/aws-targets.json konfigurasi
Mengemas kode agen Anda (sebagai CodeZip arsip atau wadah Docker, tergantung pada jenis build Anda)
Menggunakan AWS CDK untuk mensintesis dan menyebarkan sumber daya CloudFormation
Membuat AWS sumber daya yang diperlukan (peran IAM, Amazon Bedrock AgentCore Runtime, dll.)

Gunakan -v untuk keluaran verbose yang menunjukkan peristiwa penerapan tingkat sumber daya. Gunakan -y untuk mengonfirmasi penerapan secara otomatis tanpa prompt.

Jika penerapan gagal, periksa masalah umum.

Langkah 6: Uji agen yang Anda gunakan

Setelah penerapan selesai, panggil agen yang Anda gunakan:

contoh

Jika Anda melihat lelucon dalam tanggapan, agen Anda berjalan di Amazon Bedrock AgentCore Runtime dan dapat dipanggil. Jika tidak, periksa masalah umum.

Langkah 7: Panggil agen Anda yang dikerahkan

contoh

AgentCore CLI

Panggil agen yang Anda gunakan dengan prompt:
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
Streaming respons secara real time:
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
Jalankan agentcore invoke tanpa prompt untuk membuka obrolan interaktif TUI, yang mengalirkan respons secara default dan mempertahankan sesi Anda secara otomatis.

AWS Python SDK (Boto3)

Anda juga dapat memanggil agen menggunakan operasi AWS SDK InvokeAgentRuntime. Untuk mendapatkan ARN dari agen yang Anda gunakan, gunakan perintah: agentcore status
```
agentcore status
```
Gunakan kode boto3 (AWS SDK untuk Python) berikut untuk memanggil agen Anda. Ganti Agent ARN dengan ARN agen Anda. Pastikan Anda memiliki bedrock-agentcore:InvokeAgentRuntime izin. Buat file bernama invoke_agent.py dan tambahkan kode berikut:
```
import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))
```
Buka jendela terminal dan jalankan kode dengan perintah berikut:
```
python invoke_agent.py
```
Jika berhasil, Anda harus melihat lelucon dalam tanggapannya. Jika panggilan gagal, periksa log menggunakan agentcore logs atau melihatnya di Amazon CloudWatch.

catatan
Jika Anda berencana mengintegrasikan agen Anda dengan OAuth, Anda tidak dapat menggunakan AWS SDK untuk menelepon. InvokeAgentRuntime Sebagai gantinya, buat permintaan HTTPS keInvokeAgentRuntime. Untuk informasi selengkapnya, lihat Mengautentikasi dan mengotorisasi dengan Auth Masuk dan Auth Keluar.

Langkah 8: Membersihkan

Jika Anda tidak lagi ingin meng-host agen di Amazon Bedrock AgentCore Runtime, hapus sumber daya yang diterapkan AWS . Pertama, hapus semua sumber daya dari konfigurasi lokal Anda:

contoh

Kemudian gunakan lagi untuk merobohkan AWS sumber daya:

contoh

remove allPerintah me-reset file agentcore/agentcore.json konfigurasi sambil mempertahankan agentcore/aws-targets.json dan status penyebaran. Selanjutnya deploy mendeteksi sumber daya yang dihapus dan merobohkan sumber AWS daya yang sesuai.

Temukan sumber daya Anda

Setelah penerapan, Anda dapat memeriksa status sumber daya Anda dengan menggunakan AgentCore CLI:

contoh

Anda juga dapat melihat sumber daya Anda di AWS Konsol:

Sumber daya	Lokasi
Log Agen	CloudWatch → Grup log → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT`
CloudFormation Tumpukan	CloudFormation → Tumpukan → cari nama proyek Anda
Peran IAM	IAM → Peran → Cari "” BedrockAgentCore
Aset S3 () CodeZip	S3 → Ember → Ember pementasan CDK

Masalah dan solusi umum

Masalah dan solusi umum saat memulai dengan AgentCore CLI. Untuk informasi pemecahan masalah lainnya, lihat Memecahkan Masalah Amazon Bedrock Runtime. AgentCore

Izin ditolak kesalahan

Verifikasi AWS kredensil dan izin Anda:

Verifikasi AWS kredensil: aws sts get-caller-identity
Periksa Anda memiliki kebijakan yang diperlukan terlampir
Tinjau kebijakan izin pemanggil untuk persyaratan terperinci

Akses model ditolak

Aktifkan akses model di konsol Bedrock:

Aktifkan Anthropic Claude 4.0 di konsol Bedrock
Pastikan Anda berada di AWS Wilayah yang benar (us-west-2 secara default)

Kesalahan penerapan CDK

Periksa pengaturan dan izin CDK:

Pastikan Anda telah mem-bootstrap AWS akun Anda untuk CDK: cdk bootstrap
Verifikasi izin penelepon Anda termasuk CloudFormation dan akses CDK
Gunakan agentcore deploy -v untuk keluaran verbose untuk mengidentifikasi sumber daya yang gagal

Port 8080 digunakan (hanya lokal)

Temukan dan hentikan proses yang menggunakan port 8080:

Gunakan lsof -ti:8080 untuk mendapatkan daftar proses menggunakan port 8080.

Gunakan kill -9 PID untuk menghentikan proses. Ganti PID dengan ID proses.

Atau, mulai server dev pada port yang berbeda: agentcore dev -p 3000

Ketidakcocokan wilayah

Verifikasi AWS Wilayah dengan aws configure get region dan pastikan wilayah agentcore/aws-targets.json cocok dengan tempat sumber daya Anda harus digunakan.

Kesalahan validasi konfigurasi

Validasi file konfigurasi Anda:

Gunakan agentcore validate untuk memeriksa kesalahan sintaks atau skema dalam agentcore/agentcore.json dan file konfigurasi terkait.

Opsi lanjutan (Opsional)

Setelah membuat proyek agen Andaagentcore create, Anda dapat memperpanjangnya dengan menggunakan agentcore add perintah. Untuk referensi CLI lengkap, lihat dokumentasi CLIAgentCore .

Membangun jenis

Saat membuat proyek Anda, pilih jenis build yang sesuai dengan kebutuhan Anda:

CodeZip (default)

Kode agen Anda dikemas sebagai arsip zip dan diunggah ke S3. Ini adalah opsi paling sederhana dan tidak memerlukan Docker:


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip

Kontainer

Kode agen Anda dikemas sebagai image kontainer Docker. Gunakan opsi ini saat Anda membutuhkan dependensi tingkat sistem khusus atau gambar dasar tertentu:


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

Tambahkan sumber daya ke proyek Anda

Anda dapat menambahkan sumber daya tambahan ke proyek Anda setelah pembuatan:


# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

Setelah menambahkan sumber daya, jalankan agentcore deploy untuk menyediakan sumber daya baru di AWS.

Mengapa ARM64?

Amazon Bedrock AgentCore Runtime berjalan di ARM64 (AWS Graviton). AgentCore CLI menangani kompatibilitas arsitektur secara otomatis untuk tipe build CodeZip dan Container. Untuk build Container, hanya gambar yang dibuat untuk ARM64 yang akan berfungsi saat di-deploy ke Amazon Bedrock Runtime. AgentCore

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Memulai AgentCore Runtime

Memulai dengan AgentCore CLI () TypeScript

Memulai dengan AgentCore CLI

Topik

Prasyarat

Langkah 1: Instal AgentCore CLI

Langkah 2: Buat proyek agen Anda

contoh

Langkah 3: Uji agen Anda secara lokal

contoh

Langkah 4: Aktifkan observabilitas untuk agen Anda

Langkah 5: Terapkan ke Amazon Bedrock AgentCore Runtime

contoh

Langkah 6: Uji agen yang Anda gunakan

contoh

Langkah 7: Panggil agen Anda yang dikerahkan

contoh

catatan

Langkah 8: Membersihkan

contoh

contoh

Temukan sumber daya Anda

contoh

Masalah dan solusi umum

Opsi lanjutan (Opsional)

Membangun jenis

Tambahkan sumber daya ke proyek Anda

Mengapa ARM64?