Amazon Bedrock AgentCore Runtime und Tools für VPC konfigurieren

Sie können Amazon Bedrock AgentCore Runtime und integrierte Tools (Code Interpreter und Browser Tool) konfigurieren, um eine Verbindung zu Ressourcen in Ihrer Amazon Virtual Private Cloud (VPC) herzustellen. Durch die Konfiguration der VPC-Konnektivität ermöglichen Sie den sicheren Zugriff auf private Ressourcen wie Datenbanken, interne APIs und Dienste innerhalb Ihrer VPC.

VPC-Konnektivität für Amazon Bedrock AgentCore Runtime und Tools

Damit Amazon Bedrock AgentCore Runtime und integrierte Tools sicher auf Ressourcen in Ihrer privaten VPC zugreifen können, AgentCore bietet VPC-Konnektivitätsfunktionen. Diese Funktion ermöglicht Ihrer Runtime und Ihren Tools:

Wenn Sie die VPC-Konnektivität für Amazon Bedrock AgentCore Runtime und Tools konfigurieren:

Voraussetzungen

Bevor Sie Amazon Bedrock AgentCore Runtime und Tools für den VPC-Zugriff konfigurieren, stellen Sie sicher, dass Sie über Folgendes verfügen:

Unterstützte Availability Zones

AgentCore unterstützt VPC-Konnektivität in bestimmten Availability Zones innerhalb jeder unterstützten Region. Stellen Sie bei der Konfiguration von Subnetzen für Ihre Amazon Bedrock AgentCore Runtime und die integrierten Tools sicher, dass sich Ihre Subnetze in den unterstützten Availability Zones für Ihre Region befinden.

Die folgende Tabelle zeigt die unterstützten Availability Zone-IDs für jede Region:

Um die Availability Zone ID Ihrer Subnetze zu identifizieren, können Sie den folgenden CLI-Befehl verwenden:

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

IAM-Berechtigungen

AgentCore verwendet die serviceverknüpfte RolleAWSServiceRoleForBedrockAgentCoreNetwork, um Netzwerkschnittstellen in Ihrer VPC zu erstellen und zu verwalten. Diese Rolle wird automatisch erstellt, wenn Sie Amazon Bedrock AgentCore Runtime oder AgentCore integrierte Tools zum ersten Mal für die Verwendung von VPC-Konnektivität konfigurieren.

Wenn Sie diese Rolle manuell erstellen müssen, benötigt Ihre IAM-Entität die folgenden Berechtigungen:

{
    "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"
        }
    }
}

Diese Berechtigung ist bereits in der AWS verwalteten Richtlinie BedrockAgentCoreFullAccessenthalten.

Bewährte Methoden

Für optimale Leistung und Sicherheit mit VPC-connected Amazon Bedrock AgentCore Runtime und integrierten Tools:

Konfiguration des VPC-Zugriffs für Runtime und Tools

Sie können den VPC-Zugriff für Amazon Bedrock AgentCore Runtime und integrierte Tools mithilfe der AWS Management Console, AWS CLI oder AWS SDKs konfigurieren.

Laufzeitkonfiguration

Konfiguration des Codeinterpreters

Konfiguration des Browser-Tools

Überlegungen zu Sicherheitsgruppen

Sicherheitsgruppen fungieren als virtuelle Firewalls für Ihre Amazon Bedrock AgentCore Runtime oder als integriertes Tool, wenn sie mit einer VPC verbunden sind. Sie kontrollieren den eingehenden und ausgehenden Datenverkehr auf Instance-Ebene. So konfigurieren Sie Sicherheitsgruppen für Ihre Laufzeit:

Beispiel: Verbindung zu einer Amazon RDS-Datenbank herstellen

Wenn Ihre Amazon Bedrock AgentCore Runtime eine Verbindung zu einer Amazon RDS-Datenbank herstellt, konfigurieren Sie die Sicherheitsgruppen wie folgt:

Amazon Bedrock AgentCore Runtime-Sicherheitsgruppe

Amazon RDS-Datenbanksicherheitsgruppe

Beispiel: Verbindung zu Amazon EFS- oder Amazon S3 S3-Dateien herstellen

