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

Cifrado de evaluación por lotes

Al especificar 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 el resultado de la evaluación por lotes en S3, S3 llama al 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 preliminar (sesiones de acceso directo). Esto detecta los problemas de permisos de forma inmediata, en lugar de fallar de forma asíncrona durante el flujo de trabajo de evaluación por lotes.

El servicio también comprueba que puede funcionar kms:GenerateDataKey con sus propias credenciales para garantizar que la política de claves conceda al director del servicio los permisos necesarios para escribir los resultados cifrados.

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

Configurar los permisos para usar una clave 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 director 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— Otorga al rol de IAM kms:DescribeKey permiso para validar la clave en el momento de crear la evaluación del lote. 111122223333Sustitúyalo por tu ID de 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 111122223333 MyBatchEvaluationRole y por sus us-east-1 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 permisos para cifrar y descifrar los datos de evaluación de los lotes en S3. Seleccionado por cuenta de origen y ARN de origen aws:SourceArn () para evitar confusos ataques de diputados. Sustituya us-east-1 y 111122223333 por su región e ID de cuenta.

Limitar el acceso a la clave KMS administrada por el cliente

Puede usar el contexto de cifrado para limitar 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 de la política clave 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 utiliza aws:SourceArn para el ámbito más que para el contexto de cifrado.

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

Especifique el kmsKeyArn parámetro al llamar aStartBatchEvaluation:

ejemplo

AgentCore CLI

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


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 del KMS para las evaluaciones por lotes

Los siguientes nombres de CloudTrail eventos aparecen 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 el resultado cifrado de la evaluación de lotes de S3.
DescribeKey— Al validar la clave en el momento de crear la evaluación del lote.

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 deshabilita o elimina la clave KMS administrada por el cliente utilizada en una evaluación por lotes:

StartBatchEvaluation— Falla en la validación 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— Funciona correctamente porque la lista solo devuelve metadatos y no requiere operaciones de KMS.
StopBatchEvaluation— Se ejecuta correctamente porque la detención no requiere descifrar los datos.
DeleteBatchEvaluation— Se realiza correctamente porque la eliminación de objetos 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 mediante 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 del conjunto de datos (vista previa)