기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# Amazon Bedrock AgentCore 런타임 V2에 맞게 에이전트 최적화
<a name="runtime-v2-optimize"></a>

Amazon Bedrock AgentCore 런타임 V2는 스냅샷을 복원하여 에이전트를 시작합니다. 이렇게 하면 에이전트 코드의 구조가 변경됩니다. 시작 시 에이전트가 수행하는 작업은 스냅샷에 캡처되고 복원된 모든 인스턴스에서 공유됩니다. 대신 요청 핸들러에서 요청마다 달라야 하거나 만료될 수 있는 값을 생성합니다. 이 주제에서는 각 복원 후 올바르게 유지되도록 시작 작업 및 요청당 작업을 중심으로 에이전트를 구성하는 방법을 설명합니다. 플랫폼 버전 V2에 대한 개요는 [플랫폼 버전을](runtime-how-it-works.md#runtime-platform-versions) 참조하세요.

에이전트에는 두 가지 실행 컨텍스트가 있습니다.

스타트업 폴더  
AgentCore 런타임이 스냅샷을 생성하기 전에 프로세스가 시작될 때 한 번 실행되는 코드입니다. AgentCore 런타임은 스냅샷에서이 코드를 캡처하고 모든 인스턴스는 결과를 상속합니다.

요청 처리  
`/invocations` 핸들러의 코드입니다. 이 코드는 모든 인스턴스의 모든 요청에서 실행됩니다.

하나의 규칙을 사용하여 코드가 속한 위치를 결정합니다. 스냅샷 수명 동안 동일하게 유지되는 경우 시작 시 값을 계산합니다. 요청에 따라 다르거나 만료될 수 있는 경우 핸들러에서 계산합니다. AgentCore 런타임은 에이전트 버전당 스냅샷 하나를 생성하여 에이전트를 생성하거나 업데이트할 때까지 사용합니다. 따라서 스냅샷 수명은 해당 버전의 수명입니다.

## 시작 시 한 번 초기화
<a name="_initialize_once_at_startup"></a>

스냅샷 전에 프로세스가 시작될 때 비용이 많이 들고 재사용 가능한 작업을 수행합니다. 예를 들어 배포 번들에서 종속성을 가져오거나, 모델 가중치를 로드하거나, 정적 구성을 읽습니다. AgentCore SDK를 사용하여를 호출하기 전에 모듈 범위에서이 작업을 수행합니다`app.run()`. 에이전트는가 `app.run()` 실행될 때까지 포트 8080에서 수신 대기하지 않으므로 시작 작업이 완료될 때까지 성공할 `/ping` 수 없고 스냅샷을 생성할 수 없습니다. 스냅샷은 완전히 초기화된 에이전트를 구성별로 캡처하므로를 게이트할 필요가 없습니다`/ping`. 시작 후 120초 이내에 초기화를 완료합니다. 에이전트가 제시간에 정상 상태가 되지 않으면 런타임은 상태 확인에 실패합니다. `/ping` 및 `/invocations` 엔드포인트에 대한 자세한 내용은 [ AgentCore 런타임 서비스 계약 이해를 참조하세요](runtime-service-contract.md).

```
import json, pathlib

from bedrock_agentcore.runtime import BedrockAgentCoreApp

# Runs once at import, before app.run() starts the server and before the
# snapshot. Every restored instance inherits these objects.
MODEL = load_model_weights()
SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text())

app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    # Per-request work runs here on every instance.
    ...

app.run()  # starts listening on 8080; the snapshot is taken after this
```

에이전트가 AgentCore SDK 대신 자체 HTTP 서버를 실행하는 경우 스냅샷이 완전히 초기화된 에이전트를 캡처하도록 초기화가 완료된 후에`/ping`만에서 정상 상태를 보고합니다.

시작 시 모든 인스턴스에 대해 동일하고 만료되지 않는 읽기 전용 데이터입니다. 핸들러에서 수명이 짧은 자격 증명과 같은 시간에 민감한 값을 처리합니다.

**참고**  
다시 배포하지 않고는 시작 시 변경한 내용을 계산하지 마십시오. 예를 들어 AgentCore Gateway에서 가져온 도구 카탈로그는 로드 속도가 느리고 비용이 많이 들기 때문에 이상적인 시작 값처럼 보이지만 시작 시 캐싱하면 스냅샷 시점에 에이전트의 도구 인벤토리가 고정됩니다.

## 요청당 상태를 새로 유지
<a name="_keep_per_request_state_fresh"></a>

스냅샷은 한 번 캡처되고 복원된 모든 인스턴스에서 공유되므로 시작 시 에이전트가 생성하는 모든 값은 인스턴스 간에 동일하며 스냅샷 시점에 고정됩니다. 스냅샷이 핸들러에 포함할 수 없는 값을 `/invocations` 처리합니다. 다음 표에서는 시작 시 대신 핸들러에서 계산할 값을 설명합니다.


| 목적 | 핸들러에서 수행 | 이유 | 
| --- | --- | --- | 
| 무작위 값, 식별자 또는 토큰 생성 | 각 요청에서 `secrets`, 또는 `os.urandom()``uuid.uuid4()`를 호출합니다. |  `os.urandom()`는 복원 후 호출할 때마다 새 엔트로피만 반환합니다. 시작 시 읽은 값은 스냅샷에 복사되며 모든 인스턴스에서 동일하지만 엔트로피 소스는 읽을 때 양호했습니다. `random` 마찬가지로 모듈은 시작 시 시드되므로 복원된 인스턴스는 동일한 시퀀스를 반복합니다. | 
| 현재 시간 읽기 | 각 요청에 대해 계산 | 시작 시 캡처된 타임스탬프는 스냅샷 시점에 고정됩니다. | 
| 경과 시간 측정 | 핸들러에서 참조 타임스탬프 가져오기 |  `time.monotonic()`는 복원을 진행하지 않으므로 시작 참조에서 측정된 지속 시간이 잘못된 것으로 보이지 않습니다. | 
| 자격 증명 또는 토큰 사용 | 만료 시 새로 고침 | 시작 시 로드된 자격 증명은 인스턴스가 시작되기 전에 만료될 수 있습니다. | 
| 인스턴스 또는 작업자 식별 | 요청당 ID 생성, 호스트에서 파생하지 않음 | 복원된 모든 인스턴스는 동일한 호스트 이름(`localhost`)과 PID(`1`)를 보고하므로 ID로를 사용하면 플릿 전체에서 지표, 로그 스트림 및 잠금 소유자가 축소됩니다. | 

시작 시 재사용 가능한 클라이언트를 구축하고 각 호출에서 요청당 값을 계산합니다.

```
import os, time

# Build reusable clients at startup, before the snapshot. Exercise them here too
# (for example, with a warm-up call) so the setup the client caches — endpoint and
# credential resolution, connection pool — is captured in the snapshot.
client = build_client()
warm_up(client)

@app.entrypoint
def invoke(payload):
    creds = get_credentials()          # refreshed when expired, not read at startup
    request_id = os.urandom(16).hex()  # unique per request
    now = time.time()                  # current time, not snapshot time
    # Handle the request.
```

## 스냅샷 보호 암호화 라이브러리 사용
<a name="_use_snapshot_safe_cryptographic_libraries"></a>

AgentCore 런타임이 스냅샷에서 인스턴스를 복원할 때 시작 시 임의 상태를 캐싱한 암호화 라이브러리는 인스턴스 간에 해당 상태를 재사용할 수 있습니다. 암호화 라이브러리는 복원 후 재시도되는 스냅샷 보호(스냅세이프) 빌드를 사용해야 합니다.

직접 코드 배포  
서비스 관리형 기본 이미지에는 이미 암호화 라이브러리의 스냅샷 보호 빌드가 포함되어 있으므로 이에 대한 조치를 취할 필요가 없습니다.

Bring-your-own 암호화 라이브러리  
예를 들어 컨테이너 에이전트에서 자체 암호화 라이브러리를 가져오는 경우 스냅샷 보호 빌드를 사용하여 복원 후 복구되도록 합니다. Amazon Linux 2023에서는를 사용합니다`openssl-snapsafe-libs`.

## 네트워킹
<a name="_networking"></a>

시작 시 클라이언트를 구축하고 투명한 재연결 예상  
시작 시 여는 소켓은 복원되지 않지만 클라이언트 라이브러리가 캐시하는 설정인 서비스 모델 구문 분석, 엔드포인트 확인, 자격 증명 확인 및 연결 풀은 복원됩니다. 시작 시 클라이언트를 구성하고 연습하고 복원 후 첫 번째 호출을 예상하여 연결을 투명하게 다시 설정합니다.

호스트 이름 또는 PID를 고유한 인스턴스 식별자로 사용하지 마십시오.  
복원된 모든 인스턴스는 동일한 스냅샷에서 시작하고 동일한 호스트 이름과 프로세스 ID를 보고합니다. 각 요청에서 고유 식별자를 생성합니다.

고정 소스 포트에 바인딩 방지  
복원 후 스냅샷 시간에 보류된 연결이 다시 설정되고 고정 소스 포트가 인스턴스 내에서 해당 대체 포트와 충돌할 수 있습니다. 복원된 인스턴스는 자체 네트워크 네임스페이스가 있는 별도의 microVMs이므로 충돌이 인스턴스 내에서 발생하고 인스턴스 간에 충돌이 발생하지 않습니다.