Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Penyebaran kode langsung untuk Python
Dengan penyebaran kode langsung, Anda mengemas kode agen Python Anda dan dependensinya dalam arsip file.zip dan menyebarkannya ke AgentCore Waktu pelaksanaan. Agen Anda masih perlu mengikuti AgentCore Persyaratan runtime : memiliki file entrypoint .py yang menggunakan @app.entrypoint anotasi dari Batu Dasar Amazon AgentCore SDK Python atau mengimplementasikan /invocations POST dan /ping DAPATKAN titik akhir server.
Halaman ini berisi ringkas AgentCore Jalur CLI dan instruksi terperinci untuk mengemas dan menerapkan file.zip secara manual dengan uv, Boto3, atau AWS Konsol Manajemen. Untuk alur kerja CLI lengkap, lihat Memulai dengan AgentCore Runtime menggunakan AgentCore CLI.
Prasyarat
Sebelum memulai, pastikan Anda memiliki:
-
AWS Akun dengan kredenSIAL yang dikonfigurasi. Untuk mengonfigurasi AWS kredenSIAL, lihat Konfigurasi dan pengaturan file kredenSIAL di AWS CLI.
-
Uv terpasang dan Python 3.10+ terpasang
-
AWS Izin : Untuk membuat dan menyebarkan agen, Anda harus memiliki izin yang sesuai. Untuk informasi lebih lanjut, lihat AgentCore Izin runtime.
-
Akses model : Amazon Bedrock memungkinkan akses ke model pondasi secara default. Untuk menggunakan model non-pondasi, ikuti langkah-langkah akses model.
-
Agen Python yang ada dengan main.py titik masuk dan a pyproject.toml file yang menyatakan dependensinya.
Langkah 1: Siapkan dan uji agen Python Anda
Proyek Anda harus berisi file yang akan Anda tambahkan ke paket penerapan:
my-agent/
├── main.py
└── pyproject.toml
Jalankan agen secara lokal menggunakan perintah untuk aplikasi Anda. Untuk titik masuk yang memulai servernya dari main.py, jalankan:
uv run main.py
Di terminal lain, uji /invocations titik akhir:
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
Sukses: Anda harus melihat jawaban seperti {"result": "Hello! I’m here to help…"} . Di jendela terminal yang menjalankan agen, masukkan Ctrl+C untuk menghentikan agen.
Secara opsional, jalankan uv add aws-opentelemetry-distro untuk mengaktifkan Batu Dasar Amazon AgentCore jejak pengamatan.
Langkah 2: Aktifkan observabilitas untuk agen Anda
Batu Dasar Amazon AgentCore Pengamatan membantu Anda melacak, men-debug, dan memantau agen yang Anda host AgentCore Waktu pelaksanaan. Aktifkan pertama CloudWatch Pencarian Transaksi dengan mengikuti petunjuk di Mengaktifkan Amazon Bedrock AgentCore observabilitas runtime . Untuk mengamati agen Anda, lihat Lihat data pengamatan untuk Amazon Bedrock Anda AgentCore pelaku.
Langkah 3: Kemas, terapkan, dan panggil
Kemas dan terapkan agen Anda menggunakan salah satu metode berikut:
contoh
- AgentCore CLI
-
-
Untuk CLI-managed CodeZip proyek, AgentCore CLI mengemas dan menyebarkan proyek untuk Anda. Untuk menyebarkan agen Anda yang ada dengan AgentCore CLI, buat proyek dari template minimal:
agentcore create --name DirectDeployProject --template agent-python-minimal
cd DirectDeployProject
Salin Anda main.py dan pyproject.toml ke app/agent/, mengganti file yang dihasilkan. Kemudian terapkan proyek:
agentcore deploy
Secara opsional, jalankan agentcore build pertama untuk mensintesis dan memeriksa proyek tanpa menerapkan.
Memanggil Runtime yang digunakan:
agentcore invoke --runtime agent \
--payload '{"prompt":"Hello!"}'
Anda juga bisa berlari agentcore tanpa argumen untuk membuka UI terminal interaktif, lalu pilih menyebarkan untuk melihat kemajuan penerapan. Untuk pengujian lokal, lihat Memulai dengan AgentCore Runtime menggunakan AgentCore CLI.
- Boto3
-
-
Untuk mengunduh roda yang kompatibel dengan AgentCore Runtime, Anda menggunakan uv pip --python-platform pilihan. AgentCore Runtime hanya mendukung lengan64 arsitektur. Jalankan perintah berikut, dan ganti 3.13 di --python-version dengan versi Python Anda.
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
Buat file.zip dengan pustaka yang diinstal di root proyek.
cd deployment_package
zip -r ../deployment_package.zip .
Tambahkan main.py file dan file lain dalam paket Anda ke root file.zip.
cd ..
zip deployment_package.zip main.py
Setelah membuat paket penerapan.zip, Anda dapat menggunakannya untuk membuat paket baru AgentCore Runtime atau perbarui yang sudah ada. Anda dapat menerapkan paket.zip Anda menggunakan AgentCore Runtime API, AgentCore Konsol runtime, atau AWS Antarmuka Baris Perintah.
Ukuran maksimum untuk paket penerapan.zip untuk AgentCore Runtime adalah 250 MB (zip) dan 750 MB (unzip). Batas ini berlaku untuk ukuran gabungan semua file yang Anda unggah.
Yang AgentCore Runtime memerlukan izin untuk membaca file dalam paket penerapan Anda. Dalam notasi oktal izin Linux, AgentCore Runtime membutuhkan 644 izin untuk file yang tidak dapat dieksekusi (rw-r—r--) dan 755 izin (rwxr-xr-x) untuk direktori dan file yang dapat dieksekusi. Di Linux dan macOS, gunakan chmod perintah untuk mengubah izin file pada file dan direktori dalam paket penerapan Anda. Misalnya, untuk memberikan izin yang benar pada file yang tidak dapat dieksekusi, jalankan chmod 644 <filepath>. Untuk mengubah izin file di Windows, lihat Mengatur, Melihat, Mengubah, atau Hapus Izin pada Objek dalam dokumentasi Microsoft Windows. Jika Anda tidak memberikan AgentCore Jalankan izin yang diperlukan untuk mengakses direktori dalam paket penerapan Anda, AgentCore Runtime menetapkan izin untuk direktori tersebut ke 755 (rwxr-xr-x).
Arsip ZIP yang berisi Linux arm64 dependensi perlu diunggah ke S3 sebagai prasyarat untuk Membuat Agen Runtime. Kode di bawah ini membutuhkan bucket S3 yang ditentukan untuk sudah ada. Untuk membuat ember, lihat buat_bucket dalam dokumentasi Boto3. Kode boto3 berikut akan mengunggah arsip file.zip ke s3 dan membuat Amazon Bedrock AgentCore waktu pelaksanaan.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = agentcore_client.create_agent_runtime(
agentRuntimeName=agent_name,
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2",
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Untuk informasi selengkapnya tentang memanggil agen secara terprogram, lihat Memanggil agen streaming.
- AWS Management Console
-
Anda dapat menyebarkan agen Anda menggunakan Amazon Bedrock AgentCore konsol dengan dukungan runtime terkelola.
Untuk menerapkan menggunakan konsol, pertama-tama buat paket penerapan Anda mengikuti langkah-langkah di Pemberongan3 tab di atas.
Buat agen melalui konsol
Untuk membuat agen Anda:
-
Dari halaman beranda Agen, pilih Agen Tuan Rumah
-
Pilih pilihan sumber Anda:
-
Sumber S3 - Unggah dari bucket S3
-
Unggah Lokal - Unggah file ZIP dari komputer Anda
-
Templat - Gunakan templat agen yang sudah dibuat sebelumnya
-
Konfigurasikan setelan agen Anda:
-
Nama agen
-
Versi runtime (Python 3.13 disarankan)
-
Titik masuk (mis., main.py )
-
Peran eksekusi (buat baru atau gunakan yang sudah ada)
-
Memilih Buat Agen untuk menyebarkan
Buat titik akhir
Memilih Buat Titik Akhir untuk membuat titik akhir baru untuk agen Anda. Nama titik akhir dan versi terkait akan diisi sebelumnya.
Titik akhir pengujian
Pilih titik akhir dan pilih Titik Akhir Uji untuk menavigasi ke Playground/Sandbox untuk pengujian.
Persyaratan peran eksekusi
Agen Anda memerlukan peran eksekusi dengan izin yang sesuai. Untuk informasi terperinci tentang peran dan izin eksekusi, lihat AgentCore Izin runtime . Peran eksekusi harus mencakup dasar Amazon Bedrock AgentCore izin runtime, izin akses S3 untuk paket penerapan Anda, dan CloudWatch Izin mencatat untuk pengamatan.
Langkah 4: Menghentikan sesi, memperbarui, atau membersihkan
Hentikan sesi runtime Anda, perbarui, atau bersihkan agen Anda menggunakan salah satu metode berikut:
contoh
- AgentCore CLI
-
-
Terapkan proyek lagi untuk memperbarui Runtime:
agentcore deploy
Untuk menghapus sumber daya proyek yang digunakan, hapus sumber daya dari proyek dan gunakan konfigurasi yang diperbarui:
agentcore remove all --yes
agentcore deploy --yes
Untuk menghentikan sesi Runtime yang aktif, gunakan StopRuntimeSession Operasi API.
- Boto3
-
-
Mengikuti kode boto3 akan memperbarui AgentCore Waktu pelaksanaan.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = bedrock_agentcore_client.update_agent_runtime(
agentRuntimeId='<your-agent-id>',
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2"
)
print(f"Agent Runtime updated successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Untuk menghentikan sesi yang sedang berjalan sebelum dapat dikonfigurasi IdleRuntimeSessionTimeout (default pada 15 menit) dan hemat biaya potensial, gunakan kode boto3 berikut:
import boto3
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/agent-name-suffix',
runtimeSessionId='your-session-id',
qualifier="DEFAULT"
)
Kode boto3 berikut akan menghapus Amazon Bedrock AgentCore runtime dan file arsip.zip di s3.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
print("Deleting Agent from Amazon Bedrock AgentCore Runtime!")
response = bedrock_agentcore_client.delete_agent_runtime(
agentRuntimeId='<agent-id>'
)
print(f"Agent Runtime delete successfully!")
print(f"Status: {response['status']}")
s3_client = boto3.client('s3', region_name='us-west-2')
print("Deleting deployment archive from S3...")
s3_client.delete_object(
Bucket=f"bedrock-agentcore-code-{account_id}-us-west-2",
Key=f"{agent_name}/deployment_package.zip",
ExpectedBucketOwner=account_id
)
print("Archive deleted successfully from S3!")
- AWS Management Console
-
Perbarui agen
Dari halaman detail Agen, pilih Perbarui hosting untuk membuat versi baru dengan kode atau konfigurasi yang diperbarui.
Perbarui titik akhir
Pilih titik akhir dari tabel Endpoints dan pilih Sunting untuk memperbarui deskripsi atau versi terkait.
Hapus titik akhir
Pilih titik akhir dan pilih Hapus . Anda harus mengetik “hapus” untuk mengonfirmasi penghapusan.
Hapus agen
Dari daftar agen atau halaman detail, pilih agen Anda dan pilih Hapus untuk menghapus agen dan semua sumber daya terkait.
Python-specific konsep untuk penyebaran kode langsung
Pelajari tentang Python-specific konsep saat menggunakan penerapan kode langsung dengan Amazon Bedrock AgentCore Waktu pelaksanaan.
Ketika Anda menggunakan import pernyataan dalam kode Anda, runtime Python mencari direktori di jalur pencariannya sampai menemukan modul atau paket. Secara default, lokasi pertama yang dicari runtime adalah direktori tempat paket penerapan.zip Anda didekompresi dan dipasang ( /var/task ).
Anda dapat melihat jalur pencarian lengkap untuk AgentCore Agen runtime dengan menambahkan cuplikan kode berikut.
import sys
search_path = sys.path
print(search_path)
Anda juga dapat menambahkan dependensi dalam folder terpisah di dalam paket.zip Anda. Misalnya, Anda dapat menambahkan versi Boto3 SDK ke folder dalam paket.zip Anda yang disebut common . Ketika paket.zip Anda didekompresi dan dipasang, folder ini ditempatkan di dalam /var/task direktori. Untuk menggunakan dependensi dari folder dalam paket penerapan.zip dalam kode Anda, gunakan import from pernyataan. Misalnya, untuk menggunakan versi Boto3 dari folder bernama common dalam paket.zip Anda, gunakan pernyataan berikut.
from common import boto3
Kami menyarankan Anda untuk tidak menyertakan
pycache
folder dalam paket penerapan agen Anda. Bytecode Python yang dikompilasi pada mesin build dengan arsitektur atau sistem operasi yang berbeda mungkin tidak kompatibel dengan AgentCore Lingkungan eksekusi runtime.
Jika fungsi Anda hanya menggunakan paket dan modul Python murni, Anda dapat menggunakan uv pip install perintah untuk menginstal dependensi Anda pada mesin build lokal dan membuat file.zip Anda. Banyak pustaka Python populer, termasuk NumPy dan Panda, bukan Python murni dan berisi kode yang ditulis dalam C atau C. Ketika Anda menambahkan pustaka yang berisi C/C kode ke paket penerapan Anda, Anda harus membuat paket Anda dengan benar agar kompatibel dengan AgentCore Lingkungan eksekusi runtime.
Sebagian besar paket tersedia di Indeks Paket Python ( PyPI ) tersedia sebagai “roda” (file.whl). File.whl adalah jenis file ZIP yang berisi distribusi bawaan dengan binari pra-dikompilasi untuk sistem operasi tertentu dan arsitektur set instruksi. Untuk membuat paket penerapan Anda kompatibel dengan Amazon Bedrock AgentCore Runtime, Anda menginstal roda untuk sistem operasi Linux dan lengan64 arsitektur set instruksi.
Beberapa paket mungkin hanya tersedia sebagai distribusi sumber. Untuk paket-paket ini, Anda perlu mengkompilasi dan membangun C/C++ komponen sendiri.
Untuk melihat distribusi apa yang tersedia untuk paket yang Anda butuhkan, lakukan hal berikut:
Jika paket Anda hanya tersedia sebagai distribusi sumber, Anda perlu membangun C/C++ perpustakaan sendiri. Untuk membuat paket Anda kompatibel dengan Amazon Bedrock AgentCore Lingkungan eksekusi runtime, Anda perlu membangunnya di lingkungan yang menggunakan sistem operasi Amazon Linux yang sama dengan lengan64 set instruksi. Anda dapat melakukan ini dengan membuat paket Anda di instans Linux Amazon Elastic Compute Cloud (Amazon EC2).
Untuk mempelajari cara meluncurkan dan menyambung ke instans Amazon EC2 Linux, lihat Memulai dengan Amazon EC2 di Panduan Pengguna Amazon EC2.