콘텐츠로 이동

AgentCore Gateway

Filter this guidePick generator option values to hide sections that don't apply.

Amazon Bedrock AgentCore Gateway 프로젝트를 생성합니다. AgentCore Gateway는 MCP 서버 또는 에이전트 앞에 있는 관리형 진입점으로, 인바운드 요청을 인증하고(IAM 또는 Cognito) 대상으로 가는 아웃바운드 트래픽에 IAM SigV4로 서명합니다.

protocol 옵션은 Gateway가 무엇을 앞에 두는지 선택합니다:

  • mcp (기본값) — 하나 이상의 MCP 서버 대상을 단일 MCP 엔드포인트 뒤에 집계하고, 모든 도구 호출을 Cedar 정책 엔진에 대해 평가합니다.
  • http — 경로 기반 라우팅(/<targetName>/invocations)을 통해 AgentCore Runtime 대상(사용자의 에이전트)으로 요청을 직접 프록시하며, 집계나 프로토콜 변환 없이 수행합니다. 이를 사용하여 단일 관리형 엔드포인트로 에이전트를 앞에 두세요 — 예를 들어 웹사이트가 Gateway를 통해 VPC 내부에 배포된 에이전트에 도달할 수 있도록 합니다.
Terminal window
pnpm nx g @aws/nx-plugin:agentcore-gateway
어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다
Terminal window
pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run
매개변수타입기본값설명
name 필수string-AgentCore Gateway 프로젝트의 이름
directory stringpackages게이트웨이 프로젝트가 배치되는 상위 디렉토리입니다.
subDirectory string-프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.
protocol mcp | httpmcp게이트웨이가 노출하는 인바운드 프로토콜입니다. mcp 게이트웨이는 MCP 서버 대상을 단일 MCP 엔드포인트로 집계합니다. http 게이트웨이는 경로 기반 라우팅을 통해 에이전트 런타임 대상으로 요청을 프록시하므로, 호출자(예: 웹사이트)가 게이트웨이를 통해 에이전트에 접근할 수 있습니다.
auth iam | cognitoiam게이트웨이로 들어오는 요청을 인증하는 데 사용되는 방법입니다. 현재는 iam만 지원되며, 향후 cognito 및 custom-jwt가 추가될 수 있습니다.
cedarPolicy booleantrue게이트웨이에서 세밀한 권한 부여를 적용하는 Cedar 정책 엔진을 포함할지 여부입니다.
infra agentcore | noneagentcore게이트웨이를 호스팅할 인프라 유형입니다. 호스팅하지 않으려면 none을 선택하세요.
iac inherit | cdk | terraforminherit선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
preferInstallDependencies booleantrue생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

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

  • 디렉터리packages/<name>/
    • 디렉터리policies/ Cedar 정책 소스 파일 (mcp 프로토콜만 해당; cedarPolicy: false일 때 생략됨)
      • permit-all.cedar 인증된 호출자를 허용하는 기본 Cedar 정책
      • README.md Cedar 정책 작성 참조
    • local-dev.ts 로컬 개발을 위한 로컬 게이트웨이 — 연결된 MCP 서버(mcp) 집계 또는 연결된 에이전트(http) 프록시
    • project.json servedev 타겟 추가

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

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

  • 디렉터리packages/common/constructs
    • 디렉터리src
      • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
      • 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
      • index.ts app에서 constructs를 내보내는 진입점
    • project.json 프로젝트 빌드 타겟 및 구성
  • 디렉터리packages/common/constructs/src
    • 디렉터리core
      • 디렉터리agentcore-gateway/ 공유 게이트웨이 구성 요소 (준비 상태 프로브, Cedar 정책 로딩)
    • 디렉터리app
      • 디렉터리gateways
        • 디렉터리<name>/
          • <name>.ts Gateway 배포를 위한 CDK 구성 요소

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

  • 인바운드 IAM 인증(기본값) 또는 Cognito JWT 인증(인증 참조)이 있는 AgentCore::Gateway. mcp 게이트웨이는 MCP 프로토콜로 구성되며, http 게이트웨이는 프로토콜 유형이 없으며, 이는 AgentCore가 런타임 대상에 필요로 합니다
  • ENFORCE 모드에서 실행되는 AgentCore::PolicyEngine, Gateway에 연결됨 (mcp 게이트웨이만 해당; cedarPolicy: false일 때 생략됨)
  • policies/.cedar 파일당 하나의 AgentCore::Policy (mcp 게이트웨이만 해당)
  • Gateway와 연결된 AWS WAFv2 Web ACL, CloudWatch로 요청 로깅 (기본적으로 활성화됨 — AWS WAF 참조)

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

