Configura Amazon Bedrock AgentCore Runtime e gli strumenti per VPC

Puoi configurare Amazon Bedrock AgentCore Runtime e gli strumenti integrati (Code Interpreter e Browser Tool) per connetterti alle risorse del tuo Amazon Virtual Private Cloud (VPC). Configurando la connettività VPC, abiliti l'accesso sicuro a risorse private come database, API interne e servizi all'interno del tuo VPC.

Connettività VPC per Amazon Bedrock AgentCore Runtime e strumenti

Per consentire ad Amazon Bedrock AgentCore Runtime e agli strumenti integrati di accedere in modo sicuro alle risorse nel tuo VPC privato, fornisce funzionalità di connettività AgentCore VPC. Questa funzionalità consente al runtime e agli strumenti di:

Quando configuri la connettività VPC per Amazon Bedrock AgentCore Runtime e gli strumenti:

Prerequisiti

Prima di configurare Amazon Bedrock AgentCore Runtime e gli strumenti per l'accesso al VPC, assicurati di disporre di:

Zone di disponibilità supportate

AgentCore supporta la connettività VPC in zone di disponibilità specifiche all'interno di ciascuna regione supportata. Quando configuri le sottoreti per Amazon Bedrock AgentCore Runtime e gli strumenti integrati, assicurati che le sottoreti si trovino nelle zone di disponibilità supportate per la tua regione.

La tabella seguente mostra gli ID delle zone di disponibilità supportati per ogni regione:

Per identificare l'ID della zona di disponibilità delle sottoreti, è possibile utilizzare il seguente comando CLI:

aws ec2 describe-subnets --subnet-ids subnet-12345678 --query 'Subnets[0].AvailabilityZoneId'

autorizzazioni IAM

AgentCore utilizza il ruolo collegato al servizio AWSServiceRoleForBedrockAgentCoreNetwork per creare e gestire interfacce di rete nel tuo VPC. Questo ruolo viene creato automaticamente quando configuri per la prima volta Amazon Bedrock AgentCore Runtime o gli strumenti AgentCore integrati per utilizzare la connettività VPC.

Se devi creare questo ruolo manualmente, la tua entità IAM necessita delle seguenti autorizzazioni:

{
    "Action": "iam:CreateServiceLinkedRole",
    "Effect": "Allow",
    "Resource": "arn:aws:iam::*:role/aws-service-role/network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreNetwork",
    "Condition": {
        "StringLike": {
            "iam:AWSServiceName": "network.bedrock-agentcore.amazonaws.com"
        }
    }
}

Questa autorizzazione è già inclusa nella policy AWS BedrockAgentCoreFullAccessgestita.

Best practice

Per prestazioni e sicurezza ottimali con VPC-connected Amazon Bedrock AgentCore Runtime e strumenti integrati:

Configurazione dell'accesso VPC per runtime e strumenti

Puoi configurare l'accesso al VPC per Amazon Bedrock AgentCore Runtime e gli strumenti integrati utilizzando la console di AWS gestione, la AWS CLI o gli SDK. AWS

Configurazione di runtime

Configurazione di Code Interpreter

Configurazione dello strumento Browser

Considerazioni relative al gruppo di sicurezza

I gruppi di sicurezza agiscono come firewall virtuali per Amazon Bedrock AgentCore Runtime o come strumento integrato quando connesso a un VPC. Controllano il traffico in entrata e in uscita a livello di istanza. Per configurare i gruppi di sicurezza per il tuo runtime:

Esempio: connessione a un database Amazon RDS

Quando Amazon Bedrock AgentCore Runtime si connette a un database Amazon RDS, configura i gruppi di sicurezza come segue:

Gruppo di sicurezza Amazon Bedrock AgentCore Runtime

Gruppo di sicurezza del database Amazon RDS

Esempio: connessione a file Amazon EFS o Amazon S3

Quando configuri i file system personalizzati (punti di accesso Amazon EFS o Amazon S3 Files) sul runtime dell'agente, AgentCore Runtime monta il file system su NFS. Ciò richiede la connettività TCP sulla porta 2049 tra gli ENI di runtime dell'agente e gli obiettivi di montaggio del file system.

