AgentCore Gateway

Tạo một dự án Amazon Bedrock AgentCore Gateway. AgentCore Gateway là một điểm vào được quản lý đặt trước các MCP server hoặc agent của bạn, xác thực các yêu cầu đến (IAM hoặc Cognito) và ký lưu lượng đi đến các target của nó bằng IAM SigV4.

Tùy chọn protocol chọn những gì Gateway đứng trước:

mcp (mặc định) — tổng hợp một hoặc nhiều MCP server target đằng sau một endpoint MCP duy nhất, và đánh giá mọi lời gọi tool dựa trên Cedar policy engine.
http — proxy các yêu cầu trực tiếp đến AgentCore Runtime targets (các agent của bạn) thông qua định tuyến dựa trên đường dẫn (/<targetName>/invocations), không có tổng hợp hoặc chuyển đổi giao thức. Sử dụng điều này để đặt các agent trước một endpoint được quản lý duy nhất — ví dụ để một trang web có thể truy cập các agent được triển khai bên trong VPC thông qua Gateway.

Cách sử dụng

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn nx g @aws/nx-plugin:agentcore-gateway

npx nx g @aws/nx-plugin:agentcore-gateway

bunx nx g @aws/nx-plugin:agentcore-gateway

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 nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - agentcore-gateway
Điền các tham số bắt buộc
Nhấp Generate

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của dự án AgentCore Gateway của bạn
directory	string	packages	Thư mục cha nơi dự án gateway được đặt.
subDirectory	string	-	Thư mục con nơi dự án được đặt. Mặc định là tên dự án.
protocol	mcp \| http	mcp	Giao thức đầu vào được cung cấp bởi gateway của bạn. Một mcp gateway tổng hợp các MCP server targets thành một MCP endpoint duy nhất. Một http gateway chuyển tiếp các yêu cầu đến agent runtime targets thông qua định tuyến dựa trên đường dẫn, cho phép các bên gọi (ví dụ: một trang web) có thể truy cập agents thông qua gateway.
auth	iam \| cognito	iam	Phương thức được sử dụng để xác thực các yêu cầu đầu vào đến gateway của bạn. Hiện tại chỉ hỗ trợ iam; cognito và custom-jwt có thể được thêm vào trong tương lai.
cedarPolicy	boolean	true	Có bao gồm công cụ chính sách Cedar để thực thi ủy quyền chi tiết trên gateway hay không.
infra	agentcore \| none	agentcore	Loại hạ tầng để lưu trữ gateway của bạn. Chọn none để không lưu trữ.
iac	inherit \| cdk \| terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để 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.

Kết quả của Generator

Generator tạo một dự án mới tại packages/<name>/, cộng với một CDK construct hoặc Terraform module cho cơ sở hạ tầng:

Thư mụcpackages/<name>/
- Thư mụcpolicies/ Các file nguồn Cedar policy (chỉ giao thức mcp; bỏ qua khi cedarPolicy: false)
  - permit-all.cedar Cedar policy mặc định cho phép các caller đã xác thực
  - README.md Tài liệu tham khảo để viết Cedar policies
- local-dev.ts Gateway cục bộ cho phát triển local — tổng hợp các MCP server đã gắn (mcp) hoặc proxy các agent đã gắn (http)
- project.json Thêm các target serve và dev

Cơ sở hạ tầng

Cơ sở hạ tầng được tạo khi infra là agentcore (mặc định). Với infra: none không có cơ sở hạ tầng nào được tạo — chạy lại generator với infra: agentcore sau để thêm nó.

Vì generator này cung cấp infrastructure as code dựa trên iac bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK
Terraform

Thư mụcpackages/common/constructs
- Thư mụcsrc
  - Thư mụcapp/ Constructs for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

CDK
Terraform

Thư mụcpackages/common/constructs/src
- Thư mụccore
  - Thư mụcagentcore-gateway/ Shared gateway construct (readiness probe, Cedar policy loading)
    …
- Thư mụcapp
  - Thư mụcgateways
    Thư mục<name>/
    <name>.ts CDK construct để triển khai Gateway

Construct được tạo tạo ra các tài nguyên AWS sau:

