기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
AgentCore 런타임에 대한 수명 주기 후크 구성
수명 주기 후크는 AgentCore 런타임이 에이전트 런타임 수명 주기의 특정 지점에서 호출하는 컨테이너의 엔드포인트입니다. 후크를 사용하여 세션이 시작되기 전에 에이전트를 준비하는 등 해당 지점에서 자체 코드를 실행합니다. CreateAgentRuntime 및 UpdateAgentRuntime hooksConfiguration 필드를 사용하여 후크를 구성하고 해당 후크가 속한 수명 주기 단계를 기준으로 그룹화합니다.
수명 주기 후크는 microVM에서 플랫폼 버전 V2를 사용하는 에이전트 런타임에 사용할 수 있습니다. microVMs 자세한 내용은 플랫폼 버전을 참조하세요.
요구 사항
-
에이전트 런타임은 플랫폼 버전 V2를 사용해야 합니다. V1에서는에서 요청이 실패합니다
ValidationException. -
에이전트 런타임은 microVMs 유형을 사용해야 합니다. 인스턴스에서는 수명 주기 후크가 지원되지 않습니다.
hooksConfiguration와를 결합하면 요청이 로capacityProviderConfiguration실패합니다ValidationException.
후크 호출 작동 방식
에이전트 런타임이 수명 주기의 후크 지점에 도달하면 AgentCore 런타임은 후크의 작업을 한 번 실행합니다. 컨테이너에 단일 요청을 하고 구현이 후크의 시간 제한 내에서 성공을 보고할 때까지 기다립니다. AgentCore 런타임은 후크 호출을 재시도하지 않습니다.
호출이 실패하거나 시간 제한 내에 성공하지 못하면 후크를 트리거한 작업이 실패합니다. 예를 들어 빌드 후크가 실패하면 런타임은 실패를 failureReason 설명하는 CREATE_FAILED 또는 UPDATE_FAILED 로 이동합니다. 자세한 내용은 수명 주기 후크 문제 해결을 참조하세요.
구현이 성공을 보고하는 방법은 후크의 작업에 따라 달라집니다.
후크 작업
각 후크에는 AgentCore 런타임이 컨테이너를 호출하는 방식을 정의하는 작업이 하나씩 있습니다.
HTTP 작업
HTTP 작업은 컨테이너의 서버에서 선택한 path 및 port에 HTTP 요청을 보냅니다. 구현은 작업이 완료된 후 2xx 상태 코드를 반환하여 성공을 보고합니다. 다른 모든 상태 코드 또는 실패한 연결은 호출에 실패합니다. 각 요청에는 호출을 식별하는 헤더가 포함될 수 있습니다. 각 후크에는 전송하는 헤더와 값이 나열됩니다.
후크는 POST 요청을 보내는 httpPost 작업을 지원합니다. 다음 action.httpPost 필드가 있는 후크의 필드에서 구성합니다.
| Field | 유형 | 필수 | 설명 |
|---|---|---|---|
|
|
문자열 |
예 |
AgentCore 런타임이 요청을 보내는 경로입니다. 경로는 다음 규칙을 충족해야 합니다.
|
|
|
Integer |
아니요 |
AgentCore 런타임이 요청을 보내는 포트입니다. 지원되는 범위는 |
후크의 경로는 HTTP 메서드, 경로 및 포트입니다. 에이전트의 서빙 포트에서 AgentCore 런타임이 이미 사용하는 라우팅과 일치할 수 없습니다. 다음 표에는 이러한 플랫폼 경로가 나열되어 있습니다.
| 프로토콜 | 후크가 사용할 수 없는 경로 |
|---|---|
|
모든 프로토콜 |
|
|
MCP |
|
|
A2A |
|
충돌은 메서드와 경로를 비교합니다. 예를 들어 AgentCore 런타임은를 사용하기 때문에 POST /ping는 유효한 후크 경로입니다GET /ping. 서비스 포트 및 호출 경로는 에이전트의 서비스 포트 및 호출 경로 구성을 참조하세요.
에이전트 런타임에서 세션 엔드포인트를 사용하는 경우 AgentCore 런타임은 세션 엔드포인트 요청으로부터 후크를 보호합니다.
-
후크의 경로를 대상으로 하는 요청은 HTTP
403및 컨테이너에 도달AccessDenied하기 전에 거부됩니다. 경로 일치는 대/소문자를 무시하고 경로의 일반적인 동등한 철자를 동일한 경로로 처리합니다. 여기에는 반복 또는 후행 슬래시,...세그먼트, 백분율 인코딩 문자 및;파라미터가 포함됩니다. -
후크 헤더는 예약되어 있습니다. AgentCore 런타임은 세션 엔드포인트 요청에서 이를 삭제하므로 애플리케이션은 후크 호출 시에만 후크 헤더를 수신합니다.
수명 주기 후크 구성
에이전트 런타임을 생성하거나 업데이트할 hooksConfiguration 때를 지정합니다. 다음 예제에서는 포트 POST /warmup에서를 호출하는 빌드 워밍업 후크를 사용하여 V2 런타임을 생성합니다8080. 후크의 기능은 워밍업 후크 빌드를 참조하세요. 리전, 컨테이너 이미지 URI 및 실행 역할 ARN을 값으로 바꿉니다.
예
UpdateAgentRuntime는 전체 후크 구성을 대체합니다. 후크hooksConfiguration를 유지하려는 모든 업데이트 요청에를 포함합니다. 후크를 제거하려면 UpdateAgentRuntime 없이를 호출합니다hooksConfiguration.
지원되는 후크
| 단계 | 후크 | AgentCore 런타임에서 호출하는 경우 | 에 사용 |
|---|---|---|---|
|
|
|
에이전트를 준비하는 동안 |
세션이 더 빠르게 시작되도록 메모리와 디스크를 준비합니다. 자세한 내용은 워밍업 후크 빌드를 참조하세요. |
빌드 워밍업 후크
AgentCore 런타임은 런타임이에 도달하기 UpdateAgentRuntime전에 CreateAgentRuntime 및 중에 에이전트를 준비하는 동안 빌드 워밍업 후크를 호출합니다READY. 이 순서대로 두 번 호출하고 구현에 어떤 호출인지 알려줍니다.
| 워밍업 유형 | Order | 수행할 작업 |
|---|---|---|
|
|
먼저 에이전트가 |
가져오기, 모델, 캐시 등 모든 세션에 필요한 것을 메모리에 로드합니다. 각 새 인스턴스는 여기에 로드하는 것으로 시작합니다. |
|
|
초 |
세션이 시작될 때 에이전트가 읽는 파일을 읽습니다. AgentCore 런타임은 이러한 읽기를 사용하여 이러한 파일을 새 세션에서 더 빠르게 사용할 수 있도록 합니다. |
HTTP 작업을 사용하면 AgentCore 런타임이 memory 또는 값과 함께 X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type 헤더의 워밍업 유형을 전송합니다disk.
두 호출은 총 120초의 시간 제한을 공유합니다. memory 호출이 먼저 실행되기 때문에 disk 호출은 memory 호출이 종료되는 시간을 가져옵니다. 예를 들어 memory 호출에 50초가 걸리는 경우 disk 호출에는 70초가 걸립니다. 이 제한은 변경할 수 없습니다.
워밍업 후크는에 도달하는 CreateAgentRuntime UpdateAgentRuntime 데 걸리는 시간에 최대 120초까지 추가할 수 있습니다READY. 각 워밍업 로그 줄은 하나의 생성 또는 업데이트에 대해 두 번 이상 나타날 수 있습니다.
워밍업 핸들러 쓰기
워밍업 핸들러는 에이전트의 서버에서 /ping 및 호출 핸들러와 함께 실행됩니다.
-
응답
/ping성을 유지합니다. 워밍업이 실행되는/ping동안 서버가 계속 응답해야 합니다. 워밍업 핸들러 내에서 서버의 유일한 스레드를 차단하지 마십시오. 별도의 스레드 또는 프로세스에서 작업을 실행하거나 요청을 동시에 처리하는 서버를 사용합니다. -
작업이 완료된 후에
2xx만를 반환합니다. 응답할 때 로드한 것은 세션이 시작하는 것입니다.
다음 FastAPI 애플리케이션은 포트의에서 /ping/invocations, 및 워밍업 후크POST /warmup를 제공합니다8080. 작업자 스레드에서 워밍업 작업을 실행하므로 서버가 계속에 응답합니다/ping. load_shared_state 및 STARTUP_FILES를 에이전트의 작업 및 파일로 바꿉니다.
import asyncio from fastapi import FastAPI, Request, Response app = FastAPI() # Files that each session reads when it starts. STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"] def load_shared_state(): # Load what every session needs into memory, such as heavy imports, # model weights, and caches. ... def read_startup_files(): # Read the files that a session reads when it starts, so that new # sessions can use them faster. for path in STARTUP_FILES: with open(path, "rb") as f: while f.read(1024 * 1024): pass @app.get("/ping") def ping(): return {"status": "Healthy"} @app.post("/warmup") async def warmup(request: Request): # Header lookup in Starlette and FastAPI is case-insensitive. warmup_type = request.headers.get( "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", "" ).lower() # Run the work in a worker thread so that /ping keeps answering. if warmup_type == "memory": await asyncio.to_thread(load_shared_state) elif warmup_type == "disk": await asyncio.to_thread(read_startup_files) # Respond only after the work is done. return Response(status_code=200) @app.post("/invocations") async def invoke(request: Request): payload = await request.json() # Per-request work runs here on every session. return {"response": payload.get("prompt", "")}
애플리케이션을 로 저장하는 경우 다음 명령을 사용하여 컨테이너에서 app.py시작합니다.
uvicorn app:app --host 0.0.0.0 --port 8080
각 호출에 넣을 내용은 수명 주기 후크를 사용하여 메모리 및 디스크 준비를 참조하세요.
후크 로그 보기
AgentCore 런타임은 이름이 로 시작하는 로그 스트림/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT에서 각 빌드 후크 호출의 진행 상황과 결과를 런타임의 로그 그룹에 기록합니다build-logs-. 각 줄은 로 시작하고 [LIFECYCLE-HOOK <epoch-milliseconds>]그 뒤에[LIFECYCLE]는 진행 상황 또는 실패가 [ERROR]옵니다. 라인과 이에 대한 작업 방법은 수명 주기 후크 문제 해결을 참조하세요.