인터셉터 유형
게이트웨이에 구성할 수 있는 인터셉터에는 REQUEST 인터셉터와 RESPONSE 인터셉터라는 두 가지 유형이 있습니다. 인터셉터 페이로드 구조는 게이트웨이에 구성된 대상 유형에 따라 달라집니다.
이 주제에서는 MCP 대상과 HTTP 대상(예: Amazon Bedrock AgentCore 런타임) 모두에 대한 인터셉터 계약을 다룹니다.
인터셉터 요청
게이트웨이가 게이트웨이에 구성된 대상을 호출하기 전에 REQUEST 인터셉터가 호출됩니다. REQUEST 인터셉터를 사용하여 사용자 지정 검증 또는 권한 부여를 수행할 수 있습니다.
요청 인터셉터 입력 페이로드 예제
다음 예제는 요청 인터셉터 Lambda 함수가 수신하는 입력 페이로드 구조를 보여줍니다.
{ "interceptorInputVersion": "1.0", "mcp": { "rawGatewayRequest": { "body": "<raw_request_body>" }, "gatewayRequest" : { "path": "/mcp", "httpMethod": "POST", "headers": { "Accept": "application/json", "Authorization": "<bearer_token>", "SomeHeader": "headerValue1", "Mcp-Session-Id": "<session_id>", "User-Agent": "<client_user_agent>" }, "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } } } }
참고
headers 필드는가 인터셉터 구성true에서 로 passRequestHeaders 설정된 경우에만 포함됩니다. 응답이 아직 생성되지 않았으므로 요청 인터셉터에 대한 gatewayResponse 필드가 없습니다.
요청 인터셉터 출력 페이로드 예제
다음 예제는 요청 인터셉터 Lambda 함수가 반환해야 하는 출력 페이로드 구조를 보여줍니다.
{ "interceptorOutputVersion": "1.0", "mcp": { "transformedGatewayRequest" : { "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "transformedGatewayResponse" : { "statusCode": 200, "body": { "jsonrpc": "2.0", "id": 1, "result": { "<result_content>": "<result_value>" } } } } }
중요
요청 인터셉터 출력에 대한 중요 참고 사항: *는 "1.0" 로 설정해야 interceptorOutputVersion 합니다. * 인터셉터 출력에 transformedGatewayResponse가 포함된 경우 도 제공되더라도 게이트웨이는 해당 콘텐츠로 즉시 응답transformedGatewayRequest합니다. * REQUEST 인터셉터와 RESPONSE 인터셉터가 모두 구성되어 있고 REQUEST 인터셉터 출력에 transformedGatewayResponse가 포함된 경우 RESPONSE 인터셉터는 계속 호출됩니다.
응답 인터셉터
게이트웨이가 호출자에게 응답하기 전에 RESPONSE 인터셉터가 호출됩니다. RESPONSE 인터셉터를 사용하여 응답에 대한 사용자 지정 수정 또는 추가를 호출자에게 다시 수행할 수 있습니다.
응답 인터셉터 입력 페이로드 예제
다음 예제는 응답 인터셉터 Lambda 함수가 수신하는 입력 페이로드 구조를 보여줍니다.
{ "interceptorInputVersion": "1.0", "mcp": { "rawGatewayRequest": { "body": "<raw_request_body>" }, "gatewayRequest" : { "path": "/mcp", "httpMethod": "POST", "headers": { "Accept": "application/json", "Authorization": "<bearer_token>", "SomeHeader": "headerValue1", "Mcp-Session-Id": "<session_id>", "User-Agent": "<client_user_agent>" }, "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "gatewayResponse" : { "statusCode": 200, "headers": { "SomeHeader": "headerValue1", "Mcp-Session-Id": "<session_id>" }, "body": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [] } } } } }
참고
의 headers 필드는 gatewayRequest가 인터셉터 구성true에서 로 passRequestHeaders 설정된 경우에만 포함됩니다. 응답 인터셉터는 원래 요청과 게이트웨이의 응답을 모두 수신하므로 호출자에게 반환되기 전에 응답을 수정할 수 있습니다.
응답 인터셉터 출력 페이로드 예제
다음 예제는 응답 인터셉터 Lambda 함수가 반환해야 하는 출력 페이로드 구조를 보여줍니다.
{ "interceptorOutputVersion": "1.0", "mcp": { "transformedGatewayRequest" : { "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "transformedGatewayResponse" : { "statusCode": 200, "body": { "jsonrpc": "2.0", "id": 1, "result": { "<result_content>": "<result_value>" } } } } }
중요
응답 인터셉터 출력에 대한 중요 참고 사항: *는 "1.0" 로 설정해야 interceptorOutputVersion 합니다. * 인터셉터 출력에 transformedGatewayResponse가 포함된 경우 도 제공되더라도 게이트웨이는 해당 콘텐츠로 즉시 응답transformedGatewayRequest합니다. * REQUEST 인터셉터와 RESPONSE 인터셉터가 모두 구성되어 있고 REQUEST 인터셉터 출력에 transformedGatewayResponse가 포함된 경우 RESPONSE 인터셉터는 계속 호출됩니다.
스트리밍이 활성화된 응답 인터셉터
참고
게이트웨이에서 응답 스트리밍이 활성화된 경우 응답 인터셉터 Lambda 함수는의 isStreamingResponse 필드를 확인하여 스트리밍 응답과 비스트리밍 응답을 gatewayResponse 구분해야 합니다. 스트리밍 응답의 경우 요청당, 즉 적격 이벤트당 하나씩 여러 간접 호출을 처리하고 첫 번째 간접 호출만 headers 및를 재정의할 수 있습니다statusCode.
게이트웨이에서 응답 스트리밍이 활성화되면 응답 인터셉터 동작이 변경됩니다. 인터셉터는 전체 응답과 함께 한 번이 아닌 적격 이벤트당 한 번 스트리밍 응답 중에 여러 번 호출됩니다.
응답 인터셉터가 호출되는 경우
JSON-RPC id 필드가 포함된 이벤트에 대해 응답 인터셉터가 호출됩니다.
-
첫 번째 이벤트 - 스트림에서 첫 번째 JSON-RPC 응답 또는 서버 시작 요청(예: 도구 결과 또는
elicitation/create/sampling/createMessage요청). -
후속 이벤트 - 추가 JSON-RPC 응답 또는 서버 시작 요청(예: 유도가 이행된 후 최종 도구 결과).
응답 인터셉터는 다음에 대해 호출되지 않습니다.
-
notifications/progress- 진행 상황 업데이트는 클라이언트에 직접 전달됩니다. -
notifications/message- 로그 메시지는 클라이언트에 직접 전달됩니다. -
핑 - 연결 유지 신호가 클라이언트에 직접 전달됩니다.
스트리밍 응답 인터셉터 입력 페이로드
입력 페이로드에는 로 설정된 새 isStreamingResponse 필드가 포함됩니다true. gatewayResponse.body 필드에는 현재 이벤트 본문이 포함됩니다.
첫 번째 이벤트 - 인터셉터가 headers, 및 statusCode를 수신합니다body.
{ "interceptorInputVersion": "1.0", "mcp": { "rawGatewayRequest": { "body": "<raw_request_body>" }, "gatewayRequest" : { "path": "/mcp", "httpMethod": "POST", "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "myTool", "arguments": {} } } }, "gatewayResponse" : { "statusCode": 200, "headers": { "Mcp-Session-Id": "<session_id>" }, "isStreamingResponse": true, "body": { "jsonrpc": "2.0", "id": "elicit-1", "method": "elicitation/create", "params": { "message": "Confirm this action?", "requestedSchema": {} } } } } }
후속 이벤트 - 인터셉터는 body (헤더 및 상태 코드가 이미 클라이언트로 전송됨)만 수신합니다.
{ "interceptorInputVersion": "1.0", "mcp": { "rawGatewayRequest": { "body": "<raw_request_body>" }, "gatewayRequest" : { "path": "/mcp", "httpMethod": "POST", "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "myTool", "arguments": {} } } }, "gatewayResponse" : { "isStreamingResponse": true, "body": { "jsonrpc": "2.0", "id": 1, "result": { "content": [{"type": "text", "text": "Tool result"}] } } } } }
스트리밍 응답 인터셉터 출력 페이로드
인터셉터가 재정의할 수 있는 사항은 첫 번째 이벤트인지 후속 이벤트인지에 따라 달라집니다.
| Event | 재정의 가능 | 반환된 경우 무시됨 |
|---|---|---|
|
첫 번째 이벤트 |
|
해당 사항 없음 |
|
후속 이벤트 |
|
|
|
비스트리밍(변경되지 않음) |
|
해당 사항 없음 |
HTTP 대상에 대한 인터셉터
HTTP 대상은 MCP 대상과 다른 인터셉터 페이로드 구조를 사용합니다. HTTP 대상(AgentCore 런타임 및 패스스루) 및 추론 대상은 모두이 http페이로드 구조를 사용합니다. 추론은 HTTP 인터셉터 페이로드 셰이프를 공유하기 위해 발생하는 별도의 대상 유형입니다. 페이로드는 http 키 대신 mcp 키를 사용합니다. 요청 및 응답 본문은 구문 분석된 JSON 객체가 아닌 base64로 인코딩된 문자열입니다.
HTTP 대상은 게이트웨이가 응답 인터셉터를 호출하기 전에 전체 응답을 버퍼링하는 버퍼 모드에서 REQUEST 및 RESPONSE 인터셉터를 모두 지원합니다. 인터셉터는 스트리밍 모드에서 아직 지원되지 않습니다.
다음 목록에는 HTTP 대상 인터셉터의 주요 동작이 요약되어 있습니다.
-
httpMethod필드는 읽기 전용입니다. -
요청 및 응답
body필드는 base64로 인코딩된 문자열입니다. -
headers필드는 인터셉터 구성에서이 로passRequestHeaders설정된 경우에만 요청 페이로드true에 포함됩니다. -
transformedGatewayResponse가 REQUEST 인터셉터의 출력에 있는 경우 게이트웨이는 대상을 호출하지 않고 해당 응답을 즉시 반환합니다(단락). RESPONSE 인터셉터는 단락 후 실행되지 않습니다.
요청 인터셉터 입력 페이로드 예제
다음 JSON 예제는 HTTP 대상 요청을 처리할 때 요청 인터셉터 Lambda 함수가 수신하는 입력 페이로드의 구조를 보여줍니다.
{ "interceptorInputVersion": "1.0", "http": { "gatewayRequest": { "path": "/my-target-name/invocations", "httpMethod": "POST", "headers": { "Content-Type": "application/json", "Authorization": "<bearer_token>" }, "body": "<base64_encoded_body>" } } }
참고
입력 페이로드에 대한 다음 사항에 유의하세요.
-
필드는 인터셉터 구성
true에서이 로passRequestHeaders설정된 경우에만headers포함됩니다. -
body필드는 원시 HTTP 요청 본문을 나타내는 base64로 인코딩된 문자열입니다. -
httpMethod필드는 정보 제공 목적으로 포함되지만 읽기 전용입니다. 인터셉터는 변경할 수 없습니다.
요청 인터셉터 출력 페이로드 예제
다음 JSON 예제는 HTTP 대상 요청을 변환할 때 요청 인터셉터 Lambda 함수가 반환해야 하는 출력 페이로드의 구조를 보여줍니다.
{ "interceptorOutputVersion": "1.0", "http": { "transformedGatewayRequest": { "headers": { "Content-Type": "application/json", "X-Custom-Header": "custom-value" }, "body": "<base64_encoded_body>" }, "transformedGatewayResponse": { "contentType": "application/json", "statusCode": 200, "headers": { "X-Custom-Header": "custom-value" }, "body": "<base64_encoded_body>" } } }
중요
HTTP 요청 인터셉터 출력에 대한 중요 참고 사항:
-
는 로 설정해야
interceptorOutputVersion합니다"1.0". -
출력에가 포함된 경우 게이트웨이는 대상
transformedGatewayResponse을 호출하지 않고 해당 응답을 즉시 반환합니다. -
body필드는 base64로 인코딩된 문자열이어야 합니다. -
httpMethod는 수정할 수 없으므로 출력에 포함되지 않습니다.
응답 인터셉터 입력 페이로드 예제
HTTP 대상에 대한 RESPONSE 인터셉터를 구성하면 게이트웨이가 대상 응답을 버퍼링하여 Lambda 함수에 전달합니다. 다음 JSON 예제는 입력 페이로드의 구조를 보여줍니다.
{ "interceptorInputVersion": "1.0", "http": { "gatewayRequest": null, "gatewayResponse": { "statusCode": 200, "headers": null, "body": "<base64_encoded_body>", "contentType": "application/json" } } }
참고
응답 입력 페이로드에 대한 다음 사항에 유의하세요.
-
body필드는 원시 HTTP 응답 본문을 나타내는 base64로 인코딩된 문자열입니다. -
body필드는 페이로드 필터가 있는 응답 본문을 제외하는null경우 입니다. 자세한 내용은 대용량 응답 페이로드 처리를 참조하세요.
응답 인터셉터 출력 페이로드 예제
다음 JSON 예제는 HTTP 대상 응답을 변환할 때 응답 인터셉터 Lambda 함수가 반환하는 출력 페이로드의 구조를 보여줍니다.
{ "interceptorOutputVersion": "1.0", "http": { "transformedGatewayResponse": { "statusCode": 200, "headers": { "X-Custom-Header": "custom-value" }, "body": "<base64_encoded_body>", "contentType": "application/json" } } }
중요
HTTP 응답 인터셉터 출력에 대한 중요 참고 사항:
-
는 로 설정해야
interceptorOutputVersion합니다"1.0". -
statusCode,body및contentType필드는 각각 원래 응답 값을 재정의합니다. 필드를 생략(또는 로 설정null)하면 게이트웨이가 원래 값을 사용합니다. -
body필드는 base64로 인코딩된 문자열이어야 합니다. -
응답을 변경하지 않고 전달하려면 빈
http객체를 반환합니다{"interceptorOutputVersion": "1.0", "http": {}}.
대규모 응답 페이로드 처리
Lambda 동기 호출에는 요청과 응답을 합친 페이로드 한도가 6MB입니다. 대상이 추론 모델과 공통적인 큰 본문을 반환하는 경우 base64로 인코딩된 페이로드가이 제한을 초과하고 오류가 발생할 수 있습니다.
이를 방지하려면 RESPONSE_BODY 필드를 제외하는 페이로드 필터를 구성하여 인터셉터 입력에서 응답 본문을 제외합니다. 인터셉터는 여전히 statusCode, contentType및를 검사할 수 headers있으며 헤더를 주입하거나 상태 코드를 재정의할 수 있습니다. 응답 본문이 제외되면 입력 페이로드의 body 필드는 이고 함수가 body: null를 반환null하면 게이트웨이는 원래(수정되지 않은) 응답 본문을 사용합니다.
클라이언트 컨텍스트
HTTP 대상의 경우 게이트웨이는 호출의 클라이언트 컨텍스트를 통해 요청 메타데이터를 Lambda 함수에 전달합니다. 함수는 GATEWAY_ARN, GATEWAY_ACCOUNT_ID, 및 사용자 지정 값을 읽을 수 있습니다REQUEST_IDSOURCE_IP. GATEWAY_ARN, GATEWAY_ACCOUNT_ID및 REQUEST_ID 값은 항상 존재합니다. SOURCE_IP 값은 소스 IP를 사용할 수 있는 경우에만 포함되므로 함수는 이를 선택 사항으로 취급해야 합니다.
MCP와 HTTP 인터셉터 페이로드의 주요 차이점
다음 표에는 MCP와 HTTP 대상 인터셉터 페이로드의 차이점이 요약되어 있습니다.
| Field | MCP 대상 | HTTP 대상 |
|---|---|---|
|
본문 형식 |
맵<문자열, 객체>(파싱된 JSON) |
문자열(base64 인코딩) |
|
경로 |
항상 "/mcp" |
실제 HTTP 경로(예: "/my-target-name/invocations") |
|
httpMethod |
변경 불가능 |
변경 불가능 |
|
rawGatewayRequest |
포함 |
포함되지 않음 |
|
응답 인터셉터 |
지원됨 |
버퍼링 모드에서 지원됨(스트리밍 모드에서는 아직 지원되지 않음) |