Một AgentCore::Gateway với xác thực IAM đến (mặc định) hoặc xác thực Cognito JWT (xem Xác thực). Gateway mcp được cấu hình cho giao thức MCP; gateway http không có loại giao thức, điều mà AgentCore yêu cầu cho các runtime target của nó
Một AgentCore::PolicyEngine chạy ở chế độ ENFORCE, được gắn vào Gateway (chỉ gateway mcp; bỏ qua khi cedarPolicy: false)
Một AgentCore::Policy cho mỗi file .cedar trong policies/ (chỉ gateway mcp)
Một AWS WAFv2 Web ACL được liên kết với Gateway, với ghi log yêu cầu vào CloudWatch (được bật theo mặc định — xem AWS WAF)

URL của Gateway được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration để các agent có thể khám phá nó tại runtime.

Kiến trúc

Gateway được triển khai có kiến trúc sau, với một AWS WAFv2 Web ACL đặt trước Gateway, định tuyến đến các MCP server target phía sau:

Xác thực

Tùy chọn auth cấu hình cách Gateway xác thực các yêu cầu đến. Chọn giữa iam (mặc định) và cognito.

IAM

Theo mặc định, Gateway được cấu hình với GatewayAuthorizer.usingAwsIam(). Các caller ký yêu cầu bằng SigV4, và danh tính IAM của caller có sẵn cho các Cedar policy dưới dạng principal AgentCore::IamEntity. Đây là tùy chọn được khuyến nghị khi các caller của bạn là các agent hoặc dịch vụ chạy trong AWS — ví dụ một agent được kết nối qua agent to Gateway connection generator, ký các lời gọi của nó bằng execution role riêng của nó.

Cognito

Khi bạn chọn cognito, Gateway được cấu hình với Custom JWT authorizer trỏ đến một Cognito user pool. Các caller xác thực bằng cách trình bày JWT bearer token, và claim sub của token có sẵn cho các Cedar policy dưới dạng principal AgentCore::OAuthUser. Sử dụng điều này khi các caller của bạn xác thực thông qua Cognito — ví dụ một trang web hoặc một coding agent kết nối qua ts#dcr-proxy generator.

Cơ sở hạ tầng được tạo sử dụng một Cognito user pool và client hiện có — nó không tạo chúng. Bạn có thể tạo một UserIdentity bằng cách sử dụng ts#website#auth generator, hoặc cung cấp của riêng bạn.

CDK
Terraform

Construct được tạo yêu cầu một prop identity cung cấp user pool và client:

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

Module được tạo yêu cầu các biến user_pool_id và user_pool_client_ids:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Viết Policies

Cedar là ngôn ngữ policy được AgentCore Gateway sử dụng để ủy quyền các lời gọi tool. Mọi yêu cầu tools/list và tools/call chảy qua Gateway đều được đánh giá dựa trên tập policy đã gắn, và caller phải có ít nhất một câu lệnh permit khớp (và không có forbid khớp) để yêu cầu thành công.

Tham khảo tài liệu AWS về AgentCore Gateway policies để biết tài liệu tham khảo đầy đủ, bao gồm các mẫu policy phổ biến.

Thêm một policy

Để thêm một policy, tạo một file .cedar mới bên cạnh permit-all.cedar. Mỗi file .cedar trong policies/ phải chứa chính xác một câu lệnh permit hoặc forbid và được triển khai dưới dạng một tài nguyên AWS::BedrockAgentCore::Policy duy nhất. Tên của tài nguyên policy được lấy từ tên file: permit-all.cedar trở thành PermitAll (kebab/snake-case được chuyển đổi thành PascalCase). Các file chứa nhiều câu lệnh tạo ra lỗi unexpected token 'forbid' tại thời điểm triển khai — tách chúng thành các file riêng biệt.

Ví dụ, để chỉ cho phép một agent role cụ thể gọi một tool cụ thể, tạo:

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

Truyền tên role vào dưới dạng biến template (xem Biến template bên dưới) thay vì hard-code nó. Chạy lại synth hoặc plan để triển khai policy mới.

Biến template

Các policy là các template EJS được render tại thời điểm synth/plan để chúng có thể di chuyển được qua các tài khoản và triển khai lại Gateway:

Biến	Được thay thế bằng
`<%= gatewayArn %>`	ARN của Gateway đã triển khai
`<%= accountId %>`	Tài khoản AWS mà Gateway này được triển khai vào

Luôn tham chiếu các biến này thay vì hard-code các giá trị.

Thêm biến của riêng bạn

Thêm các biến mới nơi các policy được render, ví dụ để truyền tên execution role của agent vào ví dụ ts-agent-divide.cedar ở trên:

CDK
Terraform

Trong packages/common/constructs/src/app/gateways/<name>/<name>.ts, truyền cedarPolicyVariables qua shared construct:

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

