AgentCore Harness

Genera un proyecto de Amazon Bedrock AgentCore Harness. Un Harness es un bucle de agente administrado impulsado por Strands Agents: posee valores predeterminados de implementación para el modelo, el prompt del sistema, las herramientas, la memoria, las habilidades, los entornos, el truncamiento, la autorización y los límites de ejecución, mientras que el servicio acepta anulaciones por invocación para los campos admitidos. Reutilizar el mismo Runtime Session ID continúa la misma sesión de Harness.

Uso

Generar un AgentCore Harness

CLI

pnpm

pnpm nx g @aws/nx-plugin:agentcore-harness

yarn

yarn nx g @aws/nx-plugin:agentcore-harness

npm

npx nx g @aws/nx-plugin:agentcore-harness

bun

bunx nx g @aws/nx-plugin:agentcore-harness

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:agentcore-harness --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-harness --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-harness --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-harness --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - agentcore-harness
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	El nombre de tu proyecto AgentCore Harness. Debe contener al menos un carácter que no sea espacio en blanco y que pueda normalizarse en un nombre de proyecto en formato kebab-case (ej. my-harness).
directory	string	-	Directorio padre donde se coloca el proyecto harness. Por defecto es packages. Debe ser una ruta relativa que no contenga segmentos de directorio padre (..).
subDirectory	string	-	El subdirectorio donde se coloca el proyecto. Por defecto es el nombre del harness en formato kebab-case. Debe ser una ruta relativa que no contenga segmentos de directorio padre (..).
infra	agentcore | none	agentcore	El tipo de infraestructura a generar para alojar tu harness. Por defecto es agentcore. Selecciona none para no generar alojamiento.
iac	inherit | cdk | terraform	inherit	El proveedor IaC preferido para la infraestructura del harness generado. Por defecto es inherit, que utiliza el proveedor configurado para tu workspace.
preferInstallDependencies	boolean	-	Si se prefiere instalar las dependencias después de que se ejecute el generador. Por defecto es true. Establece en false para diferir la instalación al agrupar múltiples generadores (la instalación aún se ejecuta si es necesaria para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del generador

El generador crea un proyecto independiente en packages/<name>/. Debido a que AWS ejecuta el bucle de agente por ti, el proyecto solo contiene el prompt que lo configura y un script para comunicarse con él:

• Directoriopackages/<name>/

  • src/PROMPT.md El prompt del sistema del Harness
  • scripts/chat.ts Cliente de chat multi-turno para el Harness implementado
  • project.json Agrega el objetivo chat
  • README.md Instrucciones de chat y personalización

Infraestructura

La infraestructura se genera cuando infra es agentcore (el valor predeterminado). Con infra: none no se genera infraestructura — establece HARNESS_ARN para invocar un Harness administrado en otro lugar, y vuelve a ejecutar el generador con infra: agentcore más tarde para agregar infraestructura; los archivos de proyecto existentes (incluidas tus ediciones) se conservan.

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

CDK

• Directoriopackages/common/constructs/src/app/harnesses/<name>/

  • <name>.ts Constructo CDK que contiene el Harness y el rol de ejecución

Terraform

• Directoriopackages/common/terraform/src/app/harnesses/<name>/

  • <name>.tf Módulo Terraform que contiene el Harness y el rol de ejecución

La infraestructura generada administra el Harness a través del recurso nativo (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) con tus valores predeterminados generados, crea un rol de ejecución IAM con los permisos básicos descritos a continuación, y utiliza autorización entrante IAM (no se configura ningún autorizador JWT personalizado de forma predeterminada).

El ARN del Harness se registra en agentcore.harnesses.<ClassName> en Runtime Configuration, conservando cualquier entrada existente.

Implementar tu AgentCore Harness

El generador crea infraestructura como código CDK o Terraform según tu proveedor iac seleccionado. Puedes usar esto para implementar tu Harness a través de tu flujo de trabajo de infraestructura habitual.

CDK

El constructo CDK para implementar tu Harness se encuentra en la carpeta common/constructs. Instáncialo desde una aplicación CDK:

packages/infra/src/stacks/application-stack.ts

import { MyHarness } from '@my-scope/common-constructs';
import { Stack, type StackProps } from 'aws-cdk-lib';
import type { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyHarness(this, 'MyHarness');
  }
}

La interfaz de props del constructo (MyHarnessProps) extiende Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, por lo que cualquier propiedad nativa de Harness puede ser suministrada y tiene precedencia sobre los valores predeterminados generados:

const harness = new MyHarness(this, 'MyHarness', {
  maxIterations: 20,
  timeoutSeconds: 600,
});

