TypeScript Strands Agent a Database Relazionale

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

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

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

Utilizzo

Eseguire il Generatore

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

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

Seleziona il tuo progetto Strands 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.

Output del Generatore

Il generatore modifica un singolo file:

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

  • agent.ts Client Prisma recuperato all’interno di getAgent e disponibile per i tools

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

Come Funziona

Il client Prisma viene recuperato direttamente all’interno di getAgent() anziché essere passato attraverso i parametri delle funzioni. Questo si allinea con il modo in cui il runtime strands-agent propaga il contesto di sessione — withSessionId avvolge getAgent e memorizza nella cache un’istanza di Agent per sessione, quindi getPrisma() viene chiamato al massimo una volta per sessione.

Definizione dell’Agent

getAgent viene aggiornato per importare e chiamare il getter Prisma all’inizio del suo corpo:

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 { MyDatabase } from ':my-scope/common-constructs';

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

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

Passa gli output del modulo database nel tuo modulo agent in modo che possa raggiungere il database e leggere la sua configurazione di runtime:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port
}

Assicurati che il ruolo di esecuzione dell’agent abbia il permesso rds-db:connect e che il suo security group possa raggiungere il security group del database sulla porta del database.

Sviluppo Locale

pnpm

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <project-name>

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