Trong packages/common/terraform/src/app/gateways/<name>/<name>.tf, thêm vào query của data source rendered_policies:

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

Chế độ ENFORCE và default-deny

PolicyEngine chạy ở chế độ ENFORCE, có nghĩa là ngữ nghĩa default-deny được áp dụng: nếu không có câu lệnh permit nào khớp với tuple (principal, action, resource), yêu cầu bị từ chối. Các lời gọi tool bị từ chối trả về:

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

Ngoài ra, Gateway lọc phản hồi của tools/list để các caller chỉ thấy các tool mà họ có ít nhất một permit khớp: nếu một agent thiếu quyền cho một tool nhất định, tool đó bị ẩn hoàn toàn thay vì xuất hiện và thất bại tại thời điểm gọi.

`permit-all.cedar` mặc định

Generator cung cấp một policy mặc định được giới hạn theo loại xác thực của Gateway.

Đối với Gateway IAM, nó cho phép bất kỳ IAM caller nào từ tài khoản AWS mà Gateway được triển khai vào:

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

Đối với Gateway Cognito, nó cho phép bất kỳ OAuth user đã xác thực nào (JWT authorizer đã xác thực user pool và client của token trước khi các policy được đánh giá):

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Để khóa chặt hơn, thêm các policy hẹp hơn bên cạnh nó. Luôn giữ ít nhất một permit khớp trong tập policy, nếu không default-deny sẽ chặn mọi lời gọi.

Tài liệu tham khảo phạm vi policy

Loại principal phụ thuộc vào cách Gateway xác thực các caller (xem Xác thực).

Đối với Gateway IAM, các caller là các IAM principal:

principal is AgentCore::IamEntity

Các caller được đánh giá dưới dạng ARN assumed-role STS với tên session bị loại bỏ, vì vậy một role có thể được khớp chính xác — không cần ký tự đại diện:

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

Cùng một giá trị có sẵn dưới dạng principal.id cho các mệnh đề when. Dành like cho các mẫu thực sự, chẳng hạn như khớp toàn tài khoản trong permit-all.cedar mặc định.

Đối với Gateway Cognito, các caller là các OAuth user được xây dựng từ claim sub của JWT token, và các claim JWT (username, scope, v.v.) có sẵn dưới dạng principal tag:

principal is AgentCore::OAuthUser

Khớp các claim riêng lẻ trong các mệnh đề when — ví dụ để yêu cầu một scope:

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

Các lời gọi tool đến policy engine dưới dạng các action với dạng:

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

trong đó <target-name> là tên Gateway target (mặc định là mcpServerName của MCP server khi sử dụng gateway.addMcpServer(...), được lấy từ tên class của dự án MCP ở dạng kebab-case — ví dụ TsMcp → ts-mcp), <tool-name> là tên của MCP tool, và dấu phân cách là ___ (ba dấu gạch dưới). Cedar không hỗ trợ ký tự đại diện trên các action — khớp các action chính xác, hoặc bỏ qua action == để khớp tất cả các action.

Resource luôn là chính Gateway:

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

Cân nhắc về xác thực

Cơ sở hạ tầng được tạo tạo các policy với IGNORE_ALL_FINDINGS: Cedar analyzer của AgentCore (FAIL_ON_ANY_FINDINGS, mặc định của dịch vụ) từ chối nhiều policy hợp lệ — ví dụ, một forbid vô hiệu hóa một tool duy nhất cho mọi caller bị từ chối là “Overly Restrictive”, ngay cả khi được giới hạn bằng mệnh đề when. Việc thực thi không bị ảnh hưởng; nó được cấu hình bởi chế độ ENFORCE của policy engine.

Một ràng buộc về thứ tự vẫn áp dụng: một policy tham chiếu AgentCore::Action::"<target>___<tool>" chỉ xác thực khi target đã đăng ký tool đó với Gateway, đó là lý do tại sao cơ sở hạ tầng được tạo tạo các policy sau Gateway target.

Nếu một policy không triển khai được, CloudFormation hiển thị việc từ chối dưới dạng lỗi Resource stabilization failed mơ hồ — chạy aws bedrock-agentcore-control list-policies --policy-engine-id <id> để lấy statusReasons của validator, chứa lý do thực sự.

Ví dụ: forbid một tool trong khi giữ permit rộng hơn

Ghép một forbid hẹp với một permit rộng hơn (Cedar đánh giá forbid trước permit):

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Điều này từ chối Python agent role gọi ts-mcp___divide trong khi để permit-all.cedar rộng hơn tại chỗ cho tất cả các caller khác.

