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의 실행 역할을 인증합니다.

사전 요구 사항

이 생성기를 사용하기 전에 다음을 확인하세요:

두 개의 agentcore-gateway 프로젝트

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

사용법

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

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

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

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

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

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

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

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

옵션

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

생성기 출력

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

디렉터리packages/<source-gateway>
- project.json <source-gateway>-serve-local이 대상 게이트웨이의 <target-gateway>-serve-local에 대한 종속성을 얻습니다
- serve-local.ts ATTACHED_MCP_SERVERS가 업데이트되어 로컬 게이트웨이가 대상 게이트웨이를 집계합니다

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

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

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

CDK
Terraform

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

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는 생성 중에 대상의 도구를 가져오므로 대상은 대상 게이트웨이와 모든 자체 대상 이후에 생성됩니다.

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

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

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 정책이 대상이 등록한 후에 생성되도록 보장합니다.

체인 게이트웨이 간 Cedar 정책

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

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

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

로컬 개발

다음을 사용하여 소스 Gateway를 로컬에서 실행:

pnpm nx dev <source-gateway-name>

yarn nx dev <source-gateway-name>

npx nx dev <source-gateway-name>

bunx nx dev <source-gateway-name>

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