Python Agent a Base de Datos Relacional

El generador connection conecta un Python Agent a un proyecto de Base de Datos Relacional Python, haciendo que la sesión de base de datos esté disponible dentro de las herramientas de tu agente.

Requisitos Previos

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

Un proyecto py#agent
Un proyecto py#rdb

Uso

Ejecutar el Generador

Ejecute este generador@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Construya su comando5

sourceProjectRequerido

targetProjectRequerido

sourceComponent

targetComponent

preferInstallDependencies

true

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

Selecciona tu proyecto Agent como origen y tu proyecto de base de datos relacional como destino. Si el proyecto contiene múltiples componentes de agente, especifica sourceComponent para desambiguar.

Opciones

Opciones del generador5 opciones

sourceProjectRequeridostring: El proyecto de origen
targetProjectRequeridostring: El proyecto de destino al que conectar
sourceComponentstring: El componente de origen desde el cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como origen.
targetComponentstring: El componente de destino al cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependenciesbooleanPredeterminado: 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

Directoriopackages/my_service
- project.json Agrega una dependencia de my_agent-dev en el target dev de la base de datos
- pyproject.toml Agrega el paquete de base de datos como una dependencia del workspace
- Directoriomy_service
  - Directoriomy_agent
    Dockerfile Agrega el paquete de CA de RDS utilizado para conexiones directas a Aurora (solo cuando el infra del agente es agentcore-ecr)

Usar la Base de Datos en las Herramientas del Agente

Importa session_context desde tu paquete de base de datos y úsalo dentro de las herramientas de tu agente:

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:
        items = (await session.execute(select(ExampleModel))).scalars().all()
        return [item.model_dump() for item in items]

Infraestructura

El constructo de agente generado implementa IGrantable e IConnectable, por lo que puedes otorgar acceso de red e IAM a la base de datos directamente en el constructo.

CDK
Terraform

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 abre la regla del grupo de seguridad para que el runtime del agente pueda alcanzar el puerto de la base de datos. grantConnect otorga el permiso IAM rds-db:connect al rol de ejecución del agente.

Ejecuta el agente dentro de la misma VPC que la base de datos, otórgale rds-db:connect a través de additional_iam_policy_statements, y abre la ruta de red con un par de reglas de grupo de seguridad. Los recursos aws_vpc.main y aws_subnet están definidos en la guía de despliegue de la base de datos:

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 provienen de la aplicación AppConfig de configuración de runtime compartida declarada una vez en tu módulo raíz, no del módulo de base de datos. Esa aplicación expone el namespace database por defecto, por lo que la entrada de configuración de runtime del módulo de base de datos se despliega sin configuración adicional.

Requisitos SSL al Conectar sin RDS Proxy

Cuando el agente se conecta directamente al clúster Aurora (sin RDS Proxy), el generador de conexión actualiza el Dockerfile del agente generado para instalar el paquete de CA de Amazon RDS en el almacén de confianza del 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

Cuando uses RDS Proxy, no necesitas configurar el paquete de CA de RDS en el runtime del agente.

Desarrollo Local

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

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

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

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

Esto inicia el agente y todas las bases de datos conectadas. La variable de entorno LOCAL_DEV=true hace que el cliente de base de datos se conecte a su base de datos Docker local en lugar de Aurora.