本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用亚马逊 Bedrock AgentCore Runtime 处理异步和长时间运行的代理
<a name="runtime-long-run"></a>

Amazon Bedrock AgentCore Runtime 可以处理异步处理和长时间运行的代理。异步任务允许您的代理在响应客户端后继续处理，并在不阻塞响应的情况下处理长时间运行的操作。通过异步处理，您的代理可以：
+ 启动可能需要几分钟或几小时的任务
+ 立即回复用户说 “我已经开始研究这个了”
+ 继续在后台处理
+ 允许用户稍后再回来查看结果

## 重要概念
<a name="runtime-long-run-key-concepts"></a>

### 异步处理模型
<a name="runtime-long-run-async-model"></a>

亚马逊 Bedrock AgentCore SDK 支持通过统一的 API 进行同步和异步处理。这为客户和代理开发人员创建了灵活的实现模式。代理客户端可以使用相同的 API，无需区分客户端的同步和异步。由于能够跨次调用同一个会话，代理开发人员可以重复使用上下文并在此上下文的基础上逐步构建，而无需实现复杂的任务管理逻辑。

### 运行时会话生命周期管理
<a name="runtime-long-run-session-lifecycle"></a>

代理代码使用 “/ping” 端点运行状况来传达其处理状态。`/ping`终端节点必须返回具有以下 JSON 负载的 HTTP 200 响应：

```
{"status": "HealthyBusy"}
```

响应包含必填字段和可选字段：
+  `status`（必需）—`"Healthy"`（空闲、等待请求）或`"HealthyBusy"`（处理后台任务）。平台使用此字段来确定会话是否仍处于活动状态。
+  `time_of_last_update`（可选）— Unix 时间戳（以`status`上次更改时的秒为单位）。仅在实际状态更改时进行设置，而不是在每次 ping 时进行设置。

处于空闲状态 (`"Healthy"`) 15 分钟的会话会自动终止。空闲超时后，返回的会话`"HealthyBusy"`仍处于活动状态。

**警告**  
如果包括在内`time_of_last_update`，请勿将其设置为每次 ping 的当前时间。每次 ping 都会向前移动的时间戳表示状态持续变化，这可以防止空闲会话超时触发——然后会话会一直持续到会话配额用尽为止`MaxLifetime`。省略该字段（平台自行跟踪状态变化）或仅在状态实际发生变化时才对其进行更新。如果你使用 Bedrock AgentCore SDK，这个问题将由你来处理。

## 实现异步任务
<a name="runtime-long-run-implementing"></a>

要开始使用，请安装该`bedrock-agentcore`软件包：

```
pip install bedrock-agentcore
```

AgentCore SDK 为集成异步处理提供以下选项。

**Example**  

1. 要构建执行异步任务的交互式代理，您需要`add_async_task`在启动任务和任务完成`complete_async_task`时调用。SDK 自动处理任务跟踪并管理 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)
   ```

1. 您可以实现自己的自定义 ping 处理程序来管理运行时会话的状态。您的代理的运行状况通过 /ping 端点报告：

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

   状态值：
   + “健康”：为新工作做好准备
   + HealthyBusy“”: 正在处理后台任务

**重要**  
确保`@app.entrypoint`处理程序不执行阻塞操作，因为这也可能阻塞 /ping 运行状况检查端点。使用单独的线程或异步方法来阻塞操作。

## 完整示例
<a name="runtime-long-run-complete-example"></a>

首先，安装所需的软件包：

```
pip install strands-agents
```

然后，使用以下代码创建 Python 文件：

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

这个例子演示了：
+ 创建异步运行的后台任务
+ 使用`add_async_task`和跟踪任务状态 `complete_async_task` 
+ 在处理继续进行时立即回复用户
+ 自动管理代理的运行状况

## 常见问题和解决方案
<a name="runtime-long-run-common-issues"></a>

### Long-running 代理在 15 分钟后终止
<a name="runtime-long-run-issue-terminated"></a>

当应用程序为单线程且 ping 线程被阻塞时，可能会发生这种情况。
+ 检查调用路径中的阻塞调用是否在单独的线程中或异步非阻塞中
+ 在本地运行异步代理服务器并在检查 ping 状态时模拟场景。