TypeScript Strands Agent a Base de Datos Relacional

El generador connection conecta un TypeScript Strands 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:

Un proyecto ts#strands-agent
Un proyecto ts#rdb

Uso

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

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

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

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

Selecciona tu proyecto Strands 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.

Salida del Generador

El generador modifica un solo archivo:

Directoriopackages/my-service/src/my-agent
- agent.ts Cliente Prisma obtenido dentro de getAgent y disponible para las herramientas

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

Cómo Funciona

El cliente Prisma se obtiene directamente dentro de getAgent() en lugar de pasarse a través de parámetros de función. Esto se alinea con cómo el runtime de strands-agent propaga el contexto de sesión — withSessionId envuelve getAgent y almacena en caché una instancia de Agent por sesión, por lo que getPrisma() se llama como máximo una vez por sesión.

Definición del Agente

getAgent se actualiza para importar y llamar al getter de Prisma al inicio de su cuerpo:

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:

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
Terraform

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 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.

Pasa las salidas del módulo de base de datos a tu módulo de agente para que pueda alcanzar la base de datos y leer su configuración de runtime:

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
}

Asegúrate de que el rol de ejecución del agente tenga el permiso rds-db:connect y que su grupo de seguridad pueda alcanzar el grupo de seguridad de la base de datos en el puerto de la base de datos.

Desarrollo Local

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

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

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

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

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