TypeScript Agent para Banco de Dados Relacional

O gerador connection conecta um TypeScript Agent a um projeto de Banco de Dados Relacional, disponibilizando um cliente Prisma dentro da sua factory de agente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

Um projeto ts#agent
Um projeto ts#rdb

Uso

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Selecione seu projeto Agent como origem e seu projeto de banco de dados relacional como destino. Se o projeto contiver múltiplos componentes de agente, especifique sourceComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador modifica dois arquivos no diretório de origem do seu agente:

Directorypackages/my-service/src/my-agent
- agent.ts Cliente Prisma obtido dentro de getAgent e disponível para ferramentas
- Dockerfile Pacote CA do RDS instalado para conexões SSL com Aurora

Além disso, o target <agent-name>-dev do agente é atualizado para depender do target dev do banco de dados.

Usando o Banco de Dados nas Ferramentas do Agente

O cliente Prisma é instanciado dentro de getAgent(). Como o gerador ts#agent configura um único Agent por sessão, o cliente também é reutilizado durante toda a vida útil da sessão:

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

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

Múltiplos Bancos de Dados

Executar o gerador novamente com um destino diferente adiciona o segundo banco de dados junto com o primeiro:

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 */ });
};

Infraestrutura

O construto de agente gerado implementa IGrantable e IConnectable, então você pode conceder acesso de rede e IAM ao banco de dados diretamente no construto.

CDK
Terraform

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 abre a regra do grupo de segurança para que o runtime do agente possa alcançar a porta do banco de dados. grantConnect concede permissão IAM rds-db:connect ao papel de execução do agente.

Execute o agente dentro da mesma VPC que o banco de dados, conceda a ele rds-db:connect via additional_iam_policy_statements, e abra o caminho de rede com um par de regras de grupo de segurança. Os recursos aws_vpc.main e aws_subnet são definidos no guia de implantação do banco de dados:

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 vêm da configuração de runtime compartilhada da aplicação AppConfig declarada uma vez no seu módulo raiz, não do módulo do banco de dados. Inclua o namespace database ao instanciá-lo para que a entrada de configuração de runtime do módulo do banco de dados seja implantada:

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

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

Requisitos de SSL ao Conectar Sem RDS Proxy

O gerador de conexão atualiza o Dockerfile para instalar o pacote de CA do Amazon RDS em /usr/local/share/ca-certificates/rds-bundle.crt. Defina NODE_EXTRA_CA_CERTS para esse caminho para que o Node.js confie no certificado ao conectar sem RDS Proxy:

CDK
Terraform

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

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

Para mais detalhes, consulte a documentação SSL/TLS do Amazon RDS. Ao usar RDS Proxy, você não precisa configurar NODE_EXTRA_CA_CERTS.

Desenvolvimento Local

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

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

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

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

Isso inicia o agente e todos os bancos de dados conectados. A variável de ambiente LOCAL_DEV=true faz com que cada cliente Prisma se conecte ao seu banco de dados Docker local em vez do Aurora.