TypeScript Strands Agent から Relational Database への接続

connection ジェネレーターは、TypeScript Strands Agent を Relational Database プロジェクトに接続し、エージェントファクトリー内で Prisma クライアントを利用可能にします。

前提条件

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

1. ts#strands-agent プロジェクト
2. ts#rdb プロジェクト

使用方法

ジェネレーターの実行

VSCode

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

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

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

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

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソース プロジェクト
targetProject 必須	string	-	接続先のターゲット プロジェクト
sourceComponent	string	-	接続元のソース コンポーネント (コンポーネント名、ソース プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲット コンポーネント (コンポーネント名、ターゲット プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。

ジェネレーターの出力

ジェネレーターは単一のファイルを変更します：

• Directorypackages/my-service/src/my-agent

  • agent.ts getAgent 内で取得され、ツールで利用可能な Prisma クライアント

さらに、エージェントの <agent-name>-serve-local ターゲットが、データベースの serve-local ターゲットに依存するように更新されます。

仕組み

Prisma クライアントは、関数パラメーターを通じて渡されるのではなく、getAgent() 内で直接取得されます。これは、strands-agent ランタイムがセッションコンテキストを伝播する方法と一致しています — withSessionId が getAgent をラップし、セッションごとに1つの Agent インスタンスをキャッシュするため、getPrisma() はセッションごとに最大1回だけ呼び出されます。

エージェント定義

getAgent は、本体の先頭で Prisma ゲッターをインポートして呼び出すように更新されます：

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 */ });
};

複数のデータベース

異なるターゲットで再度ジェネレーターを実行すると、最初のデータベースと並んで2番目のデータベースが追加されます：

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 */ });
};

インフラストラクチャ

生成されたエージェントコンストラクトは IGrantable と IConnectable を実装しているため、コンストラクト上で直接データベースへのネットワークおよび IAM アクセスを許可できます。

CDK

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

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

const db = new MyDatabase(this, 'Db', { vpc, ... });
const myAgent = new MyAgent(this, 'MyAgent', { vpc, ... });

db.allowDefaultPortFrom(myAgent);
db.grantConnect(myAgent);

allowDefaultPortFrom は、エージェントランタイムがデータベースポートに到達できるようにセキュリティグループルールを開きます。grantConnect は、エージェントの実行ロールに IAM rds-db:connect 権限を付与します。

Terraform

データベースモジュールの出力をエージェントモジュールに渡して、データベースに到達し、そのランタイム設定を読み取れるようにします：

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
}

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

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port
}

エージェントの実行ロールが rds-db:connect 権限を持ち、そのセキュリティグループがデータベースポートでデータベースセキュリティグループに到達できることを確認してください。

ローカル開発

pnpm

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <project-name>

これにより、エージェントと接続されているすべてのデータベースが起動します。SERVE_LOCAL=true 環境変数により、各 Prisma クライアントは Aurora の代わりにローカルの Docker データベースに接続します。