# Penyebaran kode langsung untuk Python Penerapan kode langsung memungkinkan Anda membawa Python-based agen Anda ke Amazon Bedrock AgentCore Runtime hanya dengan mengemas kode agen dan dependensinya dalam arsip file.zip. Agen Anda masih harus mengikuti [persyaratan AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html): memiliki file entrypoint .py yang menggunakan anotasi dari `@app.entrypoint` Amazon [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python) atau mengimplementasikan titik akhir server POST dan GET. `/invocations` `/ping` ## Prasyarat Sebelum Anda mulai, pastikan Anda memiliki: + ** AWS Akun** dengan kredensil dikonfigurasi. Untuk mengonfigurasi AWS kredensil Anda, lihat [Konfigurasi dan pengaturan file kredenal di](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) CLI. AWS + [Uv](https://docs.astral.sh/uv/getting-started/installation/) **diinstal** dan [Python](https://docs.astral.sh/uv/guides/install-python/) 3.10\+ diinstal + ** AWS Izin**: Untuk membuat dan menyebarkan agen dengan AgentCore CLI, Anda harus memiliki izin yang sesuai. Untuk informasi selengkapnya, lihat [Menggunakan AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli). + **Akses model**: Anthropic Claude Sonnet 4.0 diaktifkan [di](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) konsol Amazon Bedrock. Untuk informasi tentang penggunaan model yang berbeda dengan Agen Strands, lihat bagian *Penyedia Model* dalam dokumentasi [Strands Agents SDK](https://strandsagents.com/latest/documentation/docs/). ## Langkah 1: Siapkan proyek dan instal dependensi Inisialisasi proyek Anda dengan perintah berikut: ``` uv init agentcore_runtime_direct_deploy --python 3.13 cd agentcore_runtime_direct_deploy ``` Tambahkan paket inti: ``` uv add bedrock-agentcore strands-agents ``` Instal AgentCore CLI (diperlukan untuk langkah-langkah berikut): ``` npm install -g @aws/agentcore ``` Deskripsi Package: + **bedrock-agentcore** - Amazon AgentCore Bedrock SDK untuk membangun agen AI + **strands-agents - The Strands Agents** [SDK](https://strandsagents.com/latest/) + **@ aws/agentcore** - AgentCore CLI Secara opsional, jalankan `uv add aws-opentelemetry-distro` untuk mengaktifkan jejak [ AgentCore pengamatan Amazon Bedrock](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). Uv akan secara otomatis membuat `pyproject.toml` file dengan dependensi, `uv.lock` file dengan penutupan ketergantungan dan direktori. `.venv` ## Langkah 2: Buat proyek agen Anda Gunakan `agentcore create` perintah untuk menyiapkan proyek agen kerangka dengan kerangka kerja pilihan Anda: ``` agentcore create ``` Perintah akan meminta Anda untuk: + Pilih kerangka kerja (pilih Strands Agents untuk tutorial ini) + Berikan nama proyek + Pilih templat (dasar atau produksi) + Pilih penyedia model dan opsi lainnya Perintah ini menghasilkan: + Kode agen dengan kerangka kerja yang Anda pilih + `pyproject.toml`File dengan dependensi yang diperlukan + File `agentcore/agentcore.json` konfigurasi + File Infrastructure as Code (IAc) jika template produksi dipilih ## Langkah 3: Uji secara lokal Pastikan port 8080 gratis sebelum memulai. Lihat *Port 8080 yang digunakan (hanya lokal)* dalam [Masalah dan solusi umum](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). Buka jendela terminal dan mulai agen Anda dengan perintah berikut: ``` agentcore dev --no-browser ``` Uji agen Anda dengan membuka jendela terminal lain dan masukkan perintah berikut: ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello!"}' ``` **Sukses:** Anda harus melihat respons seperti`{"result": "Hello! I’m here to help…​"}`. Di jendela terminal yang menjalankan agen, masukkan `Ctrl+C` untuk menghentikan agen. ## Langkah 4: Aktifkan observabilitas untuk agen Anda [Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) membantu Anda melacak, men-debug, dan memantau agen yang Anda host di Runtime. AgentCore Pertama aktifkan Penelusuran CloudWatch Transaksi dengan mengikuti petunjuk di [Mengaktifkan observabilitas AgentCore runtime Amazon Bedrock](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Untuk mengamati agen Anda, lihat [Melihat data observabilitas untuk agen Amazon Bedrock AgentCore Anda](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html). ## Langkah 5: Terapkan ke AgentCore Runtime dan panggil Gunakan agen Anda menggunakan salah satu metode berikut: **Example** 1. Langkah-langkah berikut akan diperlukan untuk menyebarkan agen ke AgentCore Runtime. Untuk informasi selengkapnya, lihat [Memulai AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html). Jika Uv tersedia, AgentCore CLI akan merekomendasikan penyebaran kode langsung. Jika tidak, itu akan default ke tipe penerapan kontainer. Setelah agen Anda mengatur penggunaan`agentcore create`, gunakan `deploy` perintah untuk membuat paket penyebaran zip, unggah ke bucket yang ditentukan, dan gunakan agen. ``` agentcore deploy ``` Mari kita minta agen untuk menceritakan lelucon\! ``` agentcore invoke "Tell me a joke" ``` Penerapan pertama membutuhkan waktu untuk menginstal dependensi tetapi pembaruan selanjutnya ke agen mengoptimalkannya dengan menggunakan kembali dependensi zip **Manajemen konfigurasi** Anda dapat memodifikasi konfigurasi agen Anda kapan saja menggunakan `agentcore add` perintah atau dengan mengedit file `agentcore/agentcore.json` konfigurasi secara langsung. File konfigurasi memungkinkan Anda memperbarui parameter penerapan seperti konfigurasi VPC, peran eksekusi, batas waktu sesi, dan pengaturan otorisasi OAuth. 1. Jalankan `agentcore` untuk membuka TUI, lalu pilih **deploy**. Layar penerapan menunjukkan kemajuan waktu nyata saat memvalidasi proyek Anda, mensintesis CloudFormation, dan menyediakan sumber daya: AWS ![AgentCore menyebarkan kemajuan yang menunjukkan pembaruan CloudFormation tumpukan](https://docs.aws.amazon.com/id_id/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) Setelah penerapan selesai, gunakan `agentcore invoke` untuk menguji agen Anda. 1. Untuk mengunduh roda yang kompatibel dengan AgentCore Runtime, Anda menggunakan opsi uv pip`--python-platform`. AgentCore Runtime hanya mendukung arsitektur set instruksi **arm64**, jalankan perintah berikut. Ganti `--python 3.x` dengan versi runtime Python yang Anda gunakan. ``` 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 Anda membuat paket.zip deployment, Anda dapat menggunakannya untuk membuat AgentCore Runtime baru atau memperbarui yang sudah ada. Anda dapat menerapkan paket.zip Anda menggunakan AgentCore Runtime API, AgentCore Runtime console dan Command AWS Line Interface. AgentCore CLI akan menangani langkah-langkah di atas untuk membuat.zip. **catatan** . Ukuran maksimum untuk paket deployment .zip untuk AgentCore Runtime adalah 250 MB (zip) dan 750 MB (unzip). Perhatikan bahwa batas ini berlaku untuk ukuran gabungan semua file yang Anda unggah. 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 penyebaran Anda. Misalnya, untuk memberikan file yang tidak dapat dieksekusi izin yang benar, jalankan perintah berikut,. `chmod 644 ` Untuk mengubah izin file di Windows, lihat [Mengatur, Melihat, Mengubah, atau Menghapus Izin pada Objek](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) dalam dokumentasi Microsoft Windows. \+.. Jika Anda tidak memberikan izin AgentCore Runtime 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 dependensi Linux **arm64** perlu diunggah ke S3 sebagai prasyarat untuk Create Agent Runtime. Kode di bawah ini membutuhkan bucket S3 yang ditentukan untuk sudah ada. Silakan ikuti AWS dokumentasi di [sini](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html) untuk membuat ember menggunakan boto3. Kode boto3 berikut akan mengunggah arsip file.zip ke s3 dan membuat runtime Amazon Bedrock. AgentCore ``` 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 secara terprogram](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically). 1. Anda dapat menerapkan agen menggunakan AgentCore konsol Amazon Bedrock dengan dukungan runtime terkelola. Konsol menyediakan antarmuka intuitif untuk mengunggah file ZIP dan mengonfigurasi pengaturan agen. Untuk menerapkan menggunakan konsol, pertama-tama buat paket penerapan Anda mengikuti langkah-langkah di tab *Custom zip \+ boto3* di atas. **Buat agen melalui konsol** Untuk membuat agen Anda: 1. Dari halaman rumah Agen, pilih **Agen Host** 1. Pilih pilihan sumber Anda: + **Sumber S3** - Unggah dari ember S3 + **Unggah Lokal** - Unggah file ZIP dari komputer Anda + **Template** - Gunakan templat agen pra-bangun 1. Konfigurasikan pengaturan agen Anda: + Nama agen + Versi runtime (disarankan Python 3.13) + Titik masuk (mis.,`main.py`) + Peran eksekusi (buat yang baru atau gunakan yang sudah ada) 1. Pilih **Buat Agen** untuk digunakan **Buat titik akhir** Pilih **Create Endpoint** untuk membuat endpoint baru untuk agen Anda. Nama titik akhir dan versi terkait akan diisi sebelumnya. **Uji titik akhir** Pilih titik akhir dan pilih **Test Endpoint** untuk menavigasi ke untuk pengujian. Playground/Sandbox **Persyaratan peran eksekusi** Agen Anda memerlukan peran eksekusi dengan izin yang sesuai. Untuk informasi mendetail tentang peran dan izin eksekusi, lihat Izin [AgentCore waktu proses](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). Peran eksekusi harus menyertakan izin AgentCore runtime Amazon Bedrock dasar, izin akses S3 untuk paket penerapan Anda, dan izin Log untuk observabilitas. CloudWatch ## Langkah 6: Hentikan sesi, perbarui, atau pembersihan Hentikan sesi runtime, perbarui, atau bersihkan agen Anda menggunakan salah satu metode berikut: **Example** 1. Untuk memperbarui AgentCore Runtime yang digunakan sebelumnya, jalankan: ``` agentcore deploy ``` Untuk menghentikan sesi yang berjalan sebelum dapat dikonfigurasi `IdleRuntimeSessionTimeout` (default pada 15 menit) dan menghemat potensi biaya pelarian, gunakan operasi API. [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) AgentCore CLI saat ini tidak mendukung sesi penghentian secara langsung. Untuk menghapus semua sumber daya yang terkait dengan AgentCore Runtime, pertama-tama hapus semua sumber daya, lalu terapkan untuk meruntuhkan AWS sumber daya: ``` agentcore remove all agentcore deploy ``` 1. Berikut kode boto3 akan memperbarui Runtime. AgentCore ``` 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='', 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 berjalan sebelum dapat dikonfigurasi `IdleRuntimeSessionTimeout` (default pada 15 menit) dan menghemat biaya pelarian 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 AgentCore runtime Amazon Bedrock 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='' ) 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!") ``` 1. ====== 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 **Edit** 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 halaman daftar agen atau 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 Runtime. **Topics** ### Jalur pencarian ketergantungan dan pustaka yang disertakan runtime Saat Anda menggunakan `import` pernyataan dalam kode Anda, runtime Python mencari direktori di jalur pencariannya hingga menemukan modul atau paket. Secara default, lokasi pertama pencarian runtime adalah direktori tempat paket deployment .zip Anda didekompresi dan dipasang (). `/var/task` Anda dapat melihat jalur pencarian lengkap untuk agen AgentCore Runtime Anda dengan menambahkan cuplikan kode berikut. ``` import sys search_path = sys.path print(search_path) ``` Anda juga dapat menambahkan dependensi di folder terpisah di dalam paket.zip Anda. Misalnya, Anda dapat menambahkan versi Boto3 SDK ke folder dalam paket.zip yang disebut. `common` Ketika paket.zip Anda didekompresi dan dipasang, folder ini ditempatkan di dalam direktori. `/var/task` Untuk menggunakan dependensi dari folder dalam paket deployment .zip Anda dalam kode Anda, gunakan pernyataan. `import from` Misalnya, untuk menggunakan versi Boto3 dari folder bernama `common` dalam paket.zip Anda, gunakan pernyataan berikut. ``` from common import boto3 ``` ### Python bytecode dan *pycache* folder Kami menyarankan agar Anda tidak menyertakan ` pycache ` folder dalam paket penyebaran agen Anda. Bytecode Python yang dikompilasi pada mesin build dengan arsitektur atau sistem operasi yang berbeda mungkin tidak kompatibel dengan lingkungan eksekusi AgentCore Runtime. ### Paket penyebaran dengan pustaka asli 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 mana pun 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 penyebaran Anda, Anda harus membangun paket Anda dengan benar agar kompatibel dengan lingkungan eksekusi Runtime. AgentCore Sebagian besar paket yang tersedia di Indeks Paket Python ([PyPI](https://pypi.org/)) tersedia sebagai “roda” (file.whl). File WHL adalah jenis file ZIP yang berisi distribusi yang dibangun dengan binari pra-kompilasi untuk sistem operasi tertentu dan arsitektur set instruksi. Untuk membuat paket penyebaran Anda kompatibel dengan Amazon Bedrock AgentCore AgentCore Runtime, Anda menginstal roda untuk sistem operasi Linux dan arsitektur set instruksi **arm64**. Beberapa paket mungkin hanya tersedia sebagai distribusi sumber. Untuk paket-paket ini, Anda perlu mengkompilasi dan membangun sendiri komponen C/C \+\+. Untuk melihat distribusi apa yang tersedia untuk paket yang Anda butuhkan, lakukan hal berikut: 1. Cari nama paket di halaman [utama Indeks Paket Python](https://pypi.org/). 1. Pilih versi paket yang ingin Anda gunakan. 1. Pilih **Unduh file**. ### Bekerja dengan distribusi sumber Jika paket Anda hanya tersedia sebagai distribusi sumber, Anda perlu membangun pustaka C/C \+\+ sendiri. Untuk membuat paket Anda kompatibel dengan lingkungan eksekusi Amazon Bedrock AgentCore AgentCore Runtime, Anda perlu membangunnya di lingkungan yang menggunakan sistem operasi Amazon Linux yang sama dengan set instruksi **arm64**. Anda dapat melakukannya 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 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) di Panduan Pengguna Amazon *EC2*.