El constructo también acepta:

• allowedTools — las herramientas que el Harness puede usar. El Harness se implementa sin ninguna a menos que las proporciones, consulta Configurar herramientas.
• executionRole — un rol IAM existente para usar en lugar del rol generado. Un rol proporcionado se usa tal cual: los permisos básicos no se le agregan, y su ARN siempre alimenta el Harness (la cadena executionRoleArn sin procesar no se puede anular).
• modelResourceArns — los ARN del modelo de Bedrock y del perfil de inferencia que el rol de ejecución generado puede invocar, reemplazando la lista predeterminada.
• vpc, vpcSubnets y securityGroups — ejecuta el Harness en una VPC para que pueda alcanzar recursos privados, consulta Ejecutar en una VPC.

Sus miembros públicos son harness (el CfnHarness), executionRole, grantPrincipal, el getter harnessArn, connections (en una VPC), addToRolePolicy(statement) para extensiones del rol de ejecución, y grantInvokeAccess(grantee) para autorizar llamadores.

Implementa el stack con tu proyecto de infraestructura como de costumbre — consulta la guía de infraestructura CDK.

Terraform

El módulo Terraform para implementar tu Harness está en la carpeta common/terraform. Referéncialo desde una configuración de Terraform:

packages/infra/src/main.tf

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
}

El módulo expone tres variables:

• model_id — el modelo de Bedrock o perfil de inferencia que el Harness usa de forma predeterminada.
• model_resource_arns — los ARN del modelo de Bedrock y del perfil de inferencia que el rol de ejecución puede invocar, reemplazando la lista predeterminada.
• additional_execution_role_policy_statements — una lista de objetos de declaración IAM (Effect, Action, Resource, Sid y Condition opcionales) agregados a la política del rol de ejecución.

Todo lo demás se configura en el recurso aws_bedrockagentcore_harness generado en el módulo mismo.

El módulo genera harness_id, harness_arn, y execution_role_arn.

Implementa con el flujo de trabajo plan/apply de tu proyecto Terraform como de costumbre — consulta la guía de proyecto Terraform.

Visibilidad del prompt del sistema

Tu infraestructura lee packages/<name>/src/PROMPT.md cuando sintetizas (CDK) o planificas (Terraform), por lo que el prompt es configuración de implementación en lugar de almacenamiento secreto: su contenido aparece en la plantilla de CloudFormation sintetizada o en el estado de Terraform.

Otorgar acceso para invocar el harness

Puedes otorgar a un llamador permisos para invocar el harness de la siguiente manera:

CDK

const harness = new MyHarness(this, 'MyHarness');

harness.grantInvokeAccess(caller);

Terraform

# Attach to the calling principal's role
resource "aws_iam_role_policy" "invoke_my_harness" {
  name = "InvokeMyHarness"
  role = aws_iam_role.caller.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeHarness",
        "bedrock-agentcore:InvokeAgentRuntime",
      ]
      Resource = [module.my_harness.harness_arn]
    }]
  })
}

Un llamador necesita tanto bedrock-agentcore:InvokeHarness como bedrock-agentcore:InvokeAgentRuntime en el ARN del Harness, que es exactamente lo que grantInvokeAccess otorga.

Chatear con tu Harness

El objetivo chat generado ejecuta scripts/chat.ts, llevándote a un chat de terminal interactivo con tu Harness implementado:

pnpm

pnpm nx run <project>:chat

yarn

yarn nx run <project>:chat

npm

npx nx run <project>:chat

bun

bunx nx run <project>:chat

Cada turno de una ejecución comparte una sesión, por lo que el Harness mantiene el contexto de la conversación hasta que salgas. Las credenciales provienen de la cadena de proveedores de credenciales estándar del SDK de AWS, y la región de AWS se deriva del ARN del Harness.

El ARN del Harness se resuelve en este orden:

1. HARNESS_ARN (no vacío): se usa directamente, sin leer Runtime Configuration:

   pnpm

   HARNESS_ARN=<harness-arn> pnpm nx run <project>:chat

   yarn

   HARNESS_ARN=<harness-arn> yarn nx run <project>:chat

   npm

   HARNESS_ARN=<harness-arn> npx nx run <project>:chat

   bun

   HARNESS_ARN=<harness-arn> bunx nx run <project>:chat

2. RUNTIME_CONFIG_APP_ID: resuelve el ARN de la entrada agentcore.harnesses.<ClassName> publicada por la infraestructura implementada:

   pnpm

   RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx run <project>:chat

   yarn

   RUNTIME_CONFIG_APP_ID=<application-id> yarn nx run <project>:chat

   npm

   RUNTIME_CONFIG_APP_ID=<application-id> npx nx run <project>:chat

   bun

   RUNTIME_CONFIG_APP_ID=<application-id> bunx nx run <project>:chat

