TypeScript Agent a Database Relazionale

Il generatore connection collega un progetto TypeScript Agent a un progetto Relational Database, rendendo disponibile un client Prisma all’interno della tua factory di agent.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

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

Utilizzo

Esegui il Generatore

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Seleziona il tuo progetto Agent come sorgente e il tuo progetto di database relazionale come destinazione. Se il progetto contiene più componenti agent, specifica sourceComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore modifica due file nella directory sorgente del tuo agent:

• Directorypackages/my-service/src/my-agent

  • agent.ts Prisma client recuperato all’interno di getAgent e disponibile per i tool
  • Dockerfile RDS CA bundle installato per connessioni SSL ad Aurora

Inoltre, il target <agent-name>-dev dell’agent viene aggiornato per dipendere dal target dev del database.

Utilizzo del Database nei Tool dell’Agent

Il client Prisma viene istanziato all’interno di getAgent(). Poiché il generatore ts#agent configura un singolo Agent per sessione, il client viene anche riutilizzato per tutta la durata della sessione:

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

Database Multipli

Eseguire nuovamente il generatore con una destinazione diversa aggiunge il secondo database accanto al primo:

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

Infrastruttura

Il costrutto agent generato implementa IGrantable e IConnectable, quindi puoi concedere l’accesso di rete e IAM al database direttamente sul costrutto.

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 apre la regola del security group in modo che il runtime dell’agent possa raggiungere la porta del database. grantConnect concede il permesso IAM rds-db:connect al ruolo di esecuzione dell’agent.

Terraform

Esegui l’agent all’interno dello stesso VPC del database, concedigli rds-db:connect tramite additional_iam_policy_statements e apri il percorso di rete con una coppia di regole di security group. Le risorse aws_vpc.main e aws_subnet sono definite nella guida di deployment del database:

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 provengono dall’applicazione AppConfig di configurazione runtime condivisa dichiarata una volta nel tuo modulo root, non dal modulo del database. Includi il namespace database quando la istanzi in modo che l’entry di configurazione runtime del modulo del database venga distribuita:

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

Requisiti SSL per la Connessione Senza RDS Proxy

Il generatore di connessione aggiorna il Dockerfile per installare il bundle CA di Amazon RDS in /usr/local/share/ca-certificates/rds-bundle.crt. Imposta NODE_EXTRA_CA_CERTS su quel percorso in modo che Node.js si fidi del certificato quando ci si connette senza 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"
  }
}

Per maggiori dettagli, consulta la documentazione SSL/TLS di Amazon RDS. Quando si utilizza RDS Proxy, non è necessario configurare NODE_EXTRA_CA_CERTS.

Sviluppo Locale

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>

Questo avvia l’agent e tutti i database connessi. La variabile d’ambiente LOCAL_DEV=true fa sì che ogni client Prisma si connetta al suo database Docker locale invece che ad Aurora.