Funcionamiento Iniciar una evaluación por lotes con una clave de KMS administrada por el cliente Supervisión del uso de KMS para las evaluaciones por lotes Comportamiento cuando una clave deja de estar disponible

Cifrado de evaluación por lotes

Cuando especificas una kmsKeyArn evaluación por lotes, el servicio cifra todos los artefactos de salida almacenados en S3 mediante el cifrado de S3 del lado del servidor con KMS (). SSE-KMS Esto incluye la configuración de la fuente de datos, los metadatos de la sesión y los resultados de la evaluación.

kmsKeyArnSe especifica en el momento de la creación medianteStartBatchEvaluation.

Funcionamiento

El cifrado de evaluación por lotes utiliza S3 SSE-KMS. Cuando el servicio escribe o lee los resultados de la evaluación por lotes en S3, S3 llama a KMS en nombre del servicio para cifrar o descifrar los datos. El principal del servicio (bedrock-agentcore.amazonaws.com) debe tener permisos de KMS en la política de claves.

En el momento de la API, el servicio valida que la persona que llama tiene permisos de KMS mediante una comprobación en seco (sesiones de acceso directo). Esto detecta los problemas de permisos de forma inmediata, en lugar de fallar de forma asincrónica durante el flujo de trabajo de evaluación por lotes.

El servicio también comprueba que puede trabajar kms:GenerateDataKey con sus propias credenciales para garantizar que la política de claves otorga al director del servicio los permisos necesarios para escribir la salida cifrada.

AgentCore Evaluations solo admite claves KMS de cifrado simétrico. La clave de KMS debe estar en la misma AWS región que la evaluación por lotes.

Configurar los permisos para usar una clave de KMS administrada por el cliente

La siguiente política de claves proporciona los permisos mínimos necesarios para el cifrado de la evaluación por lotes. La política tiene tres instrucciones:

AllowCallerAccess— Permite al usuario o rol de IAM validar la clave medianteDescribeKey.
AllowCallerCryptoOps— Permite al usuario o rol de IAM cifrar y descifrar según el contexto de cifrado.
AllowServicePrincipalAccess— Permite al principal del AgentCore servicio cifrar y descifrar los datos de evaluación por lotes en S3, desglosados por cuenta de origen y ARN de origen.


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCallerAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*"
    },
    {
      "Sid": "AllowCallerCryptoOps",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:EncryptionContext:aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
        }
      }
    },
    {
      "Sid": "AllowServicePrincipalAccess",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
        }
      }
    }
  ]
}

La política contiene las siguientes declaraciones:

AllowCallerAccess— Concede al rol de IAM kms:DescribeKey permiso para validar la clave en el momento de crear la evaluación por lotes. 111122223333Sustitúyala por el identificador de tu cuenta y MyBatchEvaluationRole por el rol o usuario de IAM que inicia las evaluaciones por lotes.
AllowCallerCryptoOps— Otorga la función kms:GenerateDataKey y kms:Decrypt los permisos de IAM, según el aws:bedrock-agentcore:batchEvaluationArn contexto de cifrado. Sustituya 111122223333MyBatchEvaluationRole, y por us-east-1 sus valores. Para permitir el acceso a todas las evaluaciones por lotes de su cuenta, utilice un comodín conStringLike:arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*.
AllowServicePrincipalAccess— Otorga al director del AgentCore servicio kms:GenerateDataKey y kms:Decrypt los permisos para cifrar y descifrar los datos de evaluación por lotes en S3. Se divide en función de la cuenta de origen y el ARN de origen (aws:SourceArn) para evitar ataques confusos de los subalternos. Sustituye us-east-1 y 111122223333 por tu región y tu ID de cuenta.

Disminuir el acceso a la clave de KMS administrada por el cliente

Puede usar el contexto de cifrado para restringir el acceso a la clave administrada por el cliente. AgentCore Las evaluaciones incluyen el siguiente contexto de cifrado en todas las operaciones de KMS:


