기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon Bedrock AgentCore 런타임을 사용하여 비동기식 및 장기 실행 에이전트 처리
Amazon Bedrock AgentCore 런타임은 비동기 처리 및 장기 실행 에이전트를 처리할 수 있습니다. 비동기 작업을 사용하면 에이전트가 클라이언트에 응답한 후 계속 처리하고 응답을 차단하지 않고 장기 실행 작업을 처리할 수 있습니다. 비동기 처리를 통해 에이전트는 다음을 수행할 수 있습니다.
+ 몇 분 또는 몇 시간이 걸릴 수 있는 작업 시작
+ 사용자에게 "이 작업을 시작했습니다"라고 즉시 응답합니다.
+ 백그라운드에서 계속 처리
+ 사용자가 나중에 결과를 다시 확인하도록 허용
## 주요 개념
### 비동기 처리 모델
Amazon Bedrock AgentCore SDK는 통합 API를 통한 동기 및 비동기 처리를 모두 지원합니다. 이렇게 하면 클라이언트와 에이전트 개발자 모두에게 유연한 구현 패턴이 생성됩니다. 에이전트 클라이언트는 클라이언트 측에서 동기식과 비동기식 간에 구분하지 않고 동일한 API로 작업할 수 있습니다. 에이전트 개발자는 호출 간에 동일한 세션을 호출할 수 있으므로 복잡한 작업 관리 로직을 구현하지 않고도 컨텍스트를 재사용하고이 컨텍스트를 점진적으로 구축할 수 있습니다.
### 런타임 세션 수명 주기 관리
에이전트 코드는 "/ping" 엔드포인트 상태를 사용하여 처리 상태를 전달합니다. `/ping` 엔드포인트는 다음 JSON 페이로드와 함께 HTTP 200 응답을 반환해야 합니다.
```
{"status": "HealthyBusy"}
```
응답에는 필수 필드와 선택적 필드가 포함됩니다.
+ `status` (필수) - `"Healthy"` (유휴, 요청 대기 중) 또는 `"HealthyBusy"` (백그라운드 작업 처리 중). 플랫폼은이 필드를 사용하여 세션이 여전히 활성 상태인지 확인합니다.
+ `time_of_last_update` (선택 사항) - `status` 마지막 변경 시간의 초 단위 Unix 타임스탬프입니다. 모든 ping이 아닌 실제 상태 변경에만 설정합니다.
15분 동안 유휴 상태(`"Healthy"`)인 세션은 자동으로 종료됩니다. 세션 반환은 유휴 제한 시간 이후에`"HealthyBusy"`도 유지됩니다.
**주의**
를 포함하는 경우 모든 ping에서 현재 시간으로 설정하지 `time_of_last_update`마십시오. 모든 ping에서 진행되는 타임스탬프는 지속적인 상태 변경 신호를 보내 유휴 세션 제한 시간이 실행되지 않도록 합니다. 그러면 세션은 `MaxLifetime`가 세션 할당량을 소진할 수 있을 때까지 지속됩니다. 필드를 생략하거나(플랫폼은 상태 변경을 자체적으로 추적함) 실제로 상태가 변경될 때만 업데이트합니다. Bedrock AgentCore SDK를 사용하는 경우이 작업이 처리됩니다.
## 비동기 작업 구현
시작하려면 `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": 백그라운드 작업 처리
**중요**
/ping 상태 확인 엔드포인트도 차단할 수 있으므로 `@app.entrypoint` 핸들러가 차단 작업을 수행하지 않는지 확인합니다. 별도의 스레드 또는 비동기 메서드를 사용하여 작업을 차단합니다.
## 전체 예제
먼저 필요한 패키지를 설치합니다.
```
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`
+ 처리가 계속되는 동안 사용자에게 즉시 응답
+ 에이전트 상태 자동 관리
## 일반적인 문제 및 해결 방법
### 장기 실행 에이전트는 15분 후에 종료됩니다.
이는 애플리케이션이 단일 스레드이고 ping 스레드가 차단될 때 발생할 수 있습니다.
+ 호출 경로의 호출 차단이 별도의 스레드 또는 비차단 비동기화에 있는지 확인
+ ping 상태를 확인하면서 로컬에서 비동기 에이전트 서버를 실행하고 시나리오를 시뮬레이션합니다.