Gestisci agenti asincroni e di lunga durata con Amazon Bedrock Runtime AgentCore

Amazon Bedrock AgentCore Runtime è in grado di gestire l'elaborazione asincrona e gli agenti a lunga durata. Le attività asincrone consentono all'agente di continuare l'elaborazione dopo aver risposto al client e di gestire operazioni di lunga durata senza bloccare le risposte. Con l'elaborazione asincrona, il tuo agente può:

• Avviare un'attività che potrebbe richiedere minuti o ore

• Rispondi immediatamente all'utente dicendo «Ho iniziato a lavorarci»

• Continua l'elaborazione in background

• Consenti all'utente di ricontrollare i risultati in un secondo momento

Concetti chiave

Modello di elaborazione asincrono

L'Amazon Bedrock AgentCore SDK supporta l'elaborazione sincrona e asincrona tramite un'API unificata. Questo crea un modello di implementazione flessibile sia per i clienti che per gli agenti sviluppatori. Gli agenti client possono lavorare con la stessa API senza distinguere tra sincrona e asincrona sul lato client. Grazie alla possibilità di richiamare la stessa sessione per più chiamate, gli sviluppatori di agenti possono riutilizzare il contesto e basarsi su questo contesto in modo incrementale senza implementare una logica di gestione delle attività complessa.

Gestione del ciclo di vita delle sessioni di runtime

Il codice dell'agente comunica lo stato di elaborazione utilizzando lo stato di integrità dell'endpoint «/ping». L'/pingendpoint deve restituire una risposta HTTP 200 con il seguente payload JSON:

{"status": "HealthyBusy"}

La risposta contiene un campo obbligatorio e un campo opzionale:

• status(obbligatorio): "Healthy" (inattivo, in attesa di richieste) o "HealthyBusy" (elaborazione di attività in background). La piattaforma utilizza questo campo per determinare se la sessione è ancora attiva.

• time_of_last_update(opzionale) — Timestamp Unix in secondi dell'ultima modifica. status Impostalo solo su un cambio di stato effettivo, non su ogni ping.

Una sessione in stato di inattività ("Healthy") per 15 minuti viene interrotta automaticamente. Una sessione che ritorna "HealthyBusy" rimane attiva oltre il timeout di inattività.

avvertimento

Se lo includitime_of_last_update, non impostarlo sull'ora corrente di ogni ping. Un timestamp che avanza ad ogni ping segnala un cambiamento continuo dello stato, che impedisce che il timeout della sessione inattiva si attivi. Le sessioni quindi persistono fino MaxLifetime all'esaurimento della quota di sessione e possono esaurire la quota di sessione. Ometti il campo (la piattaforma tiene traccia delle modifiche di stato da sola) o aggiornalo solo quando lo stato cambia effettivamente. Se utilizzi Bedrock AgentCore SDK, questo viene gestito per te.

Implementazione di attività asincrone

Per iniziare, installa il pacchetto: bedrock-agentcore

pip install bedrock-agentcore

AgentCore L'SDK fornisce le seguenti opzioni per l'integrazione dell'elaborazione asincrona.

Esempio

API based task management

1. Per creare agenti interattivi che eseguono attività asincrone, è necessario chiamare all'avvio di un'attività e al add_async_task termine dell'attività. complete_async_task L'SDK gestisce il monitoraggio delle attività e gestisce automaticamente lo stato del ping.

   # 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. Puoi implementare il tuo gestore di ping personalizzato per gestire lo stato della sessione di runtime. Lo stato di salute del tuo agente viene segnalato tramite l'endpoint /ping:

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

   Valori di stato:

   • «Healthy»: pronto per un nuovo lavoro

   • "HealthyBusy«: Elaborazione dell'attività in background

Importante

Assicurati che il @app.entrypoint gestore non esegua operazioni di blocco, poiché ciò potrebbe bloccare anche l'endpoint /ping health check. Usa thread separati o metodi asincroni per bloccare le operazioni.

Esempio completo

Innanzitutto, installa il pacchetto richiesto:

pip install strands-agents

Quindi, crea un file Python con il seguente codice:

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 = str(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()

Questo esempio dimostra:

• Creazione di un'attività in background che viene eseguita in modo asincrono

• Monitoraggio dello stato dell'attività con e add_async_task complete_async_task

• Rispondere immediatamente all'utente mentre l'elaborazione continua

• Gestione automatica dello stato di salute dell'agente

Problemi e soluzioni comuni

Long-running l'agente viene terminato dopo 15 minuti

Ciò può accadere quando l'applicazione è a thread singolo e il thread ping è bloccato.

• Verifica che le chiamate di blocco nel percorso di invocazione siano in un thread separato o asincrono non bloccante

• Esegui il server agente asincrono localmente e simula gli scenari controllando lo stato del ping.