AgentCore Gateway

Amazon Bedrock AgentCore Gateway 프로젝트를 생성합니다. AgentCore Gateway는 하나 이상의 MCP 서버 대상을 단일 MCP 엔드포인트 뒤에 집계하고, Cedar 정책 엔진에 대해 모든 도구 호출을 평가하며, MCP 서버로의 아웃바운드 트래픽에 IAM SigV4로 서명하는 관리형 진입점입니다.

사용법

AgentCore Gateway 생성

VSCode
CLI

설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
VSCode에서 Nx 콘솔 열기
클릭 Generate (UI) "Common Nx Commands" 섹션에서
검색 @aws/nx-plugin - agentcore-gateway
필수 매개변수 입력
클릭 Generate

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn nx g @aws/nx-plugin:agentcore-gateway

npx nx g @aws/nx-plugin:agentcore-gateway

bunx nx g @aws/nx-plugin:agentcore-gateway

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

옵션

매개변수	타입	기본값	설명
name 필수	string	-	AgentCore Gateway 프로젝트의 이름
directory	string	packages	게이트웨이 프로젝트가 배치되는 상위 디렉토리입니다.
subDirectory	string	-	프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.
protocol	mcp	mcp	게이트웨이에서 노출되는 인바운드 프로토콜입니다. 현재는 mcp만 지원되며, 향후 추가 프로토콜이 추가될 수 있습니다.
auth	iam	iam	게이트웨이로 들어오는 요청을 인증하는 데 사용되는 방법입니다. 현재는 iam만 지원되며, 향후 cognito 및 custom-jwt가 추가될 수 있습니다.
cedarPolicy	boolean	true	게이트웨이에서 세밀한 권한 부여를 적용하는 Cedar 정책 엔진을 포함할지 여부입니다.
infra	agentcore \| none	agentcore	게이트웨이를 호스팅할 인프라 유형입니다. 호스팅하지 않으려면 none을 선택하세요.
iac	inherit \| cdk \| terraform	inherit	선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

생성기 출력

생성기는 packages/<name>/에 새 프로젝트를 생성하며, 인프라를 위한 CDK 구성 요소 또는 Terraform 모듈을 추가합니다:

디렉터리packages/<name>/
- 디렉터리policies/ Cedar 정책 소스 파일 (cedarPolicy: false일 때 생략됨)
  - permit-all.cedar 동일한 AWS 계정 내에서 인증된 호출자를 허용하는 기본 Cedar 정책
  - README.md Cedar 정책 작성 참조
- local-dev.ts 로컬 개발을 위해 연결된 MCP 서버를 집계하는 로컬 게이트웨이
- project.json serve 및 dev 대상 추가

인프라

인프라는 infra가 agentcore(기본값)일 때 생성됩니다. infra: none을 사용하면 인프라가 생성되지 않습니다 — 나중에 infra: agentcore로 생성기를 다시 실행하여 추가할 수 있습니다.

이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

CDK
Terraform

디렉터리packages/common/constructs
- 디렉터리src
  - 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소
    …
  - 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소
    …
  - index.ts app의 구축 요소를 익스포트하는 진입점
- project.json 프로젝트 빌드 대상 및 구성

디렉터리packages/common/terraform
- 디렉터리src
  - 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈
    …
  - 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈
    …
- project.json 프로젝트 빌드 대상 및 구성

CDK
Terraform

디렉터리packages/common/constructs/src
- 디렉터리core
  - 디렉터리agentcore-gateway/ 공유 게이트웨이 구성 요소 (준비 상태 프로브, Cedar 정책 로딩)
    …
- 디렉터리app
  - 디렉터리gateways
    디렉터리<name>/
    <name>.ts Gateway 배포를 위한 CDK 구성 요소

생성된 구성 요소는 다음 AWS 리소스를 생성합니다:

GatewayAuthorizer.usingAwsIam()(인바운드 IAM 인증)을 사용하여 MCP 프로토콜용으로 구성된 AgentCore::Gateway
Gateway에 연결되어 ENFORCE 모드로 실행되는 AgentCore::PolicyEngine (cedarPolicy: false일 때 생략됨)
policies/의 .cedar 파일당 하나의 AgentCore::Policy

