Agente TypeScript a DynamoDB

El generador connection conecta un Agente TypeScript a un proyecto TypeScript DynamoDB, configurando el desarrollo local para que ambos se inicien juntos automáticamente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto ts#agent
2. Un proyecto ts#dynamodb

Uso

Ejecutar el generador

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en 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

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

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

Selecciona tu proyecto Agent como origen y tu proyecto DynamoDB 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.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador actualiza el target <agent-name>-dev del agente en project.json para que dependa del target dev del proyecto DynamoDB. No se modifican archivos de código fuente.

Usar DynamoDB en Agentes

Importa las factories de entidades del paquete DynamoDB y úsalas dentro de la definición de tu agente:

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;
        },
      }),
    ],
  });
};

Infraestructura

Para permitir que la función Lambda del agente acceda a la tabla DynamoDB, otorga los permisos necesarios en tu infraestructura.

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 otorga tanto los permisos de DynamoDB como de KMS al rol de ejecución del agente.

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]
      },
    ]
  })
}

Desarrollo local

El generador connection configura el target dev de tu proyecto para que dependa del target dev del proyecto DynamoDB. DynamoDB Local se iniciará automáticamente junto con tu proyecto al ejecutar dev.

La variable de entorno LOCAL_DEV=true se establece automáticamente, por lo que getDynamoDBClient() y resolveTableName() se conectan a la instancia local de DynamoDB Local en lugar de AWS.