View a markdown version of this page

Gerencie agentes assíncronos e de longa duração com o Amazon Bedrock Runtime AgentCore - Amazon Bedrock AgentCore
Principais conceitosImplementação de tarefas assíncronasExemplo completoProblemas e soluções comuns de

Gerencie agentes assíncronos e de longa duração com o Amazon Bedrock Runtime AgentCore

O Amazon Bedrock AgentCore Runtime pode lidar com processamento assíncrono e agentes de longa execução. As tarefas assíncronas permitem que seu agente continue processando depois de responder ao cliente e realize operações de longa duração sem bloquear as respostas. Com o processamento assíncrono, seu agente pode:

  • Inicie uma tarefa que pode levar minutos ou horas

  • Responda imediatamente ao usuário dizendo “Comecei a trabalhar nisso”

  • Continue processando em segundo plano

  • Permitir que o usuário verifique os resultados mais tarde

Principais conceitos

Modelo de processamento assíncrono

O Amazon Bedrock AgentCore SDK suporta processamento síncrono e assíncrono por meio de uma API unificada. Isso cria um padrão de implementação flexível para clientes e desenvolvedores de agentes. Clientes agentes podem trabalhar com a mesma API sem diferenciar entre síncrono e assíncrono no lado do cliente. Com a capacidade de invocar a mesma sessão em todas as invocações, os desenvolvedores de agentes podem reutilizar o contexto e desenvolver esse contexto de forma incremental sem implementar uma lógica complexa de gerenciamento de tarefas.

Gerenciamento do ciclo de vida da sessão em tempo de execução

O código do agente comunica seu status de processamento usando o status de integridade do endpoint “/ping”. O /ping endpoint deve retornar uma resposta HTTP 200 com a seguinte carga JSON:

{"status": "HealthyBusy"}

A resposta contém um campo obrigatório e um campo opcional:

  • status(obrigatório) — seja "Healthy" (inativo, aguardando solicitações) ou "HealthyBusy" (processando tarefas em segundo plano). A plataforma usa esse campo para determinar se a sessão ainda está ativa.

  • time_of_last_update(opcional) — Carimbo de data/hora do Unix em segundos a partir da status última alteração. Defina-o somente em uma mudança de status real, não em cada ping.

Uma sessão em estado ocioso ("Healthy") por 15 minutos é automaticamente encerrada. Uma sessão que retorna "HealthyBusy" permanece ativa além do tempo limite de inatividade.

Atenção

Se você incluirtime_of_last_update, não a defina para a hora atual em cada ping. Um registro de data e hora que avança a cada ping sinaliza uma mudança contínua de status, o que evita que o tempo limite da sessão ociosa seja acionado. As sessões então persistem até MaxLifetime esgotar sua cota de sessão. Omita o campo (a plataforma rastreia as mudanças de status sozinha) ou atualize-o somente quando o status realmente mudar. Se você usa o AgentCore SDK do Bedrock, isso é feito para você.

Implementação de tarefas assíncronas

Para começar, instale o bedrock-agentcore pacote:

pip install bedrock-agentcore

AgentCore O SDK fornece as seguintes opções para processamento assíncrono de integração.

exemplo
API based task management

  1. Para criar agentes interativos que executam tarefas assíncronas, você precisa ligar ao iniciar uma tarefa e add_async_task complete_async_task quando a tarefa for concluída. O SDK gerencia o rastreamento de tarefas e gerencia o status do Ping automaticamente.

    # 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. Você pode implementar seu próprio manipulador de ping personalizado para gerenciar o estado da sessão de tempo de execução. A saúde do seu agente é relatada por meio do endpoint /ping:

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

    Valores de status:

    • “Saudável”: pronto para um novo trabalho

    • “HealthyBusy“: Processando tarefa em segundo plano

Importante

Certifique-se de que o @app.entrypoint manipulador não execute operações de bloqueio, pois isso também pode bloquear o endpoint de verificação de integridade /ping. Use threads separados ou métodos assíncronos para bloquear as operações.

Exemplo completo

Primeiro, instale o pacote necessário:

pip install strands-agents

Em seguida, crie um arquivo Python com o seguinte código:

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

Este exemplo demonstra:

  • Criação de uma tarefa em segundo plano que é executada de forma assíncrona

  • Rastreando o status da tarefa com add_async_task e complete_async_task

  • Responder imediatamente ao usuário enquanto o processamento continua

  • Gerenciando automaticamente o estado de saúde do agente

Problemas e soluções comuns de

Long-running o agente é encerrado após 15 minutos

Isso pode acontecer quando o aplicativo tem um único encadeamento e o encadeamento de ping está bloqueado.

  • Verifique se as chamadas de bloqueio no caminho de invocação estão em um encadeamento separado ou assíncrono sem bloqueio

  • Execute o servidor de agente assíncrono localmente e simule cenários enquanto verifica o status do ping.