Agent TypeScript Strands vers Base de Données Relationnelle

Le générateur connection connecte un Agent TypeScript Strands à un projet de Base de Données Relationnelle, rendant un client Prisma disponible à l’intérieur de votre factory d’agent.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

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

Utilisation

Exécuter le Générateur

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - connection
5. Remplissez les paramètres requis
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Sélectionnez votre projet Agent comme source et votre projet de base de données relationnelle comme cible. Si le projet contient plusieurs composants d’agent, spécifiez sourceComponent pour lever l’ambiguïté.

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du Générateur

Le générateur modifie deux fichiers dans le répertoire source de votre agent :

• Répertoirepackages/my-service/src/my-agent

  • agent.ts Client Prisma récupéré dans getAgent et disponible pour les outils
  • Dockerfile Bundle CA RDS installé pour les connexions SSL à Aurora

De plus, la cible <agent-name>-dev de l’agent est mise à jour pour dépendre de la cible dev de la base de données.

Utilisation de la Base de Données dans les Outils de l’Agent

Le client Prisma est instancié à l’intérieur de getAgent(). Étant donné que le générateur ts#agent configure un seul Agent par session, le client est également réutilisé pour la durée de vie de la session :

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

Bases de Données Multiples

Exécuter le générateur à nouveau avec une cible différente ajoute la deuxième base de données à côté de la première :

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

Infrastructure

Le construct d’agent généré implémente IGrantable et IConnectable, vous pouvez donc accorder l’accès réseau et IAM à la base de données directement sur le construct.

CDK

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 ouvre la règle du groupe de sécurité afin que le runtime de l’agent puisse atteindre le port de la base de données. grantConnect accorde la permission IAM rds-db:connect au rôle d’exécution de l’agent.

Terraform

Exécutez l’agent dans le même VPC que la base de données, accordez-lui rds-db:connect via additional_iam_policy_statements, et ouvrez le chemin réseau avec une paire de règles de groupe de sécurité. Les ressources aws_vpc.main et aws_subnet sont définies dans le guide de déploiement de la base de données :

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 proviennent de l’application configuration d’exécution AppConfig partagée déclarée une fois dans votre module racine, et non du module de base de données. Incluez le namespace database lors de son instanciation afin que l’entrée de configuration d’exécution du module de base de données soit déployée :

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

Exigences SSL lors de la Connexion sans RDS Proxy

Le générateur de connexion met à jour le Dockerfile pour installer le bundle CA Amazon RDS à l’emplacement /usr/local/share/ca-certificates/rds-bundle.crt. Définissez NODE_EXTRA_CA_CERTS sur ce chemin afin que Node.js fasse confiance au certificat lors de la connexion sans 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"
  }
}

Pour plus de détails, consultez la documentation Amazon RDS SSL/TLS. Lors de l’utilisation de RDS Proxy, vous n’avez pas besoin de configurer NODE_EXTRA_CA_CERTS.

Développement 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>

Cela démarre l’agent et toutes les bases de données connectées. La variable d’environnement LOCAL_DEV=true fait en sorte que chaque client Prisma se connecte à sa base de données Docker locale au lieu d’Aurora.