View a markdown version of this page

Menangani agen asinkron dan berjalan lama dengan Amazon Bedrock Runtime AgentCore - Batuan Dasar Amazon AgentCore
Konsep UtamaMenerapkan tugas asinkronContoh lengkapMasalah dan solusi umum

Menangani agen asinkron dan berjalan lama dengan Amazon Bedrock Runtime AgentCore

Amazon Bedrock AgentCore Runtime dapat menangani pemrosesan asinkron dan agen yang berjalan lama. Tugas asinkron memungkinkan agen Anda untuk melanjutkan pemrosesan setelah merespons klien dan menangani operasi yang berjalan lama tanpa memblokir respons. Dengan pemrosesan asinkron, agen Anda dapat:

  • Memulai tugas yang mungkin memakan waktu beberapa menit atau jam

  • Segera tanggapi pengguna yang mengatakan “Saya sudah mulai mengerjakan ini”

  • Lanjutkan pemrosesan di latar belakang

  • Memungkinkan pengguna untuk memeriksa kembali nanti untuk hasil

Konsep Utama

Model pemrosesan asinkron

Amazon Bedrock AgentCore SDK mendukung pemrosesan sinkron dan asinkron melalui API terpadu. Ini menciptakan pola implementasi yang fleksibel untuk klien dan pengembang agen. Klien agen dapat bekerja dengan API yang sama tanpa membedakan antara sinkron dan asinkron di sisi klien. Dengan kemampuan untuk memanggil sesi yang sama di seluruh pemanggilan, pengembang agen dapat menggunakan kembali konteks dan membangun konteks ini secara bertahap tanpa menerapkan logika manajemen tugas yang kompleks.

Manajemen siklus hidup sesi runtime

Kode agen mengkomunikasikan status pemrosesannya menggunakan status kesehatan titik akhir “/ping”. /pingTitik akhir harus mengembalikan respons HTTP 200 dengan payload JSON berikut:

{"status": "HealthyBusy"}

Respons berisi bidang wajib dan bidang opsional:

  • status(wajib) — baik "Healthy" (menganggur, menunggu permintaan) atau "HealthyBusy" (memproses tugas latar belakang). Platform menggunakan bidang ini untuk menentukan apakah sesi masih aktif.

  • time_of_last_update(opsional) - Stempel waktu Unix dalam hitungan detik saat terakhir berubah. status Setel hanya pada perubahan status aktual, bukan pada setiap ping.

Sesi dalam keadaan idle ("Healthy") selama 15 menit akan dihentikan secara otomatis. Sesi yang kembali "HealthyBusy" tetap hidup di luar batas waktu idle.

Awas

Jika Anda menyertakantime_of_last_update, jangan atur ke waktu saat ini pada setiap ping. Stempel waktu yang maju pada setiap ping menandakan perubahan status berkelanjutan, yang mencegah batas waktu sesi idle tidak pernah diaktifkan — sesi kemudian bertahan hingga MaxLifetime dan dapat menghabiskan kuota sesi Anda. Hilangkan bidang (platform melacak perubahan statusnya sendiri) atau perbarui hanya ketika status benar-benar berubah. Jika Anda menggunakan Bedrock AgentCore SDK, ini ditangani untuk Anda.

Menerapkan tugas asinkron

Untuk memulai, instal bedrock-agentcore paket:

pip install bedrock-agentcore

AgentCore SDK menyediakan opsi berikut untuk integrasi pemrosesan asinkron.

contoh
API based task management

  1. Untuk membangun agen interaktif yang melakukan tugas asinkron, Anda perlu menelepon add_async_task saat memulai tugas dan complete_async_task saat tugas selesai. SDK menangani pelacakan tugas dan mengelola status Ping secara otomatis.

    # Start tracking a task manually
task_id = app.add_async_task("data_processing")

# Do work...

# Mark task as complete
app.complete_async_task(task_id)
Custom ping handler

  1. Anda dapat menerapkan penangan ping kustom Anda sendiri untuk mengelola status Runtime Session. Kesehatan agen Anda dilaporkan melalui titik akhir/ping:

    @app.ping
def custom_status():
    if system_busy():
        return PingStatus.HEALTHY_BUSY
    return PingStatus.HEALTHY

    Nilai status:

    • “Sehat”: Siap untuk pekerjaan baru

    • “HealthyBusy“: Memproses tugas latar belakang

penting

Pastikan @app.entrypoint handler tidak melakukan operasi pemblokiran, karena ini mungkin juga memblokir titik akhir pemeriksaan kesehatan /ping. Gunakan thread terpisah atau metode async untuk memblokir operasi.

Contoh lengkap

Pertama, instal paket yang diperlukan:

pip install strands-agents

Kemudian, buat file Python dengan kode berikut:

import threading
import time
from strands import Agent, tool
from bedrock_agentcore.runtime import BedrockAgentCoreApp

# Initialize app with debug mode for task management
app = BedrockAgentCoreApp()

@tool
def start_background_task(duration: int = 5) -> str:
    """Start a simple background task that runs for specified duration."""
    # Start tracking the async task
    task_id = app.add_async_task("background_processing", {"duration": duration})

    # Run task in background thread
    def background_work():
        time.sleep(duration)  # Simulate work
        app.complete_async_task(task_id)  # Mark as complete

    threading.Thread(target=background_work, daemon=True).start()
    return f"Started background task (ID: {task_id}) for {duration} seconds. Agent status is now BUSY."

# Create agent with the tool
agent = Agent(tools=[start_background_task])

@app.entrypoint
def main(payload):
    """Main entrypoint - handles user messages."""
    user_message = payload.get("prompt", "Try: start_background_task(3)")
    return {"message": agent(user_message).message}

if __name__ == "__main__":
    print("🚀 Simple Async Strands Example")
    print("Test: curl -X POST http://localhost:8080/invocations -H 'Content-Type: application/json' -d '{\"prompt\": \"start a 3 second task\"}'")
    app.run()

Contoh ini menunjukkan:

  • Membuat tugas latar belakang yang berjalan secara asinkron

  • Melacak status tugas dengan add_async_task dan complete_async_task

  • Menanggapi segera pengguna saat pemrosesan berlanjut

  • Mengelola status kesehatan agen secara otomatis

Masalah dan solusi umum

Long-running agen akan dihentikan setelah 15 menit

Ini bisa terjadi ketika aplikasi berulir tunggal dan utas ping diblokir.

  • Periksa apakah memblokir panggilan di jalur pemanggilan berada di utas terpisah atau asinkron non-pemblokiran

  • Jalankan server agen async secara lokal dan simulasikan skenario sambil memeriksa status ping.