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ập hợp một hoặc nhiều mục tiêu MCP server phía sau một endpoint MCP duy nhất, đánh giá mọi lời gọi công cụ dựa trên công cụ chính sách Cedar, và ký lưu lượng truy cập đi ra đến các MCP server bằng IAM SigV4.

Cách sử dụng

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

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

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	mcp	Giao thức đầu vào được gateway của bạn cung cấp. Hiện tại chỉ hỗ trợ mcp; các giao thức bổ sung có thể được thêm vào trong tương lai.
auth	iam	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 tệp nguồn chính sách Cedar (bỏ qua khi cedarPolicy: false)
  - permit-all.cedar Chính sách Cedar mặc định cho phép người gọi đã xác thực từ trong cùng tài khoản AWS
  - README.md Tài liệu tham khảo để viết chính sách Cedar
- local-dev.ts Gateway cục bộ tập hợp các MCP server đính kèm cho phát triển cục bộ
- 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 iacProvider 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 cho infrastructure cụ thể của một dự án/generator
    …
  - Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app
    …
  - index.ts Entry point xuất các constructs từ app
- project.json Các build targets và cấu hình của dự án

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator
    …
  - Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app
    …
- project.json Các build targets và cấu hình của dự án

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 ra sẽ tạo các tài nguyên AWS sau:

Một AgentCore::Gateway được cấu hình cho giao thức MCP với GatewayAuthorizer.usingAwsIam() (xác thực IAM đầu vào)
Một AgentCore::PolicyEngine chạy ở chế độ ENFORCE, được gắn vào Gateway (bỏ qua khi cedarPolicy: false)
Một AgentCore::Policy cho mỗi tệp .cedar trong policies/

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.

Viết chính sách

Cedar là ngôn ngữ chính sách được AgentCore Gateway sử dụng để ủy quyền các lời gọi công cụ. Mọi yêu cầu tools/list và tools/call đi qua Gateway đều được đánh giá dựa trên tập chính sách đính kèm, và người gọi 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ề chính sách AgentCore Gateway để biết tài liệu tham khảo đầy đủ, bao gồm các mẫu chính sách phổ biến.

Thêm một chính sách

Để thêm một chính sách, hãy tạo một tệp .cedar mới bên cạnh permit-all.cedar. Mỗi tệp .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 chính sách được lấy từ tên tệp: permit-all.cedar trở thành PermitAll (kebab/snake-case được chuyển đổi thành PascalCase). Các tệp chứa nhiều câu lệnh sẽ tạo ra lỗi unexpected token 'forbid' tại thời điểm triển khai — hãy tách chúng thành các tệp riêng biệt.

Ví dụ, để chỉ cho phép một vai trò agent cụ thể gọi một công cụ cụ thể, hãy 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 vai trò 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 chính sách mới.

Biến template

Các chính sách là template EJS được render tại thời điểm synth/plan để chúng có thể di chuyển giữa 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 biến mới tại nơi các chính sách được render, ví dụ để truyền tên vai trò thực thi 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 bộ ba (principal, action, resource), yêu cầu sẽ bị từ chối. Các lời gọi công cụ bị từ chối sẽ 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 để người gọi chỉ thấy các công cụ mà họ có ít nhất một permit khớp: nếu một agent thiếu quyền cho một công cụ nhất định, công cụ đó sẽ 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 chính sách mặc định cho phép bất kỳ người gọi IAM 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 %>:*"
};

Để khóa chặt hơn, hãy thêm các chính sách hẹp hơn bên cạnh nó. Luôn giữ lại ít nhất một permit khớp trong tập chính sách, 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 chính sách

Đối với các Gateway được tạo bởi plugin này, tất cả người gọi đều là IAM principal (Gateway được cấu hình với GatewayAuthorizer.usingAwsIam()):

principal is AgentCore::IamEntity

Người gọi được đánh giá dưới dạng STS assumed-role ARN với tên session bị loại bỏ, vì vậy một vai trò có thể được khớp chính xác — không cần wildcard:

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.

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

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

trong đó <target-name> là tên target Gateway (mcpServerName của MCP server theo mặc định 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ông cụ MCP, và dấu phân cách là ___ (ba dấu gạch dưới). Cedar không hỗ trợ wildcard trên action — khớp chính xác action, hoặc bỏ qua action == để khớp tất cả action.

Resource luôn là chính Gateway:

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

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

Cơ sở hạ tầng được tạo ra tạo các chính sách với IGNORE_ALL_FINDINGS: trình phân tích Cedar của AgentCore (FAIL_ON_ANY_FINDINGS, mặc định của dịch vụ) từ chối nhiều chính sách hợp lệ — ví dụ, một forbid vô hiệu hóa một công cụ duy nhất cho mọi người gọi 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 chính sách tham chiếu AgentCore::Action::"<target>___<tool>" chỉ xác thực sau khi target đã đăng ký công cụ đó với Gateway, đó là lý do tại sao cơ sở hạ tầng được tạo ra tạo các chính sách sau các target Gateway.

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

Ví dụ: forbid một công cụ 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 vai trò agent Python gọi ts-mcp___divide trong khi vẫn giữ permit-all.cedar rộng hơn cho tất cả người gọi khác.

Phát triển cục bộ

Generator thêm target dev vào dự án Gateway, chạy local-dev.ts: một gateway cục bộ cung cấp một endpoint MCP duy nhất tập hợp mọi MCP server đính kèm (được kết nối thông qua generator agentcore-gateway#mcp-connection), với các công cụ có tiền tố <target>___<tool> để khớp với Gateway đã triển khai. Chạy nó sẽ khởi động gateway cục bộ và tất cả các MCP server đính kèm cùng nhau:

pnpm nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

Xem hướng dẫn kết nối để biết toàn bộ câu chuyện phát triển cục bộ.

Kết nối

Sử dụng generator connection để 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 Server Tổng hợp MCP server phía sau AgentCore Gateway

AgentCore Gateway to AgentCore Gateway Tổng hợp AgentCore Gateway phía sau một AgentCore Gateway khác

TypeScript Agent to AgentCore Gateway Kết nối TypeScript Agent với AgentCore Gateway

Python Agent to AgentCore Gateway Kết nối Python Agent với AgentCore Gateway