Salta ai contenuti
@aws/nx-plugin
Blog

TypeScript Agent a Database Relazionale

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

Prerequisiti

Sezione intitolata “Prerequisiti”

Prima di utilizzare questo generatore, assicurati di avere:

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

Utilizzo

Sezione intitolata “Utilizzo”

Eseguire il Generatore

Sezione intitolata “Eseguire il Generatore”
  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
    • 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

    Sezione intitolata “Opzioni”
    ParametroTipoPredefinitoDescrizione
    sourceProject Obbligatoriostring-Il progetto sorgente
    targetProject Obbligatoriostring-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 booleantrueSe 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

    Sezione intitolata “Output del Generatore”

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

    • Directorypackages/my-service/src/my-agent
      • agent.ts Client Prisma recuperato all’interno di getAgent e disponibile per i tools
      • Dockerfile Bundle CA RDS 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 negli Strumenti dell’Agent

    Sezione intitolata “Utilizzo del Database negli Strumenti 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 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

    Sezione intitolata “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

    Sezione intitolata “Infrastruttura”

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

    packages/infra/src/stacks/application-stack.ts
    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 },
      }),
    });
    

    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.

    Requisiti SSL per la Connessione Senza RDS Proxy

    Sezione intitolata “Requisiti SSL per la Connessione Senza RDS Proxy”

    Il generatore di connessioni 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:

    packages/infra/src/stacks/application-stack.ts
    new MyAgent(this, 'MyAgent', {
      ...
      environmentVariables: {
        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

    Sezione intitolata “Sviluppo Locale”
    Terminal window
    pnpm 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.