AgentCore Gateway đến AgentCore Gateway

Trình tạo connection có thể đăng ký một AgentCore Gateway làm mục tiêu của một AgentCore Gateway khác. Điều này cho phép bạn kết hợp các gateway theo cấu trúc phân cấp — ví dụ một gateway cấp nhóm tổng hợp nhiều gateway miền, mỗi gateway miền lại đứng trước các MCP server của riêng nó.

Sau khi được kết nối, Gateway nguồn sẽ tổng hợp các công cụ của Gateway mục tiêu vào một điểm cuối MCP duy nhất. Vì Gateway mục tiêu đã thêm tiền tố cho các công cụ của nó bằng tên mục tiêu riêng, các công cụ sẽ xuất hiện thông qua Gateway nguồn dưới dạng <gateway-target-name>___<target-name>___<tool-name> — mỗi gateway trong chuỗi thêm một tiền tố. Cả hai gateway đều đánh giá các chính sách Cedar của riêng chúng: Gateway nguồn ủy quyền cho người gọi đối với hành động có tiền tố, sau đó Gateway mục tiêu ủy quyền cho vai trò thực thi của Gateway nguồn đối với hành động bên trong.

Điều kiện tiên quyết

Trước khi sử dụng trình tạo này, hãy đảm bảo bạn có:

1. Hai dự án agentcore-gateway

Cả hai gateway phải có protocol: mcp, và gateway mục tiêu phải có auth: iam — gateway nguồn gọi mục tiêu bằng cách ký với vai trò thực thi của chính nó, vì vậy chỉ xác thực đầu vào của mục tiêu cần là IAM. Trình tạo xác thực điều này, và cũng từ chối các kết nối có thể tạo ra chu trình giữa các gateway, điều này sẽ đệ quy vô hạn trên tools/list.

Cách sử dụng

Chạy Trình tạo

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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

Chọn dự án Gateway tổng hợp làm nguồn và Gateway được tổng hợp làm mục tiêu.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Đầu ra của Trình tạo

Trình tạo kết nối các dự án hiện có với nhau thay vì tạo ra các tệp nguồn mới. Các tệp sau được sửa đổi:

• Thư mụcpackages/<source-gateway>

  • project.json mục tiêu dev của Gateway nguồn có thêm phụ thuộc vào mục tiêu dev của gateway mục tiêu
  • local-dev.ts ATTACHED_MCP_SERVERS được cập nhật để gateway cục bộ tổng hợp gateway mục tiêu

Mục tiêu dev của dự án Gateway nguồn có thêm phụ thuộc vào mục tiêu dev của Gateway mục tiêu, vì vậy việc chạy Gateway nguồn cục bộ cũng khởi động gateway mục tiêu (và theo cách bắc cầu, mọi MCP server được gắn vào nó). Gateway mục tiêu cũng được đăng ký trong local-dev.ts của dự án Gateway nguồn để gateway cục bộ tổng hợp các công cụ của nó.

Thêm mục tiêu gateway vào stack của bạn

Trình tạo không thể tự động kết nối mục tiêu gateway vào cơ sở hạ tầng của bạn vì nó không biết stack hoặc module nào khởi tạo các Gateway. Hãy tự thêm một lệnh gọi duy nhất gateway.addGateway(targetGateway).

CDK

Trong stack nơi bạn khởi tạo các Gateway, hãy đăng ký gateway mục tiêu làm mục tiêu của gateway nguồn:

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

Tên mục tiêu Gateway (gatewayName của gateway mục tiêu theo mặc định) là tiền tố cho tên hành động Cedar trên gateway nguồn — định dạng hành động là AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>". Xem phần Viết Chính sách. Giữ tên mục tiêu ngắn gọn và ổn định; thay đổi nó sau này sẽ làm mất hiệu lực bất kỳ chính sách Cedar nào tham chiếu đến tên cũ.

Để ghi đè tên mục tiêu mặc định, hãy truyền gatewayTargetName:

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

