Python Agent에서 관계형 데이터베이스로

connection 생성기는 Python Agent를 Python Relational Database 프로젝트에 연결하여 에이전트 도구 내에서 데이터베이스 세션을 사용할 수 있도록 합니다.

사전 요구 사항

이 생성기를 사용하기 전에 다음이 필요합니다:

1. py#agent 프로젝트
2. py#rdb 프로젝트

사용법

생성기 실행

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

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - connection
5. 필수 매개변수 입력
6. 클릭 Generate

Agent 프로젝트를 소스로, 관계형 데이터베이스 프로젝트를 타겟으로 선택하세요. 프로젝트에 여러 에이전트 컴포넌트가 포함되어 있는 경우 sourceComponent를 지정하여 명확히 구분하세요.

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

• 디렉터리packages/my_service

  • project.json my_agent-dev에서 데이터베이스의 dev 타겟으로의 의존성 추가
  • pyproject.toml 데이터베이스 패키지를 워크스페이스 의존성으로 추가
  • 디렉터리my_service

    • 디렉터리my_agent

      • Dockerfile 직접 Aurora 연결에 사용되는 RDS CA 번들 추가

Agent 도구에서 데이터베이스 사용

데이터베이스 패키지에서 session_context를 가져와 에이전트 도구 내에서 사용하세요:

packages/my_service/my_service/my_agent/agent.py

from sqlmodel import select
from my_scope.my_db import session_context
from my_scope.my_db.models.example import ExampleModel
from strands import tool

@tool
async def list_examples() -> list:
    """List all example records."""
    async with session_context() as session:
        return [item.model_dump() for item in (await session.execute(select(ExampleModel))).all()]

인프라

생성된 에이전트 구성은 IGrantable 및 IConnectable을 구현하므로 구성에서 직접 데이터베이스에 대한 네트워크 및 IAM 액세스를 부여할 수 있습니다.

CDK

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

import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
import { MyDatabase } from '@my-scope/common-constructs';

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

const myAgent = new MyAgent(this, 'MyAgent', {
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    securityGroups: [
      new SecurityGroup(this, 'MyAgentSecurityGroup', { vpc, allowAllOutbound: true }),
    ],
  }),
});

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

allowDefaultPortFrom은 에이전트 런타임이 데이터베이스 포트에 도달할 수 있도록 보안 그룹 규칙을 엽니다. grantConnect는 에이전트의 실행 역할에 IAM rds-db:connect 권한을 부여합니다.

Terraform

에이전트를 데이터베이스와 동일한 VPC 내에서 실행하고, additional_iam_policy_statements를 통해 rds-db:connect를 부여하며, 보안 그룹 규칙 쌍으로 네트워크 경로를 엽니다. aws_vpc.main 및 aws_subnet 리소스는 데이터베이스 배포 가이드에 정의되어 있습니다:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "my_agent" {
  source     = "../../common/terraform/src/app/agents/my-agent"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "agent_to_database" {
  description                  = "Allow the agent runtime to connect to the database"
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.my_agent.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "agent_to_database" {
  description                  = "Allow outbound traffic from the agent runtime to the database"
  security_group_id            = module.my_agent.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

appconfig_application_id/appconfig_application_arn은 데이터베이스 모듈이 아닌 루트 모듈에서 한 번 선언된 공유 런타임 구성 AppConfig 애플리케이션에서 가져옵니다. 데이터베이스 모듈의 런타임 구성 항목이 배포되도록 인스턴스화할 때 database 네임스페이스를 포함하세요:

packages/infra/src/main.tf

module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database"]
}

RDS Proxy 없이 연결할 때의 SSL 요구 사항

에이전트가 Aurora 클러스터에 직접 연결할 때(RDS Proxy 없이), 연결 생성기는 생성된 에이전트 Dockerfile을 업데이트하여 Amazon RDS CA 번들을 시스템 신뢰 저장소에 설치합니다:

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
RUN update-ca-certificates

RDS Proxy를 사용하는 경우 에이전트 런타임에서 RDS CA 번들을 구성할 필요가 없습니다.

로컬 개발

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

이렇게 하면 에이전트와 연결된 모든 데이터베이스가 시작됩니다. LOCAL_DEV=true 환경 변수는 데이터베이스 클라이언트가 Aurora 대신 로컬 Docker 데이터베이스에 연결하도록 합니다.