AgentCore Gateway에서 AgentCore Gateway로

connection 생성기는 AgentCore Gateway를 다른 AgentCore Gateway의 대상으로 등록할 수 있습니다. 이를 통해 게이트웨이를 계층적으로 구성할 수 있습니다. 예를 들어 팀 수준 게이트웨이가 여러 도메인 게이트웨이를 집계하고, 각 도메인 게이트웨이는 자체 MCP 서버를 프론트하는 구조입니다.

연결되면 소스 Gateway는 대상 Gateway의 도구를 단일 MCP 엔드포인트로 집계합니다. 대상 Gateway는 이미 자체 대상 이름으로 도구에 접두사를 붙이므로, 소스 Gateway를 통해 도구가 <gateway-target-name>___<target-name>___<tool-name>으로 표시됩니다. 체인의 각 게이트웨이는 하나의 접두사를 추가합니다. 두 게이트웨이 모두 자체 Cedar 정책을 평가합니다. 소스 Gateway는 접두사가 붙은 작업에 대해 호출자를 인증하고, 대상 Gateway는 내부 작업에 대해 소스 Gateway의 실행 역할을 인증합니다.

전제 조건

이 생성기를 사용하기 전에 다음이 필요합니다:

1. 두 개의 agentcore-gateway 프로젝트

두 게이트웨이 모두 protocol: mcp를 가져야 하며, 대상 게이트웨이는 auth: iam을 가져야 합니다. 소스 게이트웨이는 자체 실행 역할로 서명하여 대상을 호출하므로 대상의 인바운드 인증만 IAM이어야 합니다. 생성기는 이를 검증하며, 게이트웨이 간에 순환을 생성하는 연결도 거부합니다. 순환이 있으면 tools/list에서 무한 재귀가 발생합니다.

사용법

생성기 실행

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

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

집계하는 Gateway 프로젝트를 소스로 선택하고 집계될 Gateway를 대상으로 선택합니다.

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

생성기는 새 소스 파일을 생성하는 대신 기존 프로젝트를 연결합니다. 다음 파일이 수정됩니다:

• 디렉터리packages/<source-gateway>

  • project.json 소스 Gateway의 dev 대상이 대상 게이트웨이의 dev 대상에 대한 종속성을 얻습니다
  • local-dev.ts ATTACHED_MCP_SERVERS가 업데이트되어 로컬 게이트웨이가 대상 게이트웨이를 집계합니다

소스 Gateway 프로젝트의 dev 대상은 대상 Gateway의 dev 대상에 대한 종속성을 얻으므로, 소스 Gateway를 로컬에서 실행하면 대상 게이트웨이(및 전이적으로 연결된 모든 MCP 서버)도 시작됩니다. 대상 게이트웨이는 소스 Gateway 프로젝트의 local-dev.ts에도 등록되어 로컬 게이트웨이가 해당 도구를 집계합니다.

스택에 게이트웨이 대상 추가

생성기는 Gateway를 인스턴스화하는 스택이나 모듈을 알 수 없기 때문에 게이트웨이 대상을 인프라에 자동으로 연결할 수 없습니다. gateway.addGateway(targetGateway) 호출을 직접 추가하세요.

CDK

Gateway를 인스턴스화하는 스택에서 대상 게이트웨이를 소스 게이트웨이의 대상으로 등록합니다:

packages/infra/src/stacks/application-stack.ts

const innerGateway = new InnerGateway(this, 'InnerGateway');
const outerGateway = new OuterGateway(this, 'OuterGateway');

// Register the inner gateway as a target of the outer gateway. The target
// name defaults to the inner gateway's `gatewayName` (its class name in
// kebab-case, e.g. `InnerGateway` -> `inner-gateway`).
outerGateway.addGateway(innerGateway);

Gateway 대상 이름(기본적으로 대상 게이트웨이의 gatewayName)은 소스 게이트웨이의 Cedar 작업 이름에 접두사를 붙입니다. 작업 형식은 AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>"입니다. 정책 작성 섹션을 참조하세요. 대상 이름을 짧고 안정적으로 유지하세요. 나중에 변경하면 이전 이름을 참조하는 모든 Cedar 정책이 무효화됩니다.

기본 대상 이름을 재정의하려면 gatewayTargetName을 전달하세요:

outerGateway.addGateway(innerGateway, { gatewayTargetName: 'inner' });

구성은 소스 게이트웨이의 실행 역할에 대상 게이트웨이에 대한 bedrock-agentcore:InvokeGateway 액세스 권한을 부여하고, 소스 게이트웨이가 자체 실행 역할을 사용하여 아웃바운드 호출에 서명하도록 대상을 iamCredentialProvider.service = 'bedrock-agentcore'로 구성합니다. AgentCore는 생성 중에 대상의 도구를 가져오므로 대상은 대상 게이트웨이와 모든 자체 대상 이후에 생성됩니다.