배포된 Gateway는 다음 아키텍처를 가지며, Gateway 앞에 AWS WAFv2 Web ACL이 있고, 다운스트림 MCP 서버 대상으로 라우팅합니다:

ClientWAFAgentCore Gateway(MCP, IAM or Cognito auth)Downstream MCP Servers(Gateway targets)

auth 옵션은 Gateway가 인바운드 요청을 인증하는 방법을 구성합니다. iam(기본값)과 cognito 중에서 선택하세요.

기본적으로 Gateway는 GatewayAuthorizer.usingAwsIam()으로 구성됩니다. 호출자는 SigV4로 요청에 서명하고, 호출자의 IAM 자격 증명은 AgentCore::IamEntity 주체로 Cedar 정책에서 사용할 수 있습니다. 이는 호출자가 AWS에서 실행되는 에이전트 또는 서비스일 때 권장되는 옵션입니다 — 예를 들어 에이전트에서 Gateway로의 연결 생성기를 통해 연결된 에이전트는 자체 실행 역할로 호출에 서명합니다.

cognito를 선택하면 Gateway는 Cognito 사용자 풀을 가리키는 Custom JWT 권한 부여자로 구성됩니다. 호출자는 JWT 베어러 토큰을 제시하여 인증하고, 토큰의 sub 클레임은 AgentCore::OAuthUser 주체로 Cedar 정책에서 사용할 수 있습니다. 호출자가 Cognito를 통해 인증할 때 이를 사용하세요 — 예를 들어 ts#dcr-proxy 생성기를 통해 연결하는 웹사이트 또는 코딩 에이전트.

생성된 인프라는 기존 Cognito 사용자 풀과 클라이언트를 사용합니다 — 생성하지 않습니다. ts#website#auth 생성기를 사용하여 UserIdentity를 생성하거나 직접 제공할 수 있습니다.

생성된 구성 요소는 사용자 풀과 클라이언트를 제공하는 identity prop이 필요합니다:

packages/infra/src/stacks/application-stack.ts
import { MyGateway, UserIdentity } from ':my-scope/common-constructs';
export class ApplicationStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
const identity = new UserIdentity(this, 'Identity');
new MyGateway(this, 'MyGateway', {
identity,
});
}
}
cedarPolicy = true

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

전체 참조는 AgentCore Gateway 정책에 대한 AWS 문서를 참조하세요. 일반적인 정책 패턴도 포함되어 있습니다.

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

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

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

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

정책은 EJS 템플릿으로, 합성/계획 시점에 렌더링되어 계정 및 Gateway 재배포 간에 이식 가능하게 유지됩니다:

변수대체되는 값
<%= gatewayArn %>배포된 Gateway의 ARN
<%= accountId %>이 Gateway가 배포된 AWS 계정

항상 하드코딩된 값 대신 이러한 변수를 참조하세요.

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

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),
},
});

