# HTTP 프로토콜 계약
에이전트 애플리케이션에서 HTTP 프로토콜을 구현하기 위한 요구 사항을 이해합니다. HTTP 프로토콜을 사용하여 기존 요청/응답 패턴을 위한 직접 REST API 엔드포인트와 실시간 양방향 스트리밍 연결을 위한 WebSocket 엔드포인트를 생성합니다.
**참고**
HTTP(`/invocations`) 및 WebSocket(`/ws`) 엔드포인트 모두 포트 8080을 사용하여 동일한 컨테이너에 배포할 수 있으므로 단일 에이전트 구현이 기존 API 상호 작용과 실시간 양방향 스트리밍을 모두 지원할 수 있습니다.
예제 코드는 [ AgentCore CLI 시작하기를 참조하세요](runtime-get-started-cli.md).
**Topics**
+ [컨테이너 요구 사항](#container-requirements-http)
+ [경로 요구 사항](#path-requirements-http)
+ [OAuth 인증 응답](#http-oauth-authentication-responses)
## 컨테이너 요구 사항
에이전트는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.
+ **호스트: ** `0.0.0.0`
+ **포트**: `8080` - HTTP 기반 에이전트 통신을 위한 표준 포트
+ **플랫폼**: ARM64 컨테이너 - AgentCore 런타임 환경과의 호환성에 필요합니다.
## 경로 요구 사항
### /호출 - POST
JSON 입력 및 JSON/SSE 출력이 있는 기본 에이전트 상호 작용 엔드포인트입니다.
**용도**
사용자 또는 애플리케이션으로부터 수신 요청을 수신하고 에이전트의 비즈니스 로직을 통해 처리합니다.
**사용 사례**
`/invocations` 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.
+ 직접 사용자 상호 작용 및 대화
+ 외부 시스템과 API 통합
+ 여러 요청의 배치 처리
+ 장기 실행 작업을 위한 실시간 스트리밍 응답
**요청 형식 예**
```
Content-Type: application/json
{
"prompt": "What's the weather today?"
}
```
**응답 형식**
에이전트는 사용 사례에 따라 다음 형식 중 하나를 사용하여 응답할 수 있습니다.
#### JSON 응답(비스트리밍)
**용도**
빠르게 처리할 수 있는 요청에 대한 전체 응답을 제공합니다.
**사용 사례**
JSON 응답은 다음과 같은 경우에 적합합니다.
+ 간단한 질문 응답 시나리오
+ 결정적 계산
+ 빠른 데이터 조회
+ 상태 확인
**JSON 응답 형식 예**
```
Content-Type: application/json
{
"response": "Your agent's response here",
"status": "success"
}
```
#### SSE 응답(스트리밍)
서버 전송 이벤트(SSE)를 사용하면 실시간 스트리밍 응답을 제공할 수 있습니다. 자세한 내용은 [서버 전송 이벤트](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) 사양을 참조하세요.
**용도**
장기 실행 작업과 향상된 사용자 경험을 위해 증분 응답 전송을 활성화합니다.
**사용 사례**
SSE 응답은 다음과 같은 경우에 적합합니다.
+ 실시간 대화형 경험
+ 점진적 콘텐츠 생성
+ 중간 결과를 사용한 장기 실행 계산
+ 라이브 데이터 피드 및 업데이트
**예제 SSE 응답 형식**
```
Content-Type: text/event-stream
data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}
```
### /ws - WebSocket(선택 사항)
실시간 양방향 통신을 위한 기본 WebSocket 연결 엔드포인트입니다.
**용도**
WebSocket 업그레이드 요청을 수락하고 스트리밍 에이전트 상호 작용을 위한 지속적인 연결을 유지합니다.
**사용 사례**
`/ws` 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.
+ 실시간 대화형 인터페이스
+ 즉각적인 피드백이 포함된 대화형 에이전트 세션
+ 양방향 통신을 통한 스트리밍 데이터 처리
**연결 설정**
WebSocket 연결은 HTTP 업그레이드 요청으로 시작됩니다.
**HTTP 업그레이드 요청 예**
```
GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid
```
**WebSocket 업그레이드 응답 예제**
```
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
```
**메시지 처리 요구 사항**
WebSocket 엔드포인트는 다음을 처리해야 합니다.
+ **연결 수락**: 연결을 설정`await websocket.accept()`하기 위한 호출
+ **메시지 수신**: 애플리케이션 요구 사항에 따라 텍스트 또는 이진 메시지 유형 지원
+ **메시지 처리**: 에이전트의 비즈니스 로직에 따라 수신 메시지 처리
+ **응답 전송**: `send_text()` 또는를 사용하여 적절한 응답 전송 `send_bytes()`
+ **연결 수명 주기**: 연결 설정, 유지 관리 및 종료 관리
#### 메시지 형식
##### 텍스트 메시지
##### JSON 형식(권장)
**용도**
에이전트 상호 작용을 위한 구조화된 데이터 교환
**메시지 예**
```
{
"prompt": "Hello, can you help me with this question?",
"session_id": "session-uuid",
"message_type": "user_message"
}
```
**응답의 예**
```
{
"response": "I'd be happy to help you with your question!",
"session_id": "session-uuid",
"message_type": "agent_response"
}
```
##### 일반 텍스트 형식
**용도**
간단한 텍스트 기반 통신
**예제**
```
Hello, can you help me with this question?
```
##### 바이너리 메시지
**용도**
이미지, 오디오 또는 기타 바이너리 형식과 같은 텍스트가 아닌 데이터 지원
**사용 사례**
이진 메시지는 여러 시나리오를 지원합니다.
+ 다중 모달 에이전트 상호 작용
+ 파일 업로드 및 다운로드
+ 압축 데이터 전송
+ 이진 프로토콜 데이터
**요구 사항 처리**
이진 메시지 처리에는 다음이 필요합니다.
+ `receive_bytes()` 및 `send_bytes()` 메서드 사용
+ 적절한 바이너리 데이터 처리 구현
+ 메시지 크기 제한 고려
#### 연결 수명 주기
##### 연결 설정
1. **HTTP 핸드셰이크**: 클라이언트가 WebSocket 업그레이드 요청 전송
1. **업그레이드 응답**: 에이전트가 101 전환 프로토콜을 수락하고 반환합니다.
1. **WebSocket Active**: 양방향 통신 시작
1. **세션 바인딩**: 연결을 세션 식별자와 연결
##### 메시지 교환
1. **연속 루프**: 메시지 수신 루프 구현
1. **메시지 처리**: 수신 메시지를 비동기적으로 처리
1. **응답 생성**: 적절한 응답 전송
1. **오류 처리**: 예외 및 연결 문제 관리
### /ping - GET
**용도**
에이전트가 작동하고 요청을 처리할 준비가 되었는지 확인합니다.
**사용 사례**
`/ping` 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.
+ 문제를 감지하고 해결하기 위한 서비스 모니터링
+ AWS의 관리형 인프라를 통한 자동 복구
**응답 형식**
에이전트의 상태를 나타내는 상태 코드를 반환합니다.
+ **Content-Type:** `application/json`
+ **HTTP 상태 코드**: 비정상 상태에 `200` 대한 정상적이고 적절한 오류 코드
에이전트가 백그라운드 작업을 처리해야 하는 경우 `/ping` 상태로 표시할 수 있습니다. ping 상태가 `HealthyBusy` 이면 런타임 세션이 활성 상태로 간주됩니다.
**예제 Ping 응답 형식**
```
{
"status": ""
}
```
**상태**(필수)
`Healthy` - 시스템이 새 작업을 수락할 준비가 되었습니다.
`HealthyBusy` - 시스템이 작동 중이지만 현재 비동기 작업으로 사용 중입니다. 상태가 인 동안 `HealthyBusy`런타임 세션은 활성 상태로 간주되고 활성 상태로 유지됩니다.
**time\_of\_last\_update**(선택 사항)
`status` 마지막 변경 시점의 Unix 타임스탬프(초)입니다. 실제 상태 변경 시에만 설정합니다.
모든 ping`time_of_last_update`에서 현재 시간으로 설정하지 마십시오. 모든 ping에서 진행되는 타임스탬프는 지속적인 상태 변경 신호를 보내 유휴 세션 제한 시간이 실행되지 않도록 합니다. 그러면 세션은 `MaxLifetime`가 세션 할당량을 소진할 수 있을 때까지 지속됩니다. 필드를 생략하면 플랫폼이 자체적으로 상태 변경을 추적합니다. Bedrock AgentCore SDK를 사용하는 경우 ping 응답이 처리됩니다.
## OAuth 인증 응답
OAuth로 구성된 에이전트는 [RFC 6749(OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749) 인증 표준을 따릅니다. 인증이 누락된 경우 서비스는 클라이언트가 GetRuntimeProtectedResourceMetadata API를 통해 권한 부여 서버 엔드포인트를 검색할 수 있도록 ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)에 따라) WWW-Authenticate 헤더와 함께 401 무단 응답을 반환합니다.
### 401 권한이 없음
권한 부여 헤더가 누락된 경우 반환됩니다.
다음과 같이 WWW-Authenticate 헤더를 포함합니다.
```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
**참고**
SigV4-configured 에이전트는 `ACCESS_DENIED` 오류와 함께 HTTP 403을 반환하며 `WWW-Authenticate` 헤더를 포함하지 않습니다.