Sin ninguno establecido, el script falla con un error nombrando ambas opciones.

Personalizar tu Harness

src/PROMPT.md es el prompt del sistema del Harness: edítalo y vuelve a implementar para cambiar cómo se comporta el Harness. Todo lo demás se configura donde instancias la infraestructura, o editando el constructo o módulo generado directamente. Volver a ejecutar el generador nunca sobrescribe archivos existentes (solo agrega archivos faltantes y fusiona metadatos del proyecto), por lo que tus ediciones al prompt y a la infraestructura generada se conservan.

CDK

Cada propiedad nativa de Harness del módulo aws-cdk-lib/aws-bedrockagentcore fijado está disponible a través de las props del constructo — proveedores de modelos alternativos, definiciones de herramientas, memoria, habilidades, configuración de entorno, truncamiento, autorización JWT personalizada y límites de ejecución — y las props explícitas tienen precedencia sobre los valores predeterminados generados. Alternativamente, edita el constructo generado en packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Terraform

El módulo generado mantiene el recurso nativo aws_bedrockagentcore_harness directamente editable, por lo que los campos nativos del proveedor — proveedores de modelos alternativos (gemini_model_config, openai_model_config), bloques tool, memory, bloques skill, entornos (environment, environment_variables, environment_artifact), truncation, y authorizer_configuration con un custom_jwt_authorizer — se configuran editando packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

Omitir la configuración del autorizador (el valor predeterminado) significa autorización entrante IAM; configura un autorizador JWT personalizado a través del campo nativo para cambiar eso.

Configurar herramientas

El Harness se implementa sin herramientas, por lo que comienza con la menor capacidad. Opta por las herramientas que puede usar:

CDK

new MyHarness(this, 'Harness', { allowedTools: ['@builtin'] });

Terraform

packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  allowed_tools = ["@builtin"]
}

Agrega una variable allowed_tools al módulo si prefieres establecerla como un argumento del módulo donde referencias el módulo.

Reduce @builtin a patrones específicos como @builtin/file_operations para restringir lo que el bucle de agente puede hacer. Consulta Herramientas de Harness para las herramientas integradas que puedes agregar.

Ejecutar en una VPC

CDK

Proporciona una vpc para ejecutar el Harness dentro de ella, de modo que pueda alcanzar recursos privados como una base de datos. El constructo implementa IConnectable, por lo que esos recursos le otorgan acceso de la misma manera que lo harían con cualquier otro:

const harness = new MyHarness(this, 'MyHarness', { vpc });

database.connections.allowDefaultPortFrom(harness, 'Harness to database');

El Harness se coloca en las subredes privadas de la VPC con salida, en un grupo de seguridad creado para él. Anula cualquiera de los dos con vpcSubnets y securityGroups. Ambos requieren vpc, y connections solo está disponible cuando el Harness se ejecuta en una VPC.

Terraform

Agrega un bloque network_configuration al environment.agent_core_runtime_environment del recurso aws_bedrockagentcore_harness generado, luego referencia el grupo de seguridad en el que lo colocas desde las reglas de tus otros recursos:

packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf

resource "aws_security_group" "harness" {
  vpc_id = var.vpc_id
}

resource "aws_bedrockagentcore_harness" "this" {
  # ...
  environment {
    agent_core_runtime_environment {
      network_configuration {
        network_mode = "VPC"
        network_mode_config {
          security_groups = [aws_security_group.harness.id]
          subnets         = var.subnet_ids
        }
      }
    }
  }
}

Anulaciones por invocación

Los valores configurados en la infraestructura son valores predeterminados de implementación. El servicio también acepta anulaciones por invocación para campos de Harness admitidos (como modelos, herramientas y habilidades) en la solicitud InvokeHarness; los valores predeterminados de implementación se aplican donde un campo no se anula.

Validar anulaciones de invocación

Las anulaciones por invocación son entradas confiables en el límite del servicio: cualquier llamador autorizado puede anular campos admitidos. Si usuarios no confiables pueden alcanzar una aplicación que reenvía anulaciones a InvokeHarness, valídalas y autorizalas en la capa de aplicación (por ejemplo, lista de permitidos de modelos y herramientas), mantén el rol de ejecución limitado a los recursos requeridos, y no otorgues bedrock-agentcore:InvokeAgentRuntimeCommand a menos que lo necesites específicamente.