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 riêng của nó.

Sau khi được kết nối, Gateway nguồn 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 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 phải 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ẽ gây đệ quy vô hạn trên tools/list.

Cách sử dụng

Chạy Trình tạo

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

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

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 <source-gateway>-serve-local có thêm phụ thuộc vào <target-gateway>-serve-local của gateway mục tiêu
  • serve-local.ts ATTACHED_MCP_SERVERS được cập nhật để gateway cục bộ tổng hợp gateway mục tiêu

Target dev của dự án Gateway nguồn có thêm phụ thuộc vào target dev của Gateway mục tiêu, vì vậy khi chạy Gateway nguồn cục bộ cũng sẽ 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 gateway target vào stack của bạn

Trình tạo không thể tự động kết nối gateway target 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 gateway target (mặc định là gatewayName của gateway mục tiêu) thêm 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 target 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 target 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 gateway target vào:

packages/infra/src/main.tf

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

  # Target ids của các target riêng của inner gateway (ví dụ: các MCP server của nó), để
  # gateway_url của nó không được sử dụng cho đến khi nó phục vụ các công cụ của chúng.
  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 target (inner-gateway ở trên) thêm tiền tố cho tên hành động Cedar trên outer gateway — 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 outer gateway quyền truy cập invoke vào inner gateway, điều này là bắt buộc cả để tìm nạp các công cụ của inner gateway tại thời điểm tạo target và để định tuyến các cuộc gọi tại runtime. policy_dependencies đảm bảo các chính sách Cedar tham chiếu đến các hành động của target này được tạo sau khi target đã đăng ký chúng.

Thứ tự target

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

Chính sách Cedar qua 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ụ qua chuỗi gateway phải được cho phép tại mọi điểm dừng. 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 <source-gateway-name>-dev

yarn

yarn nx <source-gateway-name>-dev

npm

npx nx <source-gateway-name>-dev

bun

bunx nx <source-gateway-name>-dev

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 điểm dừng 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 của 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 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 điểm dừng. Để thực thi các chính sách Cedar, hãy chạy target 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.