Trang Web React đến AgentCore Gateway

Trình tạo connection có thể kết nối một trang web React với các agent được đặt phía trước bởi 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 runtime của agent phía sau nó. Vì trang web không bao giờ cần truy cập trực tiếp vào 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 trình tạo này, hãy đảm bảo bạn có:

Một dự án trang web React
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 trình tạo kết nối Gateway đến agent

Trình tạo tạo một client trang web 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 trang web trực tiếp với từng agent (AG-UI/CopilotKit cho các agent AG-UI, một client OpenAPI cho các agent Python HTTP), được định tuyến qua Gateway thay vì tại runtime.

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

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

Chọn dự án trang web 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.

Kết quả của Trình tạo

Đối với mỗi agent AG-UI được đặt phía trước, các tệp giống như kết nối React đến agent AG-UI được tạo ra (một AguiProvider, một hook useAgui<Agent> và một module component CopilotKit có chủ đề), với hook đọc URL của Gateway từ cấu hình runtime:

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ó chủ đề
    …
- 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 agent Python HTTP được đặt phía trước, các tệp giống như kết nối React đến agent Python được tạo ra (một client OpenAPI an toàn kiểu, các hook và một provider), với URL cơ sở 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 trang web.

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

Đối với IAM Gateway, cấp cho người dùng đã xác thực của trang web quyền gọi nó (Cognito Gateway không cần cấp quyền — trình duyệt xác thực bằng JWT bearer token 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 trang web có thêm phụ thuộc vào target dev của dự án Gateway, target này khởi động gateway cục bộ cùng với mọi agent được gắn vào. Cấu hình runtime của trang web được ghi đè trong chế độ local-dev để trỏ URL của Gateway đến gateway cục bộ, 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

Trình tạo kết nối trang web 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, hãy chạy lại trình tạo kết nối để tạo client trang web của nó — các client hiện có không bị ảnh hưởng.