Terraform

Gateway를 인스턴스화하는 Terraform 파일에서 게이트웨이 대상을 연결합니다:

packages/infra/src/main.tf

module "inner_gateway" {
  source = "../../common/terraform/src/app/gateways/inner-gateway"

  # Target ids of the inner gateway's own targets (e.g. its MCP servers), so
  # its gateway_url is not consumed until it serves their tools.
  tool_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

module "outer_gateway" {
  source              = "../../common/terraform/src/app/gateways/outer-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.inner_gateway.target_id]

  additional_iam_policy_statements = [
    {
      Effect   = "Allow"
      Action   = ["bedrock-agentcore:InvokeGateway"]
      Resource = [module.inner_gateway.gateway_arn]
    }
  ]
}

# Register the inner gateway as a target of the outer gateway
resource "aws_bedrockagentcore_gateway_target" "inner_gateway" {
  gateway_identifier = module.outer_gateway.gateway_id
  name               = "inner-gateway"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.inner_gateway.gateway_url
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

대상 name(위의 inner-gateway)은 외부 게이트웨이의 Cedar 작업 이름에 접두사를 붙입니다. 정책 작성 섹션을 참조하세요. additional_iam_policy_statements 항목은 외부 게이트웨이의 실행 역할에 내부 게이트웨이에 대한 호출 액세스 권한을 부여합니다. 이는 대상 생성 시 내부 게이트웨이의 도구를 가져오고 런타임에 호출을 라우팅하는 데 모두 필요합니다. policy_dependencies는 이 대상의 작업을 참조하는 Cedar 정책이 대상이 등록한 후에 생성되도록 보장합니다.

대상 순서

AgentCore는 aws_bedrockagentcore_gateway_target이 생성될 때 내부 게이트웨이의 도구를 가져오므로, 내부 게이트웨이는 이미 도구를 제공하고 있어야 합니다. 내부 게이트웨이의 tool_dependencies를 자체 대상의 ID로 설정하세요. 그러면 gateway_url이 tools/list를 폴링하는 준비 프로브를 통해 흐르므로, 외부 게이트웨이의 대상은 내부 게이트웨이가 준비될 때까지 기다립니다.

체인 게이트웨이 간 Cedar 정책

체인의 각 게이트웨이는 자체 정책 세트를 평가합니다:

1. 소스 게이트웨이는 원래 호출자(예: 에이전트의 실행 역할)를 접두사가 붙은 작업(예: AgentCore::Action::"inner-gateway___my-mcp___add")에 대해 평가합니다.
2. 대상 게이트웨이는 소스 게이트웨이의 실행 역할을 내부 작업(예: AgentCore::Action::"my-mcp___add")에 대해 평가합니다.

즉, 게이트웨이 체인을 통한 도구 호출은 모든 홉에서 허용되어야 합니다. 기본 permit-all.cedar는 동일한 AWS 계정의 모든 호출자를 허용하며, 여기에는 소스 게이트웨이의 역할이 포함됩니다. 대상 게이트웨이에 더 좁은 정책을 작성하는 경우, 대상 게이트웨이가 보는 주체는 원래 호출자가 아니라 소스 게이트웨이의 역할임을 기억하세요.

로컬 개발

다음 명령으로 소스 Gateway를 로컬에서 실행하면:

pnpm

pnpm nx dev <source-gateway-name>

yarn

yarn nx dev <source-gateway-name>

npm

npx nx dev <source-gateway-name>

bun

bunx nx dev <source-gateway-name>

로컬 소스 게이트웨이, 로컬 대상 게이트웨이 및 둘 중 하나에 연결된 모든 MCP 서버가 각각 할당된 로컬 포트에서 시작됩니다. 도구 이름은 배포된 것과 정확히 동일하게 각 홉에서 접두사가 붙으므로(<gateway-target-name>___<target-name>___<tool-name>), 에이전트 프롬프트와 Cedar 작업 이름이 로컬 및 배포된 실행 간에 일관성을 유지합니다.

로컬 충실도

로컬 개발은 로컬 대체 게이트웨이를 사용합니다. 이는 각 Gateway 프로젝트에서 시작되는 경량 MCP 집계기이며 AgentCore Gateway 서비스가 아닙니다. 결과적으로 Cedar 정책은 로컬에서 평가되지 않습니다. Cedar 정책을 실행하려면 에이전트의 serve 대상을 대신 실행하세요(TypeScript / Python 에이전트 연결 가이드 참조). 그러면 로컬에서 실행되는 에이전트가 배포된 Gateway를 호출합니다.