Python Agent para Banco de Dados Relacional

O gerador connection conecta um Python Agent a um projeto de Banco de Dados Relacional Python, tornando a sessão do banco de dados disponível dentro das ferramentas do seu agente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto py#agent
2. Um projeto py#rdb

Uso

Executar o Gerador

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Selecione seu projeto Agent como origem e seu projeto de banco de dados relacional como destino. Se o projeto contiver múltiplos componentes de agente, especifique sourceComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

• Directorypackages/my_service

  • project.json Adiciona uma dependência de my_agent-dev no target dev do banco de dados
  • pyproject.toml Adiciona o pacote do banco de dados como uma dependência do workspace
  • Directorymy_service

    • Directorymy_agent

      • Dockerfile Adiciona o pacote CA do RDS usado para conexões diretas ao Aurora

Usando o Banco de Dados nas Ferramentas do Agente

Importe session_context do seu pacote de banco de dados e use-o dentro das ferramentas do seu agente:

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()]

Infraestrutura

O construto de agente gerado implementa IGrantable e IConnectable, então você pode conceder acesso de rede e IAM ao banco de dados diretamente no construto.

CDK

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

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

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

allowDefaultPortFrom abre a regra do grupo de segurança para que o runtime do agente possa alcançar a porta do banco de dados. grantConnect concede permissão IAM rds-db:connect à função de execução do agente.

Terraform

Execute o agente dentro da mesma VPC que o banco de dados, conceda a ele rds-db:connect via additional_iam_policy_statements, e abra o caminho de rede com um par de regras de grupo de segurança:

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
  lambda_subnet_ids   = module.vpc.private_subnet_ids
}

module "my_agent" {
  source     = "../../common/terraform/src/app/agents/my-agent"
  enable_vpc = true
  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

  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" {
  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" {
  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 vêm da aplicação AppConfig de configuração de runtime compartilhada declarada uma vez no seu módulo raiz, não do módulo do banco de dados.

Requisitos SSL ao Conectar Sem RDS Proxy

Quando o agente se conecta diretamente ao cluster Aurora (sem RDS Proxy), o gerador de conexão atualiza o Dockerfile do agente gerado para instalar o pacote CA do Amazon RDS no armazenamento de confiança do sistema:

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

Ao usar RDS Proxy, você não precisa configurar o pacote CA do RDS no runtime do agente.

Desenvolvimento Local

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>

Isso inicia o agente e todos os bancos de dados conectados. A variável de ambiente LOCAL_DEV=true faz com que o cliente do banco de dados se conecte ao seu banco de dados Docker local em vez do Aurora.