TypeScript Agent to DynamoDB

The connection generator wires a TypeScript Agent to a TypeScript DynamoDB project, configuring local development so both start together automatically.

Prerequisites

Before using this generator, ensure you have:

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

Usage

Run the Generator

VSCode

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

You can also perform a dry-run to see what files would be changed

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

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

Options

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	string	-	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	boolean	true	Whether 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

The generator updates the agent’s <agent-name>-dev target in project.json to depend on the DynamoDB project’s dev target. No source files are modified.

Using DynamoDB in Agents

Import entity factories from the DynamoDB package and use them inside your agent definition:

packages/my-service/src/my-agent/agent.ts

import { createExampleEntity } from ':my-scope/my-table';

export const getAgent = async () => {
  // ...
  return new Agent({
    tools: [
      tool({
        name: 'list_examples',
        description: 'List all example items',
        func: async () => {
          const entity = await createExampleEntity();
          const result = await entity.scan.go();
          return result.data;
        },
      }),
    ],
  });
};

Infrastructure

To allow the agent’s Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.

CDK

packages/infra/src/stacks/application-stack.ts

import { MyTable } from ':my-scope/common-constructs';

const table = new MyTable(this, 'Table');
const myAgent = new MyAgent(this, 'MyAgent');

table.grantReadWriteData(myAgent);

grantReadWriteData grants both the DynamoDB and KMS permissions to the agent’s execution role.

Terraform

packages/infra/src/main.tf

module "my_table" {
  source = "../../common/terraform/src/app/dynamodb/my-table"
}

resource "aws_iam_role_policy" "dynamodb_access" {
  role = module.my_agent.lambda_role_name

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = [
          "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
          "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
          "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
        ]
        Resource = [
          module.my_table.table_arn,
          "${module.my_table.table_arn}/index/*",
        ]
      },
      {
        Effect = "Allow"
        Action = [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = [module.my_table.kms_key_arn]
      },
    ]
  })
}

Local Development

The connection generator configures your project’s dev target to depend on the DynamoDB project’s dev target. DynamoDB Local will start automatically alongside your project when running dev.

The LOCAL_DEV=true environment variable is set automatically, so getDynamoDBClient() and resolveTableName() connect to the local DynamoDB Local instance instead of AWS.