AgentCore gestisce automaticamente la crittografia TLS e l'autenticazione IAM. Il amazon-efs-utils mount helper è preinstallato nel runtime MicroVM: non è necessario configurare o installare alcun software di montaggio nell'immagine del contenitore.

Configurazione del gruppo di sicurezza

Configura i tuoi gruppi di sicurezza per consentire il traffico NFS tra il runtime dell'agente e le destinazioni di montaggio del file system.

Gruppo di sicurezza Agent Runtime — Regola in uscita:

Gruppo di sicurezza target di montaggio sul file system — Regola in entrata:

Sostituisci sg-mounttarget con l'ID del gruppo di sicurezza delle destinazioni di montaggio EFS o S3 Files e sg-agentruntime con l'ID del gruppo di sicurezza utilizzato dal runtime dell'agente.

AWS CLI: aggiungi la regola in uscita al gruppo di sicurezza Agent Runtime:

aws ec2 authorize-security-group-egress \
  --group-id sg-0123456789abcdef0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0987654321fedcba0

AWS CLI: aggiungi una regola in entrata per montare il gruppo di sicurezza di destinazione:

aws ec2 authorize-security-group-ingress \
  --group-id sg-0987654321fedcba0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0123456789abcdef0

Configurazione degli endpoint VPC

Quando esegui Amazon Bedrock AgentCore Runtime in un VPC, consigliamo vivamente di configurare i seguenti endpoint VPC. Questi endpoint sono necessari se il tuo VPC non dispone di accesso a Internet e fortemente consigliati anche se il tuo VPC dispone di un gateway NAT, per evitare i costi di elaborazione dei dati del gateway NAT.

Endpoint VPC richiesti

Considerazioni sull'accesso a Internet

Quando colleghi Amazon Bedrock AgentCore Runtime o uno strumento integrato a un Virtual Private Cloud (VPC), per impostazione predefinita non è disponibile l'accesso a Internet. Per impostazione predefinita, queste risorse possono comunicare solo con risorse all'interno dello stesso VPC. Se il runtime o lo strumento richiedono l'accesso sia alle risorse VPC che a Internet, è necessario configurare il VPC di conseguenza.

Architettura di accesso a Internet

Per abilitare l'accesso a Internet per VPC-connected Amazon Bedrock AgentCore Runtime o per lo strumento integrato, configura il tuo VPC con i seguenti componenti:

Configurazione dell'instradamento

Aggiorna le tabelle di routing della sottorete come segue:

Monitoraggio e risoluzione dei problemi

Per monitorare e risolvere i problemi di VPC-connected Amazon Bedrock AgentCore Runtime e degli strumenti:

CloudWatch Registri

Abilita CloudWatch i log per Amazon Bedrock AgentCore Runtime per identificare eventuali problemi di connettività:

Problemi e soluzioni comuni

Problemi con Code Interpreter

Problemi con lo strumento Browser

Test della connettività VPC

Per verificare che il AgentCore Runtime e gli strumenti dispongano di una connettività VPC adeguata, puoi testare le connessioni alle tue risorse private e verificare che le interfacce di rete siano create correttamente nelle sottoreti specificate.

Per verificare che il tuo AgentCore strumento abbia accesso a Internet, puoi configurare un interprete di codice con la tua configurazione VPC e utilizzare Invoke l'API executeCommand per tentare di connettersi a un'API o a un sito Web pubblico curl utilizzando il comando e controllare la risposta. Se la connessione scade, rivedi la configurazione del VPC, in particolare le tabelle di routing e la configurazione del gateway NAT.

# Using awscurl
awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/code-interpreters/<code_interpreter_id>/tools/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-code-interpreter-session-id: your-session-id" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "name": "executeCommand",
    "arguments": {
      "command": "curl amazon.com"
    }
  }'

Problemi di connettività del file system

Quando il montaggio di un file system fallisce, l'InvokeAgentRuntimeAPI restituisce lo stato HTTP 424 (Failed Dependency). Utilizza le seguenti sezioni per diagnosticare la causa principale.

