Memulai dengan AgentCore CLI

Quickstart ini membawa Anda dari nol ke agen yang sedang berjalan dalam beberapa menit menggunakan AgentCore CLI. Anda akan menginstal CLI, menyusun proyek, menguji secara lokal, menerapkan ke AWS, dan memanggil agen Anda.

Dua cara untuk membangun agen di AgentCore, CLI yang sama:

• Harness yang dikelola. Anda mendeklarasikan agen dalam file konfigurasi (model, prompt, alat, memori) dan AgentCore menjalankan loop untuk Anda. Tidak ada kerangka kerja, tidak ada kode orkestrasi. Jalur yang bagus ketika Anda menginginkan rute tercepat dari ide ke agen yang sedang berjalan. Pelajari selengkapnya.

• Code-based agen. Anda menulis loop agen di Python menggunakan kerangka kerja yang sudah Anda ketahui (Strands,, Google ADK LangGraph, atau OpenAI Agents), dan menyebarkannya ke AgentCore Runtime. Kontrol penuh atas logika orkestrasi.

Halaman ini berjalan melalui alur berbasis kode. Untuk harness, lihat Apa itu AgentCore harness.

Mendaftar untuk AWS akun

Mendaftar untuk AWS akun

Untuk memulainya AWS, Anda memerlukan AWS akun. Untuk informasi tentang membuat AWS akun, lihat Memulai dengan AWS akun di Panduan Referensi Manajemen AWS Akun.

Prasyarat

• Node.js 20 atau lebih. AgentCore CLI didistribusikan sebagai paket npm. Periksa dengannode --version. Instal dari nodejs.org jika diperlukan.

• npm. Termasuk dengan Node.js.

• AWS Akun dengan kredenSIAL dikonfigurasi. Konfigurasikan melalui AWS CLI, variabel lingkungan, atau AWS profil. Lihat Meng onfigurasi AWS CLI.

• Python 3.10 atau yang lebih baru (untuk kode agen). Periksa denganpython3 --version.

• Izin IAM. Identitas Anda memerlukan izin untuk melakukan panggilan AgentCore API dan untuk mengambil peran bootstrap CDK yang digunakan selama penerapan. Lihat Menggunakan AgentCore CLI.

• Akses model. Amazon Bedrock memungkinkan akses ke model pondasi secara default. Model yang tersedia termasuk Amazon Nova, Anthropic Claude, Meta Llama, dan model AI Mistral. Untuk menggunakan model non-pondasi, ikuti langkah-langkah akses model.

• Pelabuhan. Diperlukan hanya jika Anda memilih jenis Container build. Jenis CodeZip build default tidak memerlukan Docker.

Langkah 1: Instal AgentCore CLI

npm install -g @aws/agentcore

Verifikasi:

agentcore --version

catatan

Jika ini melaporkan kesalahan alih-alih nomor versi, agentcore perintah Python yang lebih lama membayangi yang npm di Anda. PATH Ini terjadi jika Anda sebelumnya menginstal paket bedrock-agentcore-starter-toolkit pip, dan paling umum di Windows. J pip uninstall bedrock-agentcore-starter-toolkit alankan, lalu buka terminal baru dan coba lagi.

Untuk memperbarui nanti, jalankan kembali perintah install atauagentcore update. Sumber dan masalah: agentcore-cli aktif. GitHub

Langkah 2: Buat proyek Anda

agentcore create

Wizard interaktif pertama-tama menanyakan apa yang ingin Anda buat:

• Harness - Loop agen berbasis konfigurasi terkelola. Tidak diperlukan kerangka kerja atau kode orkestrasi. Lihat Apa itu AgentCore harness.

• Agen - Agen berbasis kode menggunakan kerangka kerja yang Anda pilih, diterapkan ke AgentCore Runtime.

• Lewati - Buat struktur proyek tanpa agen. Tambahkan satu nanti denganagentcore add.

Jika Anda memilih Agen, wizard melanjutkan dengan:

• Kerangka kerja - Strands Agents (disarankan) LangChain/LangGraph, Kit Pengembangan Agen Google, atau OpenAI Agents SDK

• Penyedia model - Amazon Bedrock, Anthropic, OpenAI, atau Gemini

• Memori - Tidak ada, hanya jangka pendek, atau jangka panjang dan jangka pendek

• Jenis build - CodeZip (default) atau Wadah

Anda juga dapat meneruskan flag secara langsung untuk membuat agen berbasis kode:

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

Untuk semua perintah dan opsi yang tersedia, lihat referensi AgentCore CLI.

Jenis Bangun

• CodeZip(default) mengemas kode Anda dalam file zip dan mengunggahnya ke Amazon S3. Jenis build ini tidak memerlukan Docker.

• Containermembangun dan menyebarkan image kontainer. Jenis build ini membutuhkan daemon Docker yang sedang berjalan.

Struktur proyek

agentcore createmenghasilkan konfigurasi proyek bersama dan struktur aplikasi yang berbeda untuk agen dan harness berbasis kode:

contoh

Code-based agent

MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/

Harness

MyHarnessProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyHarness/
        ├── harness.json
        └── system-prompt.md

File kunci:

• agentcore/agentcore.json- File konfigurasi utama. Ini mendefinisikan agen Anda, harness, penyimpanan memori, gateway, kredenSIAL, dan sumber daya lainnya. Per agentcore add agentcore remove intah dan mengelola file ini.

• agentcore/aws-targets.json- AWS Akun dan Wilayah untuk penyebaran.