{
  "aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}

Puede usar este contexto de cifrado en las condiciones clave de la política para restringir las operaciones de KMS a evaluaciones por lotes específicas, como se muestra en la AllowCallerCryptoOps declaración del ejemplo de política de claves anterior. Tenga en cuenta que se AllowServicePrincipalAccess usa aws:SourceArn para determinar el alcance en lugar de para el contexto de cifrado.

Iniciar una evaluación por lotes con una clave de KMS administrada por el cliente

Especifique el kmsKeyArn parámetro al llamarStartBatchEvaluation:

ejemplo

AgentCore CLI

Con la AgentCore CLI, utilice la --kms-key opción para especificar un ARN de clave de KMS único para cifrar los resultados de la evaluación por lotes. La AgentCore CLI usa la --kms-key marca, que difiere de la marca de la AWS CLI y del --kms-key-arn parámetro kmsKeyArn boto3.


agentcore run batch-evaluation \
  -r MyAgent \
  -e Builtin.Correctness \
  --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

AWS CLI


aws bedrock-agentcore start-batch-evaluation \
  --batch-evaluation-name "MyEncryptedBatchEval" \
  --kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
  --evaluators '[{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]' \
  --data-source-config '{
    "cloudwatchLogs": {
      "logGroupNames": ["/aws/bedrock-agentcore/sessions/my-agent"],
      "serviceNames": ["my-agent.DEFAULT"],
      "filterConfig": {
        "timeRange": {
          "startTime": "2025-01-01T00:00:00Z",
          "endTime": "2025-01-02T00:00:00Z"
        }
      }
    }
  }'

Python (Boto3)


import boto3

client = boto3.client('bedrock-agentcore')

response = client.start_batch_evaluation(
    batchEvaluationName='MyEncryptedBatchEval',
    kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    evaluators=[{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}],
    dataSourceConfig={
        'cloudwatchLogs': {
            'logGroupNames': ['/aws/bedrock-agentcore/sessions/my-agent'],
            'serviceNames': ['my-agent.DEFAULT'],
            'filterConfig': {
                'timeRange': {
                    'startTime': '2025-01-01T00:00:00Z',
                    'endTime': '2025-01-02T00:00:00Z'
                }
            }
        }
    }
)

print(f"Batch Evaluation ID: {response['batchEvaluationId']}")

Supervisión del uso de KMS para las evaluaciones por lotes

Aparecen los siguientes nombres de CloudTrail eventos para las operaciones de KMS de evaluación por lotes:

GenerateDataKey— Al escribir el resultado cifrado de la evaluación por lotes en S3 (configuración de la fuente de datos, metadatos de la sesión, resultados de la evaluación). El encryptionContext campo contieneaws:bedrock-agentcore:batchEvaluationArn.
Decrypt— Al leer los resultados cifrados de la evaluación por lotes de S3.
DescribeKey— Al validar la clave en el momento de crear la evaluación por lotes.

Para obtener más información sobre la supervisión del uso de KMS, consulte Registrar las llamadas a la API de AWS KMS AWS CloudTrail en la Guía para desarrolladores del servicio de administración de AWS claves.

Comportamiento cuando una clave deja de estar disponible

Si inhabilitas o eliminas la clave de KMS administrada por el cliente utilizada en una evaluación por lotes:

StartBatchEvaluation— No se puede validar conValidationException.
GetBatchEvaluation— Devuelve metadatos (nombre, estado, marcas de tiempo), pero el servicio no puede leer los resultados de la evaluación almacenados en objetos S3 cifrados.
ListBatchEvaluations— Se realiza correctamente porque el listado solo devuelve metadatos y no requiere operaciones de KMS.
StopBatchEvaluation— Se ejecuta correctamente porque para detenerlo no es necesario descifrar los datos.
DeleteBatchEvaluation— Se realiza correctamente porque la eliminación del objeto de S3 no requiere el descifrado de KMS.

Para restablecer el acceso, vuelva a habilitar la clave o actualice la política de claves para conceder los permisos necesarios.

Las operaciones del ciclo de vida de la evaluación por lotes descritas anteriormente se asignan a los comandos de la AgentCore CLI. Los archive comandos stop y se dirigen al trabajo a través de la -i, --id <id> opción. El view batch-evaluation comando toma el ID como argumento posicional:

StartBatchEvaluation— agentcore run batch-evaluation --kms-key <arn> (usa -r/--runtime y-e/--evaluator)
GetBatchEvaluation — agentcore view batch-evaluation <id>
ListBatchEvaluations— agentcore view batch-evaluation o agentcore batch-evaluations history
StopBatchEvaluation — agentcore stop batch-evaluation -i <id>
DeleteBatchEvaluation — agentcore archive batch-evaluation -i <id>

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Comprender los resultados y los resultados

Evaluación de conjuntos de datos (vista previa)