Timeout di montaggio del file system

Sintomi: le chiamate agli agenti con configurazioni del file system non riescono dopo un ritardo prolungato. L'errore indica che l'operazione di montaggio è scaduta.

Cause e soluzioni comuni:

1. Mancano le regole del gruppo di sicurezza

Verifica la regola in uscita sul tuo gruppo di sicurezza Agent Runtime:

aws ec2 describe-security-groups \
  --group-ids sg-0123456789abcdef0 \
  --query 'SecurityGroups[0].IpPermissionsEgress[?ToPort==`2049`]'

Verifica la regola in entrata sul tuo gruppo di sicurezza Mount Target:

aws ec2 describe-security-groups \
  --group-ids sg-0987654321fedcba0 \
  --query 'SecurityGroups[0].IpPermissions[?ToPort==`2049`]'

Se una delle query restituisce risultati vuoti, aggiungi la regola mancante come mostrato in Esempio: connessione ad Amazon EFS o Amazon S3 Files.

2. Nessun target di montaggio nella zona di disponibilità dell'agente

Il runtime dell'agente potrebbe essere collocato in una zona di disponibilità in cui non esiste alcun target di montaggio. Verifica la sovrapposizione:

# Get agent runtime subnet AZs
aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 subnet-0123456789abcdef1 \
  --query 'Subnets[*].[SubnetId, AvailabilityZoneId]' --output table

# Get EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' --output table

Soluzione: create un target di montaggio in ogni zona di disponibilità in cui si trovano le sottoreti di runtime degli agenti o limita le sottoreti di runtime degli agenti alle zone di disponibilità in cui esistono obiettivi di montaggio.

3. Nella tabella delle rotte manca la rotta locale

Verifica che la tabella di routing associata alle sottoreti di runtime dell'agente includa la route VPC locale:

aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=subnet-0123456789abcdef0" \
  --query 'RouteTables[0].Routes[?DestinationCidrBlock]'

Il montaggio del file system fallisce con "» ResourceNotFound

Sintomi: la chiamata dell'agente fallisce immediatamente (senza timeout) con un ResourceNotFound errore di riferimento al nome host del file system.

Cause e soluzioni comuni:

1. Errore di risoluzione DNS: il VPC non è in grado di risolvere il nome host della destinazione di montaggio del file system.

Verifica le impostazioni DNS sul tuo VPC:

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsSupport

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsHostnames

Entrambi devono tornare. true In caso contrario, abilitali:

aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-support
aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-hostnames

2. La destinazione di montaggio non è disponibile: la destinazione di montaggio potrebbe essere ancora in fase di creazione o potrebbe essere stata eliminata.

# For EFS
aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0

# For S3 Files
aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0

Assicurati che il target di montaggio LifeCycleState siaavailable. Se manca il target di montaggio, ricrealo nelle sottoreti appropriate.

3. File system o punto di accesso eliminato: la risorsa a cui si fa riferimento nella configurazione del runtime dell'agente non esiste più. Verifica e aggiorna il runtime dell'agente con ARN validi.

Mancata corrispondenza della zona di disponibilità (guasti intermittenti)

Sintomi: i montaggi del file system vengono eseguiti a intermittenza: alcune chiamate funzionano mentre altre falliscono a causa dei timeout.

Perché questo accade: il runtime dell'agente dispone di sottoreti in più zone di disponibilità, ma i mount target esistono solo in alcune di esse. Quando l'agente viene posizionato in una AZ senza un target di montaggio, il mount scade.

Soluzione: create target di montaggio in tutte le zone di disponibilità in cui si trovano le sottoreti di runtime dell'agente (scelta consigliata) oppure rimuovete le sottoreti di runtime dell'agente che si trovano nelle zone di disponibilità senza target di montaggio.

# List all EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].AvailabilityZoneId' --output text

# Create a mount target in a missing AZ
aws efs create-mount-target \
  --file-system-id fs-0123456789abcdef0 \
  --subnet-id subnet-in-missing-az \
  --security-groups sg-0987654321fedcba0