Phát triển Local

Generator thêm một target dev vào dự án Gateway, chạy local-dev.ts. Chạy nó sẽ khởi động local gateway và mọi target đã gắn cùng nhau:

pnpm nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

Local gateway hiển thị một endpoint MCP duy nhất tổng hợp mọi MCP server đã gắn (được kết nối qua agentcore-gateway#mcp-connection generator), với các tool có tiền tố <target>___<tool> để khớp với Gateway đã triển khai.

Local gateway proxy các đường dẫn /<targetName>/... đến local server của mỗi agent đã gắn (được kết nối qua agentcore-gateway#agent-connection generator), khớp với định tuyến dựa trên đường dẫn của Gateway đã triển khai.

Xem các hướng dẫn kết nối để biết câu chuyện phát triển local đầy đủ.

Triển khai AgentCore Gateway của bạn

AgentCore Gateway generator tạo mã cơ sở hạ tầng CDK hoặc Terraform dựa trên iac đã chọn của bạn. Bạn có thể sử dụng điều này để triển khai Gateway của bạn.

CDK
Terraform

CDK construct để triển khai Gateway của bạn nằm trong thư mục common/constructs. Bạn có thể sử dụng điều này trong một ứng dụng CDK, ví dụ:

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

Điều này thiết lập cơ sở hạ tầng Gateway của bạn, bao gồm AgentCore::Gateway, Cedar PolicyEngine của nó, và AWS WAF Web ACL (xem AWS WAF bên dưới). Đăng ký các MCP server target với gateway.addMcpServer(...) — xem hướng dẫn kết nối MCP server.

Terraform module để triển khai Gateway của bạn nằm trong thư mục common/terraform. Bạn có thể sử dụng điều này trong một cấu hình Terraform, ví dụ:

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

Điều này thiết lập cơ sở hạ tầng Gateway của bạn, bao gồm aws_bedrockagentcore_gateway, Cedar policy engine của nó, và AWS WAF Web ACL (xem AWS WAF bên dưới). Đăng ký các MCP server target với một tài nguyên aws_bedrockagentcore_gateway_target — xem hướng dẫn kết nối MCP server.

AWS WAF

Theo mặc định, construct được tạo liên kết một AWS WAFv2 Web ACL với Gateway. AWS WAF kiểm tra mọi yêu cầu đến inline trước khi nó đến target, bảo vệ Gateway của bạn khỏi các khai thác web, lưu lượng bot và các cuộc tấn công volumetric. Web ACL sử dụng bộ quy tắc mặc định được quản lý bởi AWS (AWSManagedRulesCommonRuleSet và AWSManagedRulesKnownBadInputsRuleSet), cung cấp bảo vệ chống lại các khai thác web phổ biến bao gồm OWASP Top 10. Log yêu cầu WAF được ghi vào một CloudWatch Logs group.

Web ACL là REGIONAL và được tạo trong region của Gateway, như yêu cầu cho các liên kết AgentCore Gateway.

Bạn có thể chỉnh sửa Gateway construct được tạo để thêm, xóa hoặc điều chỉnh các quy tắc (ví dụ, để thêm rate-based rules hoặc các nhóm quy tắc được quản lý bổ sung).

CDK
Terraform

Để từ chối (ví dụ, để gắn Web ACL của riêng bạn), đặt enableWaf thành false khi bạn khởi tạo Gateway construct:

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

Construct hiển thị Web ACL đã tạo dưới dạng webAcl để cấu hình thêm.

Để từ chối (ví dụ, để gắn Web ACL của riêng bạn), đặt enable_waf thành false trên Gateway module:

module "my_gateway" {
  enable_waf = false
}

Module xuất ARN của Web ACL đã tạo dưới dạng waf_web_acl_arn để cấu hình thêm.

Kết nối

Sử dụng connection generator để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

AgentCore Gateway to MCP ServerTổng hợp một MCP server đằng sau một AgentCore Gateway

AgentCore Gateway to AgentCore GatewayTổng hợp một AgentCore Gateway đằng sau một AgentCore Gateway khác

TypeScript Agent to AgentCore GatewayKết nối một TypeScript Agent với một AgentCore Gateway

Python Agent to AgentCore GatewayKết nối một Python Agent với một AgentCore Gateway

AgentCore Gateway to AgentĐặt một agent trước một AgentCore Gateway dưới dạng runtime target

React Website to AgentCore GatewayKết nối một React website với các agent thông qua một AgentCore Gateway