TypeScript Agent đến Cơ sở dữ liệu Quan hệ

Generator connection kết nối một TypeScript Agent với một dự án Relational Database, cung cấp Prisma client bên trong agent factory của bạn.

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

1. Một dự án ts#agent
2. Một dự án ts#rdb

Cách sử dụng

Chạy Generator

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

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

Chọn dự án Agent của bạn làm nguồn và dự án cơ sở dữ liệu quan hệ của bạn làm đích. Nếu dự án chứa nhiều agent component, hãy chỉ định sourceComponent để phân biệt.

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 Generator

Generator sửa đổi hai file trong thư mục nguồn của agent:

• Thư mụcpackages/my-service/src/my-agent

  • agent.ts Prisma client được lấy bên trong getAgent và có sẵn cho các tool
  • Dockerfile RDS CA bundle được cài đặt cho kết nối SSL đến Aurora

Ngoài ra, target <agent-name>-dev của agent được cập nhật để phụ thuộc vào target dev của cơ sở dữ liệu.

Sử dụng Cơ sở dữ liệu trong Agent Tools

Prisma client được khởi tạo bên trong getAgent(). Vì generator ts#agent cấu hình một Agent duy nhất cho mỗi phiên, client cũng được tái sử dụng trong suốt vòng đời của phiên:

packages/my-service/src/my-agent/agent.ts

import { getPrisma as getMyDb } from '@my-scope/my-db';

export const getAgent = async () => {
  const myDb = await getMyDb();
  // ...
  return new Agent({ /* use myDb in tools */ });
};

Nhiều Cơ sở dữ liệu

Chạy generator lần nữa với một target khác sẽ thêm cơ sở dữ liệu thứ hai cùng với cơ sở dữ liệu đầu tiên:

packages/my-service/src/my-agent/agent.ts

import { getPrisma as getMyDb } from '@my-scope/my-db';
import { getPrisma as getOtherDb } from '@my-scope/other-db';

export const getAgent = async () => {
  const myDb = await getMyDb();
  const otherDb = await getOtherDb();
  // ...
  return new Agent({ /* use both clients in tools */ });
};

Hạ tầng

Construct agent được tạo ra triển khai IGrantable và IConnectable, vì vậy bạn có thể cấp quyền truy cập mạng và IAM cho cơ sở dữ liệu trực tiếp trên construct.

CDK

packages/infra/src/stacks/application-stack.ts

import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
import { MyDatabase } from '@my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', { vpc, ... });

const myAgent = new MyAgent(this, 'MyAgent', {
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    securityGroups: [
      new SecurityGroup(this, 'MyAgentSecurityGroup', { vpc, allowAllOutbound: true }),
    ],
  }),
});

db.allowDefaultPortFrom(myAgent);
db.grantConnect(myAgent);

allowDefaultPortFrom mở quy tắc security group để agent runtime có thể truy cập cổng cơ sở dữ liệu. grantConnect cấp quyền IAM rds-db:connect cho execution role của agent.

Terraform

Chạy agent bên trong cùng VPC với cơ sở dữ liệu, cấp cho nó quyền rds-db:connect thông qua additional_iam_policy_statements, và mở đường dẫn mạng với một cặp quy tắc security group. Các tài nguyên aws_vpc.main và aws_subnet được định nghĩa trong hướng dẫn triển khai cơ sở dữ liệu:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "my_agent" {
  source     = "../../common/terraform/src/app/agents/my-agent"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "agent_to_database" {
  description                  = "Allow the agent runtime to connect to the database"
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.my_agent.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "agent_to_database" {
  description                  = "Allow outbound traffic from the agent runtime to the database"
  security_group_id            = module.my_agent.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

appconfig_application_id/appconfig_application_arn đến từ ứng dụng runtime configuration AppConfig được chia sẻ được khai báo một lần trong root module của bạn, không phải từ database module. Bao gồm namespace database khi khởi tạo nó để entry runtime configuration của database module được triển khai:

packages/infra/src/main.tf

module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database"]
}

Yêu cầu SSL Khi Kết nối Không có RDS Proxy

Trình tạo kết nối cập nhật Dockerfile để cài đặt gói CA của Amazon RDS tại /usr/local/share/ca-certificates/rds-bundle.crt. Đặt NODE_EXTRA_CA_CERTS thành đường dẫn đó để Node.js tin tưởng chứng chỉ khi kết nối không qua RDS Proxy:

CDK

packages/infra/src/stacks/application-stack.ts

new MyAgent(this, 'MyAgent', {
  ...
  environmentVariables: {
    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
  },
});

Terraform

packages/infra/src/main.tf

module "my_agent" {
  ...
  environment_variables = {
    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
  }
}

Để biết thêm chi tiết, xem tài liệu Amazon RDS SSL/TLS. Khi sử dụng RDS Proxy, bạn không cần cấu hình NODE_EXTRA_CA_CERTS.

Phát triển Cục bộ

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

Lệnh này khởi động agent và tất cả các cơ sở dữ liệu được kết nối. Biến môi trường LOCAL_DEV=true khiến mỗi Prisma client kết nối với cơ sở dữ liệu Docker cục bộ của nó thay vì Aurora.