Construct cấp cho vai trò thực thi của gateway nguồn quyền truy cập bedrock-agentcore:InvokeGateway vào gateway mục tiêu, và cấu hình mục tiêu với iamCredentialProvider.service = 'bedrock-agentcore' để gateway nguồn ký các cuộc gọi đi bằng vai trò thực thi của chính nó. Mục tiêu được tạo sau gateway mục tiêu và tất cả các mục tiêu của chính nó, vì AgentCore tìm nạp các công cụ của mục tiêu trong quá trình tạo.

Terraform

Trong tệp Terraform nơi bạn khởi tạo các Gateway, hãy kết nối mục tiêu gateway vào:

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 của mục tiêu (inner-gateway ở trên) là tiền tố cho tên hành động Cedar trên gateway bên ngoài — xem phần Viết Chính sách. Mục additional_iam_policy_statements cấp cho vai trò thực thi của gateway bên ngoài quyền truy cập gọi vào gateway bên trong, điều này được yêu cầu cả để tìm nạp các công cụ của gateway bên trong tại thời điểm tạo mục tiêu và để định tuyến các cuộc gọi tại thời gian chạy. policy_dependencies đảm bảo các chính sách Cedar tham chiếu đến các hành động của mục tiêu này được tạo sau khi mục tiêu đã đăng ký chúng.

Thứ tự mục tiêu

AgentCore tìm nạp các công cụ của gateway bên trong khi aws_bedrockagentcore_gateway_target được tạo, vì vậy gateway bên trong phải đã phục vụ chúng. Đặt tool_dependencies của gateway bên trong thành các id của các mục tiêu riêng của nó: gateway_url của nó sau đó sẽ chảy qua một đầu dò sẵn sàng thăm dò tools/list cho đến khi các công cụ đó được phục vụ, vì vậy mục tiêu của gateway bên ngoài chờ gateway bên trong sẵn sàng.

Chính sách Cedar trên các gateway được xâu chuỗi

Mỗi gateway trong chuỗi đánh giá tập chính sách của riêng nó:

1. Gateway nguồn đánh giá người gọi ban đầu (ví dụ: vai trò thực thi của agent) đối với hành động có tiền tố, ví dụ: AgentCore::Action::"inner-gateway___my-mcp___add".
2. Gateway mục tiêu đánh giá vai trò thực thi của gateway nguồn đối với hành động bên trong, ví dụ: AgentCore::Action::"my-mcp___add".

Điều này có nghĩa là một cuộc gọi công cụ thông qua chuỗi gateway phải được cho phép tại mọi bước nhảy. permit-all.cedar mặc định cho phép bất kỳ người gọi nào trong cùng tài khoản AWS, bao gồm vai trò của gateway nguồn; nếu bạn viết các chính sách hẹp hơn trên gateway mục tiêu, hãy nhớ rằng principal mà nó thấy là vai trò của gateway nguồn, không phải người gọi ban đầu.

Phát triển Cục bộ

Chạy Gateway nguồn cục bộ với:

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>

khởi động gateway nguồn cục bộ, gateway mục tiêu cục bộ và mọi MCP server được gắn vào một trong hai, mỗi cái trên cổng cục bộ được chỉ định của nó. Tên công cụ được thêm tiền tố tại mỗi bước nhảy chính xác như khi triển khai (<gateway-target-name>___<target-name>___<tool-name>), vì vậy các lời nhắc agent và tên hành động Cedar vẫn nhất quán giữa các lần chạy cục bộ và triển khai.

Độ trung thực cục bộ

Phát triển cục bộ sử dụng các gateway thay thế cục bộ — các bộ tổng hợp MCP nhẹ được khởi động bởi mỗi dự án Gateway, không phải dịch vụ AgentCore Gateway. Do đó, các chính sách Cedar không được đánh giá cục bộ tại cả hai bước nhảy. Để thực thi các chính sách Cedar, hãy chạy mục tiêu serve của agent thay thế (xem hướng dẫn kết nối agent TypeScript / Python) để agent chạy cục bộ gọi Gateway đã triển khai.