React Website đến AgentCore Gateway

Generator connection có thể kết nối một React website với các agent được đặt phía sau một AgentCore Gateway được tạo với protocol: http.

Trình duyệt chỉ giao tiếp với Gateway — các yêu cầu đến <gatewayUrl>/<targetName>/invocations được proxy đến agent runtime phía sau nó. Bởi vì website không bao giờ cần tiếp cận trực tiếp các runtime, các agent có thể được triển khai bên trong VPC, với Gateway là điểm vào duy nhất được quản lý cung cấp xác thực và khả năng quan sát.

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

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

Một dự án React website
Một dự án agentcore-gateway được tạo với protocol: http
Ít nhất một agent AG-UI hoặc HTTP được gắn vào Gateway thông qua Gateway to agent connection generator

Generator tạo một website client cho mỗi agent AG-UI hoặc HTTP được gắn vào Gateway (các target A2A bị bỏ qua — chúng sử dụng JSON-RPC agent-to-agent, không phải giao thức trình duyệt). Nó tạo ra các client giống như khi kết nối website trực tiếp với từng agent (AG-UI/CopilotKit cho các agent AG-UI, một OpenAPI client cho các Python HTTP agent), được định tuyến qua Gateway thay vì tại runtime.

Cách sử dụng

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

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: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

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 - connection
Điền các tham số bắt buộc
Nhấp Generate

Chọn dự án website làm nguồn và dự án Gateway làm đích.

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 Generator

Đối với mỗi agent AG-UI được đặt phía trước, các file giống như React to AG-UI agent connection được tạo ra (một AguiProvider, một hook useAgui<Agent> và một module component CopilotKit có theme), với hook đọc URL của Gateway từ runtime configuration:

Thư mụcpackages/<website>/src
- Thư mụccomponents
  - AguiProvider.tsx CopilotKit provider đăng ký mỗi agent
  - Thư mụccopilot/ Các component chat có theme
    …
- Thư mụchooks
  - useAgui<Agent>.tsx Kết nối với agent thông qua route /<targetName>/invocations của Gateway

Đối với mỗi Python HTTP agent được đặt phía trước, các file giống như React to Python agent connection được tạo ra (một OpenAPI client type-safe, các hook và một provider), với base URL của client được định tuyến qua Gateway.

URL của Gateway được đăng ký trong namespace connection.gateways.<GatewayClassName> của Runtime Configuration, do đó nó được xuất bản vào runtime-config.json của website.

Cấp quyền truy cập cho người dùng website

Đối với IAM Gateway, cấp quyền cho người dùng đã xác thực của website để gọi nó (một Cognito Gateway không cần cấp quyền — trình duyệt xác thực bằng JWT bearer token của nó thay thế):

CDK
Terraform

const identity = new UserIdentity(this, 'UserIdentity');
new Website(this, 'Website');

const myGateway = new MyGateway(this, 'MyGateway');
myGateway.addAgent(myAgent);
myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);

resource "aws_iam_policy" "gateway_invoke_policy" {
  name = "GatewayInvokePolicy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["bedrock-agentcore:InvokeGateway"]
        Resource = [module.my_gateway.gateway_arn]
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
}

Phát triển cục bộ

Target dev của website có thêm dependency vào target dev của dự án Gateway, target này khởi động local gateway cùng với mọi agent được gắn vào. Runtime configuration của website được ghi đè trong chế độ local-dev để trỏ URL của Gateway đến local gateway, do đó trình duyệt thực thi các route /<targetName>/invocations giống nhau ở cục bộ:

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

Kết nối các agent mới

Generator kết nối website với các agent được gắn vào Gateway tại thời điểm nó chạy. Sau khi gắn thêm một agent khác vào Gateway, chạy lại connection generator để tạo website client của nó — các client hiện có không bị ảnh hưởng.