TypeScript Agent から DynamoDB へ

connection ジェネレーターは、TypeScript Agent を TypeScript DynamoDB プロジェクトに接続し、両方が自動的に一緒に起動するようにローカル開発を構成します。

前提条件

このジェネレーターを使用する前に、以下を確認してください：

1. ts#agent プロジェクト
2. ts#dynamodb プロジェクト

使用方法

ジェネレーターの実行

このジェネレーターを実行@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. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - connection
5. 必須パラメータを入力
6. クリック Generate

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-run変更されるファイルを確認するためにドライランを実行することもできます

Agent プロジェクトをソースとして、DynamoDB プロジェクトをターゲットとして選択します。プロジェクトに複数のエージェントコンポーネントが含まれている場合は、sourceComponent を指定して明確にします。

オプション

ジェネレーターオプション5 オプション

sourceProject必須string

ソース プロジェクト

targetProject必須string

接続先のターゲット プロジェクト

sourceComponentstring

接続元のソースコンポーネント（コンポーネント名、ソースプロジェクトルートからの相対パス、またはジェネレーターID）。プロジェクトをソースとして明示的に選択するには '.' を使用します。

targetComponentstring

接続先のターゲットコンポーネント（コンポーネント名、ターゲットプロジェクトルートからの相対パス、またはジェネレーターID）。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。

preferInstallDependenciesbooleanデフォルト: true

ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、エージェントの <agent-name>-dev ターゲットを project.json 内で更新し、DynamoDB プロジェクトの dev ターゲットに依存するようにします。ソースファイルは変更されません。

Agent での DynamoDB の使用

DynamoDB パッケージからエンティティファクトリーをインポートし、エージェント定義内で使用します：

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

import { createExampleEntity } from '@my-scope/my-table';
import { z } from 'zod';

const listExamples = tool({
  name: 'list_examples',
  description: 'List all example items',
  inputSchema: z.object({}),
  callback: async () => {
    const entity = await createExampleEntity();
    const result = await entity.scan.go();
    return result.data;
  },
});

export const getAgent = async () => {
  // ...
  return new Agent({
    tools: [listExamples],
  });
};

インフラストラクチャ

エージェントの Lambda 関数が DynamoDB テーブルにアクセスできるようにするには、インフラストラクチャで必要な権限を付与します。

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 は、エージェントの実行ロールに DynamoDB と KMS の両方の権限を付与します。

Terraform

additional_iam_policy_statements を使用して、エージェントのランタイムロールにテーブルとその KMS 暗号化キーへのアクセス権を付与します：

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

ローカル開発

connection ジェネレーターは、プロジェクトの dev ターゲットが DynamoDB プロジェクトの dev ターゲットに依存するように設定します。DynamoDB Local は dev の実行時にプロジェクトと一緒に自動的に起動します。

LOCAL_DEV=true 環境変数は自動的に設定されるため、getDynamoDBClient() と resolveTableName() は AWS ではなくローカルの DynamoDB Local インスタンスに接続します。