Wenn Sie Bring-Your-Own-Dateisysteme (Amazon EFS- oder Amazon S3 Files-Zugriffspunkte) auf Ihrer Agenten-Runtime konfigurieren, mountet Runtime das AgentCore Dateisystem über NFS. Dies erfordert TCP-Konnektivität auf Port 2049 zwischen den Agent-Runtime-ENIs und den Dateisystem-Mount-Zielen.

AgentCore verarbeitet TLS-Verschlüsselung und IAM-Authentifizierung automatisch. Der amazon-efs-utils Mount Helper ist in der MicroVM Runtime vorinstalliert — Sie müssen keine Mount-Software in Ihrem Container-Image konfigurieren oder installieren.

Sicherheitsgruppenkonfiguration

Konfigurieren Sie Ihre Sicherheitsgruppen so, dass NFS-Verkehr zwischen der Agent-Runtime und den Mount-Zielen Ihres Dateisystems zugelassen wird.

Agenten-Runtime-Sicherheitsgruppe — Regel für ausgehenden Datenverkehr:

Zielsicherheitsgruppe zum Einhängen des Dateisystems — Regel für eingehenden Datenverkehr:

sg-mounttargetErsetzen Sie durch die Sicherheitsgruppen-ID Ihrer EFS- oder S3 Files-Mount-Ziele und sg-agentruntime durch die Sicherheitsgruppen-ID, die von Ihrer Agent-Laufzeit verwendet wird.

AWS CLI — Regel für ausgehenden Datenverkehr zur Runtime-Sicherheitsgruppe des Agenten hinzufügen:

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

AWS CLI — Regel für eingehenden Datenverkehr zur Bereitstellung der Zielsicherheitsgruppe hinzufügen:

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

VPC-Endpunktkonfiguration

Wenn Sie Amazon Bedrock AgentCore Runtime in einer VPC ausführen, empfehlen wir dringend, die folgenden VPC-Endpunkte zu konfigurieren. Diese Endpunkte sind erforderlich, wenn Ihre VPC keinen Internetzugang hat. Sie werden dringend empfohlen, auch wenn Ihre VPC über ein NAT-Gateway verfügt, um Gebühren für die Datenverarbeitung am NAT-Gateway zu vermeiden.

Erforderliche VPC-Endpunkte

Überlegungen zum Internetzugang

Wenn Sie Amazon Bedrock AgentCore Runtime oder ein integriertes Tool mit einer Virtual Private Cloud (VPC) verbinden, hat es standardmäßig keinen Internetzugang. Standardmäßig können diese Ressourcen nur mit Ressourcen innerhalb derselben VPC kommunizieren. Wenn Ihre Runtime oder Ihr Tool Zugriff sowohl auf VPC-Ressourcen als auch auf das Internet benötigt, müssen Sie Ihre VPC entsprechend konfigurieren.

Architektur des Internetzugangs

Um den Internetzugang für Ihre VPC-connected Amazon Bedrock AgentCore Runtime oder Ihr integriertes Tool zu aktivieren, konfigurieren Sie Ihre VPC mit den folgenden Komponenten:

Weiterleitungskonfiguration

Aktualisieren Sie Ihre Subnetz-Routentabellen wie folgt:

Überwachung und Problembehebung

Um Ihre VPC-connected Amazon Bedrock AgentCore Runtime und Tools zu überwachen und Fehler zu beheben:

CloudWatch Logs

Aktivieren Sie CloudWatch Logs für Ihre Amazon Bedrock AgentCore Runtime, um Verbindungsprobleme zu identifizieren:

Häufige Probleme und Lösungen

Probleme mit dem Codeinterpreter

Probleme mit dem Browser-Tool

VPC-Konnektivität testen

Um zu überprüfen, ob Ihre AgentCore Runtime und Ihre Tools über die richtige VPC-Konnektivität verfügen, können Sie Verbindungen zu Ihren privaten Ressourcen testen und sicherstellen, dass Netzwerkschnittstellen in den angegebenen Subnetzen korrekt erstellt wurden.

Um zu überprüfen, ob Ihr AgentCore Tool über Internetzugang verfügt, können Sie einen Code-Interpreter mit Ihrer VPC-Konfiguration konfigurieren und die Invoke API verwendenexecuteCommand, um mithilfe eines curl Befehls eine Verbindung zu einer öffentlichen API oder Website herzustellen und die Antwort zu überprüfen. Wenn die Verbindung unterbrochen wird, überprüfen Sie Ihre VPC-Konfiguration, insbesondere Ihre Routing-Tabellen und das NAT-Gateway-Setup.

