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

Ejecute este generador@aws/nx-plugin: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

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

Construya su comando6

nameRequerido

directory

subDirectory

infra

agentcorenone

iac

inheritcdkterraform

preferInstallDependencies

false

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

Opciones

Opciones del generador6 opciones

nameRequeridostring

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).

directorystring

Directorio padre donde se coloca el proyecto harness. Por defecto es packages. Debe ser una ruta relativa que no contenga segmentos de directorio padre (..).

subDirectorystring

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 (..).

infraenumPredeterminado: agentcore

El tipo de infraestructura a generar para alojar tu harness. Por defecto es agentcore. Selecciona none para no generar alojamiento.

agentcorenone

iacenumPredeterminado: inherit

El proveedor IaC preferido para la infraestructura del harness generado. Por defecto es inherit, que utiliza el proveedor configurado para tu workspace.

inheritcdkterraform

preferInstallDependenciesboolean

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
  • tsconfig.json Configuración de TypeScript utilizada por el objetivo typecheck
  • project.json Agrega los objetivos chat, build, lint, format y typecheck
  • 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. Por defecto ninguna, 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 las siguientes variables:

• model_id — el modelo de Bedrock o perfil de inferencia que el Harness usa de forma predeterminada.
• allowed_tools — las herramientas que el Harness puede usar. Por defecto ninguna, consulta Configurar herramientas.
• memory — la configuración de memoria del Harness, consulta Configurar memoria.
• environment_variables, max_iterations, timeout_seconds — los campos nativos correspondientes del Harness.
• execution_role_arn — un rol IAM existente para usar en lugar del rol generado. Un rol proporcionado se usa tal cual: ni el rol ni su política básica se crean, por lo que model_resource_arns y additional_execution_role_policy_statements no se pueden combinar con él.
• model_resource_arns — los ARN del modelo de Bedrock y del perfil de inferencia que el rol de ejecución generado 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 generado.
• enable_vpc, vpc_id, subnet_ids — ejecuta el Harness en una VPC para que pueda alcanzar recursos privados, consulta Ejecutar en una VPC.
• tags — etiquetas aplicadas a los recursos que el módulo crea.

Otros campos nativos del proveedor se configuran editando el recurso aws_bedrockagentcore_harness generado en el módulo mismo, consulta Personalizar tu Harness.

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

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

Las variables del módulo cubren los campos que la mayoría de las implementaciones configuran — model_id, allowed_tools, memory, environment_variables, max_iterations, timeout_seconds — más el rol de ejecución y la ubicación de VPC. Terraform no tiene un equivalente de la propagación de props del constructo CDK, por lo que los campos nativos del proveedor restantes se configuran editando el recurso aws_bedrockagentcore_harness en packages/common/terraform/src/app/harnesses/<name>/<name>.tf: proveedores de modelos alternativos (gemini_model_config, openai_model_config), bloques tool, bloques skill, environment_artifact, configuración de sistema de archivos y ciclo de vida bajo environment, truncation, y authorizer_configuration con un custom_jwt_authorizer.

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/infra/src/main.tf

module "my_harness" {
  source        = "../../common/terraform/src/app/harnesses/my-harness"
  allowed_tools = ["@builtin"]
}

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.

Configurar memoria

El servicio aprovisiona memoria administrada para el Harness de forma predeterminada, y al rol de ejecución generado se le otorga acceso a ella — limitado al ARN de memoria que el servicio asigna, y solo otorgado mientras el Harness usa la memoria administrada que la infraestructura creó. Configura la memoria explícitamente para ajustar esa memoria administrada, apuntar el Harness a un recurso de memoria que posees, o desactivar la memoria:

CDK

new MyHarness(this, 'MyHarness', {
  memory: { managedMemoryConfiguration: { strategies: ['SUMMARIZATION'] } },
});

Proporcionar memory en absoluto reemplaza la memoria administrada predeterminada, por lo que el constructo deja el permiso de memoria fuera del rol de ejecución: agrega lo que la configuración necesite con addToRolePolicy.

Terraform

module "my_harness" {
  source = "../../common/terraform/src/app/harnesses/my-harness"
  memory = {
    managed_memory_configuration = {
      strategies = ["SUMMARIZATION"]
    }
  }
}

Establece exactamente uno de managed_memory_configuration (ajustar la memoria administrada del servicio), agentcore_memory_configuration (usar un recurso de memoria que posees, por ARN) o disabled (sin memoria). Elegir agentcore_memory_configuration o disabled elimina el permiso de memoria administrada del rol de ejecución; para tu propio recurso de memoria, otorga acceso a través de additional_execution_role_policy_statements.

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

Establece enable_vpc junto con vpc_id y subnet_ids para ejecutar el Harness dentro de una VPC, de modo que pueda alcanzar recursos privados como una base de datos:

module "my_harness" {
  source     = "../../common/terraform/src/app/harnesses/my-harness"
  enable_vpc = true
  vpc_id     = var.vpc_id
  subnet_ids = var.private_subnet_ids
}

El módulo crea un grupo de seguridad para el Harness, permitiendo solo HTTPS saliente. Su salida security_group_id es lo que los recursos que el Harness debe alcanzar referencian en sus propias reglas de entrada:

resource "aws_vpc_security_group_ingress_rule" "harness_to_database" {
  security_group_id            = aws_security_group.database.id
  referenced_security_group_id = module.my_harness.security_group_id
  from_port                    = 5432
  to_port                      = 5432
  ip_protocol                  = "tcp"
  description                  = "Harness to database"
}

security_group_id es nulo a menos que enable_vpc sea verdadero, y vpc_id y subnet_ids son ambos requeridos cuando lo es.

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.