Gateway URL은 런타임 구성의 agentcore.gateways.<ClassName> 네임스페이스에 자동으로 등록되어 에이전트가 런타임에 이를 발견할 수 있습니다.

정책 작성

Cedar는 AgentCore Gateway가 도구 호출을 승인하는 데 사용하는 정책 언어입니다. Gateway를 통과하는 모든 tools/list 및 tools/call 요청은 연결된 정책 세트에 대해 평가되며, 요청이 성공하려면 호출자에게 최소한 하나의 일치하는 permit 문(그리고 일치하는 forbid가 없어야 함)이 있어야 합니다.

공통 정책 패턴을 포함한 전체 참조는 AgentCore Gateway 정책에 대한 AWS 문서를 참조하세요.

정책 추가

정책을 추가하려면 permit-all.cedar 옆에 새 .cedar 파일을 생성하세요. policies/의 각 .cedar 파일은 정확히 하나의 permit 또는 forbid 문을 포함해야 하며 단일 AWS::BedrockAgentCore::Policy 리소스로 배포됩니다. 정책 리소스의 이름은 파일 이름에서 파생됩니다: permit-all.cedar는 PermitAll이 됩니다(kebab/snake-case는 PascalCase로 변환됨). 여러 문을 포함하는 파일은 배포 시 unexpected token 'forbid' 오류를 생성하므로 별도의 파일로 분할하세요.

예를 들어, 특정 에이전트 역할만 특정 도구를 호출하도록 허용하려면 다음을 생성하세요:

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

역할 이름을 하드코딩하지 말고 템플릿 변수로 전달하세요(아래 템플릿 변수 참조). 새 정책을 배포하려면 재합성(re-synth) 또는 재계획(re-plan)하세요.

템플릿 변수

정책은 계정 및 Gateway 재배포 간에 이식 가능하도록 합성/계획 시점에 렌더링되는 EJS 템플릿입니다:

변수	치환 대상
`<%= gatewayArn %>`	배포된 Gateway의 ARN
`<%= accountId %>`	이 Gateway가 배포된 AWS 계정

값을 하드코딩하지 말고 항상 이러한 변수를 참조하세요.

자체 변수 추가

위의 ts-agent-divide.cedar 예제에 에이전트의 실행 역할 이름을 전달하는 등 정책이 렌더링되는 위치에 새 변수를 추가하세요:

CDK
Terraform

packages/common/constructs/src/app/gateways/<name>/<name>.ts에서 공유 구성 요소에 cedarPolicyVariables를 전달하세요:

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

packages/common/terraform/src/app/gateways/<name>/<name>.tf에서 rendered_policies 데이터 소스의 query에 추가하세요:

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

ENFORCE 모드 및 기본 거부

PolicyEngine은 ENFORCE 모드로 실행되며, 이는 기본 거부 의미론이 적용됨을 의미합니다: (principal, action, resource) 튜플과 일치하는 permit 문이 없으면 요청이 거부됩니다. 거부된 도구 호출은 다음을 반환합니다:

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

또한 Gateway는 tools/list의 응답을 필터링하여 호출자가 최소한 하나의 일치하는 permit이 있는 도구만 볼 수 있도록 합니다: 에이전트가 특정 도구에 대한 권한이 없으면 도구가 나타나서 호출 시 실패하는 대신 완전히 숨겨집니다.

기본 `permit-all.cedar`

생성기는 Gateway가 배포된 AWS 계정의 모든 IAM 호출자를 허용하는 기본 정책을 제공합니다:

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

더 엄격하게 제한하려면 그 옆에 더 좁은 정책을 추가하세요. 정책 세트에 최소한 하나의 일치하는 permit을 항상 유지하세요. 그렇지 않으면 기본 거부가 모든 호출을 차단합니다.

정책 범위 참조

이 플러그인으로 생성된 Gateway의 경우 모든 호출자는 IAM 주체입니다(Gateway는 GatewayAuthorizer.usingAwsIam()으로 구성됨):

principal is AgentCore::IamEntity

