AgentCore Gateway

AgentCore Gateway

에이전트가 바깥 세계에 접근하는 관문 — 연결이 아니라 통제가 본질

에이전트가 도구를 직접 호출하면

도구가 2개, 3개로 늘어나는 순간부터 시작되는 문제들

단일 진입점 구조

에이전트는 Gateway 하나만 바라보는 구조 — 도구 추가는 코드 변경 없는 Target 등록

3카테고리 Target

하나의 Gateway에 동시 등록 가능한 세 카테고리

MCP Targets — 도구 유형 6종

Gateway가 모든 MCP Target을 하나의 가상 MCP 서버로 집약 — tools/list 한 번으로 전체 발견

MCP vs HTTP Target

집약이냐 프록시냐 — 에이전트가 도구를 발견해야 하는지가 갈림길

Inference Targets — 모델 라우팅

에이전트에게는 단일 추론 엔드포인트 — 요청의 model 필드로 프로바이더를 자동 선택

Target 등록 — CLI와 콘솔

add는 설정, deploy가 프로비저닝 — 에이전트 코드는 그대로

핵심 포인트

agentcore add gateway-target

MCP/HTTP 도구 연결을 프로젝트에 추가 (AgentCore CLI)

add → deploy

add는 설정 파일만 갱신 — deploy가 실제 AWS 리소스를 프로비저닝

콘솔 위저드

Create Gateway 4단계 — Details → Inbound Identity → Add targets → Review

Target protocol 4종

콘솔 기준 MCP · Inference · Agent · Custom — Agent·Custom은 API의 http 카테고리에 대응

명령

# Gateway Target 추가 — MCP/HTTP 도구 연결
agentcore add gateway-target

# 필요한 부속 리소스도 같은 패턴으로
agentcore add credential   # Outbound OAuth 자격 증명 공급자

# add는 설정만 갱신 — deploy가 실제 리소스 생성
agentcore deploy

운영 기능

도구가 늘어날수록 빛나는 기능들 — 코드가 아니라 Gateway 설정으로 해결

Interceptor — 요청·응답 미들웨어

Target 앞뒤에서 Lambda가 가로채 변환 — 에이전트도 Target도 모르게

인터랙티브 MCP — 패스스루 4종

단순 도구 호출을 넘어 — 세션·스트리밍·역방향 상호작용도 그대로 통과

시맨틱 도구 검색

도구 이름을 몰라도 자연어로 — 빌트인 검색 도구가 관련 도구만 선별

1. 1
   검색 옵션 활성화

   Gateway 생성 시 시맨틱 검색 옵션을 켭니다. Default 리스팅 모드가 전제 조건입니다.

2. 2
   빌트인 도구 자동 등록

   x_amz_bedrock_agentcore_search 도구가 Gateway에 자동 등록됩니다.

3. 3
   자연어 쿼리

   에이전트가 이 도구를 tools/call로 호출 — "고객 정보 찾기"처럼 자연어로 검색합니다.

4. 4
   의미 매칭 반환

   도구 설명 임베딩과 의미 매칭해 관련 도구만 집계 반환 — getCustomerById라는 정확한 이름을 몰라도 찾습니다.

검색 장면 — 질의에서 랭킹까지

"고객 정보 찾기" 한 줄이 수백 개 도구에서 관련 도구만 골라내는 순간

리스팅 모드 — Default vs Dynamic

도구 목록 캐시와 실시간 조회 — 두 방식 사이의 선택

규모의 감각 — 쿼터

게이트웨이 하나가 감당하는 규모 — 시맨틱 검색이 필요한 이유

2중 인증 구조

들어오는 인증과 나가는 인증이 답하는 서로 다른 질문

Inbound authorizer 4종

create_gateway의 authorizerType — 누구를 들여보낼지 정하는 스위치

Outbound 인증 방식

Gateway가 Target에 접근하는 자격 — Target 종류에 따라 선택

Target 등록 — create_gateway_target

MCP 서버를 Gateway Target으로 등록 — 컨트롤 플레인 API 한 번이면 끝

핵심 포인트

bedrock-agentcore-control

리소스 관리(create_*)는 컨트롤 플레인 — 호출용 bedrock-agentcore와 혼동 주의

gatewayIdentifier

파라미터명 주의 — gatewayId가 아님

targetConfiguration

mcp / http / inference 중 하나 — mcpServer는 endpoint 필드 (url 아님)

credentialProviderConfigurations

필수 — Outbound 인증 방식 지정 (GATEWAY_IAM_ROLE 등)

코드

import boto3

# 컨트롤 플레인 클라이언트 — 리소스 생성·관리는 -control
client = boto3.client('bedrock-agentcore-control')
# 외부 MCP 서버를 Gateway Target으로 등록 — Outbound는 IAM Role
client.create_gateway_target(
    gatewayIdentifier="my-gateway-abc1234567",
    name="weather-mcp",
    targetConfiguration={
        'mcp': {
            'mcpServer': {'endpoint': 'https://mcp.example.com'}
        }
    },
    credentialProviderConfigurations=[
        {'credentialProviderType': 'GATEWAY_IAM_ROLE'}
    ],
)

에이전트에서 Gateway 도구 사용

Strands 에이전트가 알아야 할 것은 Gateway MCP 엔드포인트 하나뿐

핵심 포인트

MCPClient

생성자는 transport callable만 받음 — URL 직접 전달 금지

aws_iam_streamablehttp_client

mcp-proxy-for-aws의 SigV4 서명 transport — 무서명 streamable_http_client는 AWS_IAM Gateway가 거부

bedrock-agentcore:InvokeGateway

호출자 IAM 권한 — 엔드포인트는 {gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/mcp

tools=[gateway_tools]

MCPClient 직접 전달 — 연결 라이프사이클 자동 관리 (프로덕션 권장)

코드

from strands import Agent
from strands.tools.mcp import MCPClient
from mcp_proxy_for_aws import aws_iam_streamablehttp_client

# Gateway 연결 — SigV4 서명 transport (무서명 호출은 AWS_IAM에서 거부)
gateway_tools = MCPClient(
    lambda: aws_iam_streamablehttp_client(
        endpoint="https://my-gateway-abc1234567.gateway"
                 ".bedrock-agentcore.us-east-1.amazonaws.com/mcp",
        aws_region="us-east-1",
        aws_service="bedrock-agentcore",
    )
)

# 모든 MCP Target의 도구가 자동 발견됨
agent = Agent(
    system_prompt="식당 추천 전문가",
    tools=[gateway_tools],
)
result = agent("강남에서 이탈리안 레스토랑 추천해줘")