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

HTTP 프로토콜 계약

에이전트 애플리케이션에서 HTTP 프로토콜을 구현하기 위한 요구 사항을 이해합니다. HTTP 프로토콜을 사용하여 기존 요청/응답 패턴을 위한 직접 REST API 엔드포인트와 실시간 양방향 스트리밍 연결을 위한 WebSocket 엔드포인트를 생성합니다.

예제 코드는 AgentCore CLI 시작하기를 참조하세요.

컨테이너 요구 사항

에이전트는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.

경로 요구 사항

/호출 - POST

JSON 입력 및 JSON/SSE 출력이 있는 기본 에이전트 상호 작용 엔드포인트입니다.

용도

사용자 또는 애플리케이션으로부터 수신 요청을 수신하고 에이전트의 비즈니스 로직을 통해 처리합니다.

사용 사례

/invocations 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

요청 형식 예

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)를 사용하면 실시간 스트리밍 응답을 제공할 수 있습니다. 자세한 내용은 서버 전송 이벤트 사양을 참조하세요.

용도

장기 실행 작업과 향상된 사용자 경험을 위해 증분 응답 전송을 활성화합니다.

사용 사례

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 엔드포인트는 다음을 처리해야 합니다.

메시지 형식

텍스트 메시지

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?

바이너리 메시지

용도

이미지, 오디오 또는 기타 바이너리 형식과 같은 텍스트가 아닌 데이터 지원

사용 사례

이진 메시지는 여러 시나리오를 지원합니다.

요구 사항 처리

이진 메시지 처리에는 다음이 필요합니다.

연결 수명 주기

연결 설정

메시지 교환

/ping - GET

용도

에이전트가 작동 중이고 요청을 처리할 준비가 되었는지 확인합니다.

사용 사례

/ping 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

응답 형식

에이전트의 상태를 나타내는 상태 코드를 반환합니다.

에이전트가 백그라운드 작업을 처리해야 하는 경우 /ping 상태로 표시할 수 있습니다. ping 상태가 HealthyBusy 이면 런타임 세션이 활성 상태로 간주됩니다.

예제 Ping 응답 형식

{
  "status": "<status_value>"
}

오류 처리

A2A, MCP 및 AG-UI 프로토콜과 달리 HTTP 프로토콜은 프로토콜별 봉투에 오류를 래핑하지 않습니다. 서비스는 오류를 네이티브 HTTP 응답으로 직접 반환합니다. HTTP 상태 코드는 예외를 반영하고 x-amzn-ErrorType 응답 헤더에는 예외 이름이 포함됩니다. 다음 표에는 받을 수 있는 예외가 나열되어 있습니다.

ConflictException 및 RetryableConflictException 모두 HTTP 409를 반환합니다. x-amzn-ErrorType 헤더와 메시지는 이를 구분합니다. 두 번째 작업이 서비스가 프로비저닝하거나 해제하는 세션을 대상으로 하면 서비스는 RetryableConflictException (Session operation in progress, please retry)를 반환합니다. 이 조건은 일시적이며 재시도 가능합니다. 짧은 지수 백오프로 재시도합니다. 기본 재시도가 활성화된 경우 AWS SDKs 자동 재시도합니다. AWS SDK 없이 API를 직접 호출하는 경우 직접 다시 시도해야 합니다.

OAuth 인증 응답

OAuth로 구성된 에이전트는 RFC 6749(OAuth 2.0) 인증 표준을 따릅니다. 인증이 누락된 경우 서비스는 클라이언트가 GetRuntimeProtectedResourceMetadata API를 통해 권한 부여 서버 엔드포인트를 검색할 수 있도록 (RFC 7235에 따라) 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}"