Python Agent a Database Relazionale

Il generatore connection collega un Python Agent a un progetto Python Relational Database, rendendo la sessione del database disponibile all’interno degli strumenti del tuo agent.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

Un progetto py#agent
Un progetto py#rdb

Utilizzo

Esegui il Generatore

Esegui questo generatore@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

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Seleziona il tuo progetto Agent come sorgente e il tuo progetto database relazionale come destinazione. Se il progetto contiene più componenti agent, specifica sourceComponent per disambiguare.

Opzioni

Opzioni del generatore5 opzioni

sourceProjectObbligatoriostring: Il progetto sorgente
targetProjectObbligatoriostring: Il progetto di destinazione a cui connettersi
sourceComponentstring: Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come sorgente.
targetComponentstring: Il componente destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto destinazione, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependenciesbooleanPredefinito: true: Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Directorypackages/my_service
- project.json Aggiunge una dipendenza da my_agent-dev sul target dev del database
- pyproject.toml Aggiunge il pacchetto database come dipendenza del workspace
- Directorymy_service
  - Directorymy_agent
    Dockerfile Aggiunge il bundle CA RDS utilizzato per le connessioni dirette ad Aurora (solo quando l’infra dell’agent è agentcore-ecr)

Utilizzo del Database negli Strumenti dell’Agent

Importa session_context dal tuo pacchetto database e utilizzalo all’interno degli strumenti del tuo agent:

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]

Infrastruttura

Il costrutto agent generato implementa IGrantable e IConnectable, quindi puoi concedere l’accesso di rete e IAM al database direttamente sul costrutto.

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 apre la regola del security group in modo che il runtime dell’agent possa raggiungere la porta del database. grantConnect concede il permesso IAM rds-db:connect al ruolo di esecuzione dell’agent.

Esegui l’agent all’interno dello stesso VPC del database, concedigli rds-db:connect tramite additional_iam_policy_statements e apri il percorso di rete con una coppia di regole del security group. Le risorse aws_vpc.main e aws_subnet sono definite nella guida al deployment del database:

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 provengono dall’applicazione AppConfig di configurazione runtime condivisa dichiarata una volta nel tuo modulo root, non dal modulo database. Quell’applicazione espone il namespace database per impostazione predefinita, quindi la voce di configurazione runtime del modulo database viene distribuita senza ulteriore configurazione.

Requisiti SSL per la Connessione Senza RDS Proxy

Quando l’agent si connette direttamente al cluster Aurora (senza RDS Proxy), il generatore di connessione aggiorna il Dockerfile dell’agent generato per installare il bundle CA Amazon RDS nel trust store 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

Quando si utilizza RDS Proxy, non è necessario configurare il bundle CA RDS nel runtime dell’agent.

Sviluppo Locale

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>

Questo avvia l’agent e tutti i database connessi. La variabile d’ambiente LOCAL_DEV=true fa sì che il client del database si connetta al suo database Docker locale invece che ad Aurora.