PolicyEngineENFORCE 모드에서 실행되며, 이는 기본 거부 의미론이 적용됨을 의미합니다: (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이 하나 이상 있는 도구만 볼 수 있도록 합니다: 에이전트가 특정 도구에 대한 권한이 없으면 도구가 나타나서 호출 시 실패하는 대신 완전히 숨겨집니다.

생성기는 Gateway의 인증 유형에 범위가 지정된 기본 정책을 제공합니다.

IAM Gateway의 경우, Gateway가 배포된 AWS 계정의 모든 IAM 호출자를 허용합니다:

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

Cognito Gateway의 경우, 인증된 모든 OAuth 사용자를 허용합니다(JWT 권한 부여자가 정책이 평가되기 전에 이미 토큰의 사용자 풀과 클라이언트를 검증했습니다):

packages/<name>/policies/permit-all.cedar
permit (
principal is AgentCore::OAuthUser,
action,
resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

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

주체 유형은 Gateway가 호출자를 인증하는 방법에 따라 달라집니다(인증 참조).

IAM Gateway의 경우, 호출자는 IAM 주체입니다:

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를 예약하세요.

Cognito Gateway의 경우, 호출자는 JWT 토큰의 sub 클레임에서 구축된 OAuth 사용자이며, JWT 클레임(사용자 이름, 범위 등)은 주체 태그로 사용할 수 있습니다:

principal is AgentCore::OAuthUser

when 절에서 개별 클레임을 일치시키세요 — 예를 들어 범위를 요구하려면:

permit (
principal is AgentCore::OAuthUser,
action,
resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
principal.scope == "gateway/invoke"
};

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

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

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

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

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

생성된 인프라는 IGNORE_ALL_FINDINGS로 정책을 생성합니다: AgentCore의 Cedar 분석기(FAIL_ON_ANY_FINDINGS, 서비스 기본값)는 많은 합법적인 정책을 거부합니다 — 예를 들어, 모든 호출자에 대해 단일 도구를 비활성화하는 forbidwhen 절로 범위가 지정되어 있어도 “Overly Restrictive”로 거부됩니다. 적용은 영향을 받지 않습니다. 정책 엔진의 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를 평가합니다):

packages/<name>/policies/forbid-divide-for-py-agent.cedar
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를 실행합니다. 이를 실행하면 로컬 게이트웨이와 연결된 모든 대상이 함께 시작됩니다:

Terminal window
pnpm nx dev <name>
protocol = mcp

로컬 게이트웨이는 연결된 모든 MCP 서버(agentcore-gateway#mcp-connection 생성기를 통해 연결됨)를 집계하는 단일 MCP 엔드포인트를 노출하며, 도구는 배포된 Gateway와 일치하도록 <target>___<tool>로 접두사가 붙습니다.

protocol = http

로컬 게이트웨이는 /<targetName>/... 경로를 각 연결된 에이전트의 로컬 서버(agentcore-gateway#agent-connection 생성기를 통해 연결됨)로 프록시하며, 배포된 Gateway의 경로 기반 라우팅과 일치합니다.

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

AgentCore Gateway 생성기는 선택한 iac를 기반으로 CDK 또는 Terraform 인프라 코드를 생성합니다. 이를 사용하여 Gateway를 배포할 수 있습니다.

Gateway 배포를 위한 CDK 구성 요소는 common/constructs 폴더에 있습니다. 이를 CDK 애플리케이션에서 사용할 수 있습니다. 예를 들어:

packages/infra/src/stacks/application-stack.ts
import { MyGateway } from '@my-scope/common-constructs';
export class ApplicationStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new MyGateway(this, 'MyGateway');
}
}

이것은 AgentCore::Gateway, Cedar PolicyEngine, AWS WAF Web ACL을 포함한 Gateway 인프라를 설정합니다(아래 AWS WAF 참조). gateway.addMcpServer(...)로 MCP 서버 대상을 등록하세요 — MCP 서버 연결 가이드를 참조하세요.

기본적으로 생성된 구성 요소는 AWS WAFv2 Web ACL을 Gateway와 연결합니다. AWS WAF는 대상에 도달하기 전에 모든 인바운드 요청을 인라인으로 검사하여 웹 익스플로잇, 봇 트래픽 및 볼륨 공격으로부터 Gateway를 보호합니다. Web ACL은 AWS 관리형 기본 규칙 세트(AWSManagedRulesCommonRuleSetAWSManagedRulesKnownBadInputsRuleSet)를 사용하여 OWASP Top 10을 포함한 일반적인 웹 익스플로잇에 대한 보호를 제공합니다. WAF 요청 로그는 CloudWatch Logs 그룹에 기록됩니다.

Web ACL은 REGIONAL이며 AgentCore Gateway 연결에 필요한 대로 Gateway의 리전에 생성됩니다.

생성된 Gateway 구성 요소를 편집하여 규칙을 추가, 제거 또는 조정할 수 있습니다(예: 속도 기반 규칙 또는 추가 관리형 규칙 그룹 추가).

옵트아웃하려면(예: 자체 Web ACL을 연결하려면) Gateway 구성 요소를 인스턴스화할 때 enableWaffalse로 설정하세요:

new MyGateway(this, 'MyGateway', {
enableWaf: false,
});

구성 요소는 추가 구성을 위해 생성된 Web ACL을 webAcl로 노출합니다.

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

Amazon Bedrock AgentCore GatewayModel Context Protocol
AgentCore Gateway to MCP ServerAgentCore Gateway 뒤에 MCP 서버 집계
Amazon Bedrock AgentCore GatewayAmazon Bedrock AgentCore Gateway
AgentCore Gateway to AgentCore Gateway다른 AgentCore Gateway 뒤에 AgentCore Gateway 집계
Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
TypeScript Agent to AgentCore GatewayTypeScript Agent를 AgentCore Gateway에 연결
Strands AgentsPythonAmazon Bedrock AgentCore Gateway
Python Agent to AgentCore GatewayPython Agent를 AgentCore Gateway에 연결
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to Agent런타임 대상으로 AgentCore Gateway로 에이전트 앞에 두기
Amazon Bedrock AgentCore Gateway
React Website to AgentCore GatewayAgentCore Gateway를 통해 React 웹사이트를 에이전트에 연결