TypeScript Agent a Base de Datos Relacional

El generador connection conecta un TypeScript Agent a un proyecto de Base de Datos Relacional, haciendo que un cliente Prisma esté disponible dentro de tu fábrica de agentes.

Requisitos Previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto ts#agent
2. Un proyecto ts#rdb

Uso

Ejecutar el Generador

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Selecciona tu proyecto Agent como origen y tu proyecto de base de datos relacional como destino. Si el proyecto contiene múltiples componentes de agente, especifica sourceComponent para desambiguar.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador modifica dos archivos en el directorio de origen de tu agente:

• Directoriopackages/my-service/src/my-agent

  • agent.ts Cliente Prisma obtenido dentro de getAgent y disponible para las herramientas
  • Dockerfile Paquete CA de RDS instalado para conexiones SSL a Aurora

Además, el objetivo <agent-name>-dev del agente se actualiza para depender del objetivo dev de la base de datos.

Usando la Base de Datos en las Herramientas del Agente

El cliente Prisma se instancia dentro de getAgent(). Dado que el generador ts#agent configura un único Agent por sesión, el cliente también se reutiliza durante la vida útil de la sesió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 */ });
};

Múltiples Bases de Datos

Ejecutar el generador nuevamente con un destino diferente agrega la segunda base de datos junto a la primera:

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

Infraestructura

El constructo de agente generado implementa IGrantable e IConnectable, por lo que puedes otorgar acceso de red e IAM a la base de datos directamente en el constructo.

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 abre la regla del grupo de seguridad para que el runtime del agente pueda alcanzar el puerto de la base de datos. grantConnect otorga el permiso IAM rds-db:connect al rol de ejecución del agente.

Terraform

Ejecuta el agente dentro de la misma VPC que la base de datos, otórgale rds-db:connect a través de additional_iam_policy_statements, y abre la ruta de red con un par de reglas de grupo de seguridad. Los recursos aws_vpc.main y aws_subnet se definen en la guía de implementación de la base de datos:

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 provienen de la aplicación AppConfig de configuración de runtime compartida declarada una vez en tu módulo raíz, no del módulo de base de datos. Incluye el espacio de nombres database al instanciarla para que se implemente la entrada de configuración de runtime del módulo de base de datos:

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"]
}

Requisitos SSL al Conectarse sin RDS Proxy

El generador de conexión actualiza el Dockerfile para instalar el paquete de CA de Amazon RDS en /usr/local/share/ca-certificates/rds-bundle.crt. Establece NODE_EXTRA_CA_CERTS a esa ruta para que Node.js confíe en el certificado al conectar sin 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"
  }
}

Para más detalles, consulta la documentación SSL/TLS de Amazon RDS. Al usar RDS Proxy, no necesitas configurar NODE_EXTRA_CA_CERTS.

Desarrollo Local

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>

Esto inicia el agente y todas las bases de datos conectadas. La variable de entorno LOCAL_DEV=true hace que cada cliente Prisma se conecte a su base de datos Docker local en lugar de Aurora.