• agentcore/.env.local- Rahasia lokal, seperti kunci API untuk penyedia model.

• app/- Direktori aplikasi. Agen berbasis kode berisi titik masuk dan dependensi. Harness berisi harness.json dansystem-prompt.md.

Langkah 3: Uji secara lokal

cd MyProject
agentcore dev

agentcore devmembuat lingkungan virtual Python, menginstal dependensi, memulai server lokal dengan hot reload, dan membuka inspektur agen di browser Anda sehingga Anda dapat mengobrol dengan agen, memeriksa jejak, dan menelusuri sumber daya proyek. Perubahan kode diambil secara otomatis.

Langkah 4: Menyebarkan agen Anda

agentcore deploy

Menyebarkan:

1. Mengemas kode Anda ke dalam artefak zip (atau membangun wadah jika--build Container)

2. Menggunakan AWS CDK di bawah tenda untuk mensintesis dan menyediakan sumber daya

3. Membuat titik akhir AgentCore Runtime untuk agen Anda

4. Mengkonfigurasi pencatatan CloudWatch dan pengamatan

Penerapan pertama membutuhkan waktu beberapa menit sementara CDK mem-bootstrap akun Anda. Penerapan selanjutnya lebih cepat.

Pratinjau apa yang akan berubah tanpa menerapkan:

agentcore deploy --dry-run

Periksa status:

agentcore status

Langkah 5: Panggil agen yang Anda gunakan

agentcore invoke --prompt "Hello, what can you do?"

Jika agen Anda telah mengonfigurasi pembayaran, berikan konteks pembayaran pada waktu pemanggilan:

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id [e-mail]

Itulah putarannya. Iterasiapp/MyAgent/main.py, uji denganagentcore dev, terapkan denganagentcore deploy, panggil dengan. agentcore invoke

Memanggil agen secara terprogram

Anda dapat memanggil agen yang digunakan dengan InvokeAgentRuntime operasi AWS SDK. Dapatkan ARN runtime agen:

agentcore status

Buat file bernama invoke_agent.py. Ganti Agent ARN dengan ARN agen Anda:

import json
import uuid

import boto3

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

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode("utf-8"))

print(json.loads("".join(content)))

Jalankan kode:

python invoke_agent.py

Identitas Anda harus memiliki bedrock-agentcore:InvokeAgentRuntime izin.

catatan

Untuk agen yang menggunakan OAuth, buat permintaan HTTPS ke al InvokeAgentRuntime ih-alih menggunakan SDK. AWS Untuk informasi selengkapnya, lihat Meng autentikasi dan mengotorisasi dengan otorisasi masuk dan keluar.

Tambahkan kemampuan ke proyek Anda

agentcore addmengelola sumber daya diagentcore.json. Jalankan tanpa argumen untuk menu interaktif, atau targetkan sumber daya secara langsung.

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

Setiap perintah penambahan menancapkan konfigurasi dan meminta nilai yang diperlukan. Setelah menambahkan, jalankan agentcore deploy ke penyediaan.

Penyelaman mendalam untuk kemampuan yang dapat Anda lampirkan:

• AgentCore Memori - memori jangka pendek dan jangka panjang, strategi pengambilan

• AgentCore Gateway - konektivitas yang diatur ke API dan server MCP

• AgentCore Browser - penelusuran web terkelola untuk agen

• AgentCore Code Interpreter - eksekusi kode kotak pasir

• AgentCore Identitas - OAuth, penyedia kredensia kunci API, identitas beban kerja

• AgentCore Pengamatan - jejak, log, dan metrik di CloudWatch

• AgentCore VPC - jalankan agen di dalam VPC Anda

• AgentCore Pembay aran - pembayaran transaksi mikro untuk agen melalui x402

Lihat log dan jejak

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

Pemecahan Masalah

Kesalahan izin ditolak

Verifikasi kredensi Anda denganaws sts get-caller-identity. Pastikan identitas Anda memiliki izin di Gunakan AgentCore CLI.

Akses model ditolak

Amazon Bedrock memungkinkan akses ke model pondasi secara default. Untuk menggunakan model non-dasar, ikuti langkah-langkah akses model.

Kesalahan penerapan

Jalan agentcore deploy --verbose kan untuk menampilkan peristiwa penerapan tingkat sumber daya. CLI memeriksa status bootstrap AWS CDK. Jika bootstrap diperlukan, penerapan interaktif meminta konfirmasi. agentcore deploy --yesmenyetujui operasi bootstrap tanpa prompt.

Port sudah digunakan

Jalan agentcore dev --port 3000 kan untuk menggunakan port lokal yang berbeda.

Kesalahan validasi konfigurasi

J agentcore validate alankan untuk memeriksa konfigurasi proyek.

Untuk informasi selengkapnya, lihat Memec ahkan Masalah Amazon Bedrock AgentCore Runtime.

Bersihkan

agentcore remove all
agentcore deploy

remove allmengatur ulang konfigurasi. Tind deploy ak lanjut mendeteksi keadaan kosong dan merobek sumber daya di akun Anda.

Langkah selanjutnya

• Apa itu AgentCore harness - jalur berbasis konfigurasi ke agen yang sedang berjalan. Gunakan model apa pun, sambungkan ke alat, pertahankan status, terapkan di VPC Anda, dan lanjutkan ke kode saat Anda membutuhkannya.

• AgentCore contoh kode - contoh ujung ke ujung di seluruh kerangka kerja dan kemampuan.