# 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"
    }
  }'

Probleme mit der Dateisystem-Konnektivität

Wenn ein Dateisystem-Mount fehlschlägt, gibt die InvokeAgentRuntime API den HTTP-Status 424 (Fehlgeschlagene Abhängigkeit) zurück. Verwenden Sie die folgenden Abschnitte, um die Grundursache zu diagnostizieren.

Beim Einhängen des Dateisystems wird das Zeitlimit überschritten

Symptome: Agentenaufrufe mit Dateisystemkonfigurationen schlagen nach einer längeren Verzögerung fehl. Der Fehler weist darauf hin, dass das Zeitlimit für den Mount-Vorgang überschritten wurde.

Häufige Ursachen und Lösungen:

1. Es fehlen Regeln für Sicherheitsgruppen

Überprüfen Sie die Regel für ausgehenden Datenverkehr in Ihrer Runtime-Sicherheitsgruppe für Agenten:

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

Überprüfen Sie die Regel für eingehenden Datenverkehr in Ihrer Mount-Zielsicherheitsgruppe:

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

Wenn eine der Abfragen leere Ergebnisse zurückgibt, fügen Sie die fehlende Regel hinzu, wie in Beispiel: Verbindung zu Amazon EFS- oder Amazon S3 S3-Dateien herstellen gezeigt.

2. Kein Mount-Ziel in der Availability Zone des Agenten

Die Agenten-Laufzeit befindet sich möglicherweise in einer Availability Zone, in der kein Mount-Ziel existiert. Überschneidung überprüfen:

# 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

Lösung: Erstellen Sie in jeder Availability Zone, in der sich Ihre Agenten-Runtime-Subnetze befinden, ein Mount-Ziel, oder beschränken Sie Agent-Runtime-Subnetze auf Availability Zones, in denen Mount-Ziele existieren.

3. In der Routentabelle fehlt die lokale Route

Stellen Sie sicher, dass die Routing-Tabelle, die Ihren Agent-Runtime-Subnetzen zugeordnet ist, die lokale VPC-Route enthält:

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

Das Einhängen des Dateisystems schlägt mit "“ fehl ResourceNotFound

Symptome: Der Agentenaufruf schlägt sofort (ohne Timeout) fehl und es wird ein ResourceNotFound Fehler beim Verweis auf den Hostnamen des Dateisystems angezeigt.

Häufige Ursachen und Lösungen:

1. Fehler bei der DNS-Auflösung — Die VPC kann den Hostnamen des Dateisystem-Mount-Ziels nicht auflösen.

Überprüfen Sie die DNS-Einstellungen auf Ihrer VPC:

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

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

Beide müssen zurückkehrentrue. Wenn nicht, aktiviere sie:

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. Mount-Ziel nicht im Status „Verfügbar“ — Das Mount-Ziel wird möglicherweise noch erstellt oder wurde möglicherweise gelöscht.

# 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

Stellen Sie sicher, dass das Mount-Ziel LifeCycleState available Wenn das Mount-Ziel fehlt, erstellen Sie es in den entsprechenden Subnetzen neu.

3. Dateisystem oder Zugriffspunkt gelöscht — Die Ressource, auf die in der Laufzeitkonfiguration des Agenten verwiesen wird, ist nicht mehr vorhanden. Überprüfen und aktualisieren Sie die Agenten-Laufzeit mit gültigen ARNs.

Nichtübereinstimmung der Availability Zone (zeitweilige Ausfälle)

Symptome: Dateisystem-Bereitstellungen sind zeitweise erfolgreich — einige Aufrufe funktionieren, während andere aufgrund von Timeouts fehlschlagen.

Warum das passiert: Ihre Agenten-Laufzeit hat Subnetze in mehreren Availability Zones, aber Mount-Ziele existieren nur in einigen von ihnen. Wenn der Agent in einer AZ ohne Mount-Ziel platziert wird, kommt es bei der Bereitstellung zu einem Timeout.

Lösung: Erstellen Sie entweder Mount-Ziele in allen Availability Zones, in denen sich Ihre Agenten-Runtime-Subnetze befinden (empfohlen), oder entfernen Sie Agent-Runtime-Subnetze, die sich in Availability Zones ohne Mount-Ziele befinden.

# 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