Python Agent to DynamoDB

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

Prerequisites

Before using this generator, ensure you have:

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

Usage

Run the Generator

Run this generator@aws/nx-plugin:connection

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

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

Build your command5

sourceProjectRequired

targetProjectRequired

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

Generator Options5 options

sourceProjectRequiredstring

The source project

targetProjectRequiredstring

The target project to connect to

sourceComponentstring

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.

targetComponentstring

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.

preferInstallDependenciesbooleanDefault: 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, and adds the DynamoDB package as a workspace dependency. No source files are modified.

Using DynamoDB in Agents

Import entity classes from the DynamoDB package and use them inside your agent tools:

packages/my_project/my_project/my_agent/agent.py

from my_scope_my_table.entities.example import ExampleModel
from strands import tool

@tool
def list_examples() -> list:
    """List all example items."""
    return [item.attribute_values for item in ExampleModel.scan()]

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

Grant the agent’s runtime role access to the table and its KMS encryption key via additional_iam_policy_statements:

packages/infra/src/main.tf

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

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

  additional_iam_policy_statements = [
    {
      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 is_local() returns True and your PynamoDB entities connect to the local DynamoDB instance instead of AWS.