호출자는 세션 이름이 제거된 STS assumed-role ARN으로 평가되므로 역할을 정확히 일치시킬 수 있습니다 — 와일드카드가 필요하지 않습니다:

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

동일한 값이 when 절에서 principal.id로 사용 가능합니다. 기본 permit-all.cedar의 계정 전체 일치와 같은 실제 패턴에 대해서는 like를 예약하세요.

도구 호출은 다음 형식의 작업으로 정책 엔진에 도달합니다:

AgentCore::Action::"<target-name>___<tool-name>"

여기서 <target-name>은 Gateway 대상 이름(gateway.addMcpServer(...)를 사용할 때 기본적으로 MCP 서버의 mcpServerName이며, MCP 프로젝트의 클래스 이름에서 kebab-case로 파생됨 — 예: TsMcp → ts-mcp)이고, <tool-name>은 MCP 도구의 이름이며, 구분자는 ___(밑줄 3개)입니다. Cedar는 작업에 대한 와일드카드를 지원하지 않습니다 — 정확한 작업을 일치시키거나 action ==을 생략하여 모든 작업을 일치시키세요.

리소스는 항상 Gateway 자체입니다:

resource == AgentCore::Gateway::"<%= gatewayArn %>"

검증 고려사항

생성된 인프라는 IGNORE_ALL_FINDINGS로 정책을 생성합니다: AgentCore의 Cedar 분석기(서비스 기본값인 FAIL_ON_ANY_FINDINGS)는 많은 정당한 정책을 거부합니다 — 예를 들어, 모든 호출자에 대해 단일 도구를 비활성화하는 forbid는 when 절로 범위가 지정되어 있어도 “Overly Restrictive”로 거부됩니다. 적용(enforcement)은 영향을 받지 않으며, 정책 엔진의 ENFORCE 모드로 구성됩니다.

한 가지 순서 제약 조건이 여전히 적용됩니다: AgentCore::Action::"<target>___<tool>"을 참조하는 정책은 대상이 Gateway에 해당 도구를 등록한 후에만 검증되므로, 생성된 인프라는 Gateway 대상 이후에 정책을 생성합니다.

정책 배포가 실패하면 CloudFormation은 거부를 불투명한 Resource stabilization failed 오류로 표시합니다 — aws bedrock-agentcore-control list-policies --policy-engine-id <id>를 실행하여 실제 이유를 포함하는 검증기의 statusReasons를 검색하세요.

예제: 더 광범위한 허용을 유지하면서 하나의 도구 금지

좁은 forbid를 더 광범위한 permit과 쌍을 이루세요(Cedar는 permit보다 forbid를 우선 평가함):

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

이것은 Python 에이전트 역할이 ts-mcp___divide를 호출하는 것을 거부하면서 다른 모든 호출자를 위해 더 광범위한 permit-all.cedar를 그대로 둡니다.

로컬 개발

생성기는 Gateway 프로젝트에 dev 대상을 추가하며, 이는 local-dev.ts를 실행합니다: 배포된 Gateway와 일치하도록 도구에 <target>___<tool> 접두사가 붙은 모든 연결된 MCP 서버(agentcore-gateway#mcp-connection 생성기를 통해 연결됨)를 집계하는 단일 MCP 엔드포인트를 노출하는 로컬 게이트웨이입니다. 이를 실행하면 로컬 게이트웨이와 모든 연결된 MCP 서버가 함께 시작됩니다:

pnpm nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

전체 로컬 개발 스토리는 연결 가이드를 참조하세요.

연결

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합할 수 있습니다. 다음은 이 프로젝트와 관련된 연결입니다:

AgentCore Gateway to MCP Server AgentCore Gateway 뒤에 MCP 서버 집계하기

AgentCore Gateway to AgentCore Gateway 다른 AgentCore Gateway 뒤에 AgentCore Gateway 집계하기

TypeScript Agent to AgentCore Gateway TypeScript Agent를 AgentCore Gateway에 연결하기

Python Agent to AgentCore Gateway Python Agent를 AgentCore Gateway에 연결하기

AgentCore Gateway

사용법