# Cifrado de evaluación por lotes
<a name="batch-evaluations-encryption"></a>

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.

`kmsKeyArn`Se especifica en el momento de la creación mediante`StartBatchEvaluation`.

## Funcionamiento
<a name="batch-evaluations-encryption-how-it-works"></a>

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
<a name="batch-evaluations-encryption-key-policy"></a>

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 mediante`DescribeKey`.
+  **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. {{111122223333}}Sustitú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 con`StringLike`:`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
<a name="batch-evaluations-encryption-scoping"></a>

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
<a name="batch-evaluations-encryption-creating"></a>

Especifique el `kmsKeyArn` parámetro al llamar a`StartBatchEvaluation`:

**Example**  
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 boto3`kmsKeyArn`.  

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

```
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
<a name="batch-evaluations-encryption-monitoring"></a>

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 contiene`aws: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](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html) en la *Guía para desarrolladores del Servicio de administración de AWS claves*.

## Comportamiento cuando una clave deja de estar disponible
<a name="batch-evaluations-encryption-unavailable"></a>

Si deshabilita o elimina la clave KMS administrada por el cliente utilizada en una evaluación por lotes:
+  **StartBatchEvaluation**— Falla en la validación con`ValidationException`.
+  **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>`