Skip to content
@aws/nx-plugin
Blog

TypeScript Agent to Relational Database

The connection generator wires a TypeScript Agent to a Relational Database project, making a Prisma client available inside your agent factory.

Prerequisites

Section titled “Prerequisites”

Before using this generator, ensure you have:

  1. A ts#agent project
  2. A ts#rdb project

Usage

Section titled “Usage”

Run the Generator

Section titled “Run the Generator”
  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - connection
  5. Fill in the required parameters
    • Click Generate

    Select your Agent project as the source and your relational database project as the target. If the project contains multiple agent components, specify sourceComponent to disambiguate.

    Options

    Section titled “Options”
    ParameterTypeDefaultDescription
    sourceProject Requiredstring-The source project
    targetProject Requiredstring-The target project to connect to
    sourceComponent string-The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.
    targetComponent string-The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.
    preferInstallDependencies booleantrueWhether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

    Generator Output

    Section titled “Generator Output”

    The generator modifies two files in your agent’s source directory:

    • Directorypackages/my-service/src/my-agent
      • agent.ts Prisma client fetched inside getAgent and available to tools
      • Dockerfile RDS CA bundle installed for SSL connections to Aurora

    Additionally, the agent’s <agent-name>-dev target is updated to depend on the database’s dev target.

    Using the Database in Agent Tools

    Section titled “Using the Database in Agent Tools”

    The Prisma client is instantiated inside getAgent(). Since the ts#agent generator configures a single Agent per session, the client is also reused for the lifetime of the 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 */ });
    };

    Multiple Databases

    Section titled “Multiple Databases”

    Running the generator again with a different target adds the second database alongside the first:

    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

    Section titled “Infrastructure”

    The generated agent construct implements IGrantable and IConnectable, so you can grant network and IAM access to the database directly on the construct.

    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 opens the security group rule so the agent runtime can reach the database port. grantConnect grants IAM rds-db:connect permission to the agent’s execution role.

    SSL Requirements When Connecting Without RDS Proxy

    Section titled “SSL Requirements When Connecting Without RDS Proxy”

    The connection generator updates the Dockerfile to install the Amazon RDS CA bundle at /usr/local/share/ca-certificates/rds-bundle.crt. Set NODE_EXTRA_CA_CERTS to that path so Node.js trusts the certificate when connecting without 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',
      },
    });

    For more details, see the Amazon RDS SSL/TLS documentation. When using RDS Proxy, you do not need to configure NODE_EXTRA_CA_CERTS.

    Local Development

    Section titled “Local Development”
    Terminal window
    pnpm nx <agent-name>-dev <project-name>

    This starts the agent and all connected databases. The LOCAL_DEV=true environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.