AgentCore 게이트웨이에서 샘플링 사용
샘플링은 MCP 서버가 도구 호출 중에 클라이언트로부터 LLM 완료를 요청할 수 있는 MCP 기능입니다. 이를 통해 서버는 언어 모델에 직접 액세스할 필요 없이 AI 기능을 활용할 수 있습니다. 클라이언트는 모델 호출을 처리하고 결과를 반환합니다. AgentCore Gateway는 MCP 서버 대상의 샘플링 요청을 클라이언트로 전달하여 요청을 게이트웨이 생성 식별자id로 바꿉니다.
사전 조건
게이트웨이에서 샘플링을 사용하려면:
-
세션 활성화됨 - 샘플링에는 세션 지원이 필요합니다. 게이트웨이에서 MCP 세션 사용을 참조하세요.
-
응답 스트리밍 활성화됨 - 샘플링 요청은 열린 연결 중에 SSE 청크로 전송됩니다. 게이트웨이의
true에서를streamingConfiguration.enableResponseStreaming로 설정합니다protocolConfiguration.mcp. -
MCP 서버 대상 유형 - 샘플링 요청은 MCP 서버 대상에서 비롯됩니다.
-
클라이언트가 샘플링 기능 선언 - 클라이언트는
initialize요청 중에 샘플링에 대한 지원을 선언해야 합니다. 게이트웨이는이 기능을 선언한 클라이언트에만 샘플링 요청을 전달합니다.
샘플링 작동 방식
MCP 서버 대상은 도구 실행 중에 LLM 완료가 필요한 경우 sampling/createMessage 요청을 전송합니다. 게이트웨이는이 요청을 SSE 이벤트로 클라이언트에 전달하여 요청을 교체합니다id. 클라이언트는 언어 모델을 호출하고 결과를 게이트웨이로 다시 전송하여 대상에 전달합니다.
샘플링 요청에는 다음이 포함됩니다.
-
messages- 모델에 보낼 대화 메시지입니다. -
modelPreferences- 원하는 모델 기능(지능성, 속도, 비용)에 대한 선택적 힌트입니다. -
systemPrompt- 모델에 대한 선택적 시스템 프롬프트입니다. -
maxTokens- 생성할 최대 토큰 수입니다.
클라이언트는 다음과 같이 응답합니다.
-
model- 사용된 모델입니다. -
role- 항상assistant. -
content- 생성된 콘텐츠(텍스트 또는 이미지).
참고
클라이언트는 사용할 모델과 요청을 처리하는 방법을 완전히 제어할 수 있습니다. 서버의 힌트modelPreferences는 요구 사항이 아닙니다. 클라이언트는 자체 정책에 따라 요청을 수정하거나 거부할 수도 있습니다.
샘플링 흐름
-
클라이언트는
Mcp-Session-Id헤더와 함께tools/call요청을 보냅니다. -
Gateway는 도구 호출을 MCP 서버 대상으로 전달합니다.
-
대상이 SSE 스트림을 열고
sampling/createMessage요청을 보냅니다. -
Gateway는 샘플링 요청을 SSE 이벤트로 클라이언트에 전달하여 요청을 교체합니다
id. -
클라이언트는 제공된 메시지로 언어 모델을 호출합니다.
-
클라이언트는 게이트웨이의 요청
id에서 동일한Mcp-Session-Id및를 사용하여 샘플링 결과와 함께 새 요청을 보냅니다. -
Gateway는 결과를 MCP 서버 대상으로 전달합니다.
-
대상이 처리를 계속하고 최종 도구 결과를 반환합니다.
-
Gateway는 최종 결과를 클라이언트에 전달하고 스트림을 닫습니다.
MCP 서버 대상 개발자를 위한 지침
중요
샘플링 요청을 보내는 MCP 서버 대상은 샘플링 호출을 try-catch 블록으로 래핑하고 클라이언트가 샘플링을 지원하지 않는 경우를 처리해야 합니다. 게이트웨이의 클라이언트가 샘플링 기능을 선언하지 않은 경우 게이트웨이는 이를 대상으로 선언하지 않습니다. 대상이 샘플링 요청을 보내면 게이트웨이는 대상에 -32601 (메서드를 찾을 수 없음) 오류를 반환합니다.
샘플링을 사용할 수 없는 경우 서버는 대체 경로(예: 기본 제공 모델 사용 또는 AI 지원 단계 건너뛰기)를 구현해야 합니다.
오류 처리
| 시나리오 | 오류 | 설명 |
|---|---|---|
|
보류 중인 샘플링 요청이 없을 때 클라이언트가 샘플링 응답을 보냅니다. |
JSON-RPC |
이 세션에 대해 일치하는 샘플링 요청을 찾을 수 없습니다. |
|
클라이언트는 보류 중인 요청과 일치하지 |
JSON-RPC |
는 |
|
MCP 서버가 샘플링 요청을 보내지만 게이트웨이가 지원을 선언하지 않음 |
JSON-RPC |
MCP 서버 대상으로 반환됩니다. 문제 해결을 참조하세요. |
문제 해결
오류: "오류 호출 도구 'sample_tool': 메서드를 찾을 수 없음: sampling/createMessage"
이 오류는 MCP 서버 대상이 샘플링 요청을 보내지만 게이트웨이의 클라이언트가 중에 샘플링 기능을 선언하지 않은 경우에 발생합니다initialize. 게이트웨이는 -32601 (메서드를 찾을 수 없음) 오류를 대상에 반환하고 대상은 이를 도구 실행 오류로 클라이언트에 반환할 수 있습니다.
이 문제를 해결하려면:
-
MCP 서버 개발자인 경우: 샘플링 호출에 대한 오류 처리를 추가합니다. 샘플링이 지원되지 않는 경우 대체 경로를 구현합니다.
중요
create_message호출related_request_id=ctx.request_context.request_id에를 포함해야 합니다. 이는 게이트웨이가 샘플링 요청을 원래 도구 호출과 올바르게 연결하는 데 필요합니다. 그렇지 않으면 샘플링이 작동하지 않습니다.try: result = await ctx.session.create_message( messages=[{"role": "user", "content": {"type": "text", "text": "Summarize this document"}}], max_tokens=500, related_request_id=ctx.request_context.request_id, ) except Exception as e: # Fallback when client doesn't support sampling logger.warning(f"Sampling not supported: {e}") result = fallback_summarization(document) -
게이트웨이 클라이언트 개발자인 경우: 클라이언트가 중에 샘플링 기능을 선언하는지 확인합니다
initialize.{ "capabilities": { "sampling": {} } }
코드 샘플
참고
LangGraph MCP 클라이언트(langchain-mcp-adapters) 및 Strands MCP 클라이언트는 현재 샘플링을 지원하지 않습니다. 아래 표시된 MCP 클라이언트 접근 방식을 사용하여 게이트웨이의 샘플링 요청을 처리합니다.