AgentCore Harness

Générez un projet Amazon Bedrock AgentCore Harness. Un Harness est une boucle d’agent gérée alimentée par Strands Agents : il possède les valeurs par défaut de déploiement pour le modèle, l’invite système, les outils, la mémoire, les compétences, les environnements, la troncature, l’autorisation et les limites d’exécution, tandis que le service accepte des remplacements par invocation pour les champs pris en charge. La réutilisation du même Runtime Session ID continue la même session Harness.

Utilisation

Générer un AgentCore Harness

Exécuter ce générateur@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. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - agentcore-harness
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Composez votre commande6

nameRequis

directory

subDirectory

infra

agentcorenone

iac

inheritcdkterraform

preferInstallDependencies

false

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Options

Options du générateur6 options

nameRequisstring

Le nom de votre projet AgentCore Harness. Doit contenir au moins un caractère non-espace qui peut être normalisé en nom de projet kebab-case (ex. my-harness).

directorystring

Répertoire parent où le projet harness est placé. Par défaut packages. Doit être un chemin relatif qui ne contient pas de segments de répertoire parent (..).

subDirectorystring

Le sous-répertoire dans lequel le projet est placé. Par défaut, le nom harness en kebab-case. Doit être un chemin relatif qui ne contient pas de segments de répertoire parent (..).

infraenumPar défaut: agentcore

Le type d'infrastructure à générer pour héberger votre harness. Par défaut agentcore. Sélectionnez none pour aucun hébergement.

agentcorenone

iacenumPar défaut: inherit

Le fournisseur IaC préféré pour l'infrastructure harness générée. Par défaut inherit, qui utilise le fournisseur configuré pour votre workspace.

inheritcdkterraform

preferInstallDependenciesboolean

Indique s'il faut préférer installer les dépendances après l'exécution du générateur. Par défaut true. Définir à false pour différer l'installation lors du traitement par lots de plusieurs générateurs (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une fois à la fin.

Sortie du générateur

Le générateur crée un projet autonome dans packages/<name>/. Comme AWS exécute la boucle d’agent pour vous, le projet ne contient que l’invite qui le façonne et un script pour communiquer avec lui :

• Répertoirepackages/<name>/

  • src/PROMPT.md The Harness system prompt
  • scripts/chat.ts Multi-turn chat client for the deployed Harness
  • tsconfig.json TypeScript configuration used by the typecheck target
  • project.json Adds the chat, build, lint, format and typecheck targets
  • README.md Chat and customization instructions

Infrastructure

L’infrastructure est générée lorsque infra est agentcore (la valeur par défaut). Avec infra: none, aucune infrastructure n’est générée — définissez HARNESS_ARN pour invoquer un Harness géré ailleurs, et réexécutez le générateur avec infra: agentcore plus tard pour ajouter l’infrastructure ; les fichiers de projet existants (y compris vos modifications) sont préservés.

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app

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

Projet généré

Ce projet est généré en utilisant le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Répertoirecore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projet généré

Ce projet est généré en utilisant le générateur terraform#project et configure donc les mêmes cibles de build.

CDK

• Répertoirepackages/common/constructs/src/app/harnesses/<name>/

  • <name>.ts CDK construct containing the Harness and execution role

Terraform

• Répertoirepackages/common/terraform/src/app/harnesses/<name>/

  • <name>.tf Terraform module containing the Harness and execution role

L’infrastructure générée gère le Harness via la ressource native (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) avec vos valeurs par défaut générées, crée un rôle d’exécution IAM avec les permissions de base décrites ci-dessous, et utilise l’autorisation entrante IAM (aucun autorisateur JWT personnalisé n’est configuré par défaut).

L’ARN du Harness est enregistré dans agentcore.harnesses.<ClassName> dans la Configuration d’exécution, en préservant toutes les entrées existantes.

Déployer votre AgentCore Harness

Le générateur crée une infrastructure en tant que code CDK ou Terraform en fonction de votre fournisseur iac sélectionné. Vous pouvez l’utiliser pour déployer votre Harness via votre flux de travail d’infrastructure habituel.

CDK

Le construct CDK pour déployer votre Harness se trouve dans le dossier common/constructs. Instanciez-le depuis une application 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');
  }
}

L’interface props du construct (MyHarnessProps) étend Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, donc toute propriété Harness native peut être fournie et a la priorité sur les valeurs par défaut générées :

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

Le construct accepte également :

• allowedTools — les outils que le Harness peut utiliser. Par défaut aucun, voir Configuration des outils.
• executionRole — un rôle IAM existant à utiliser au lieu du rôle généré. Un rôle fourni est utilisé tel quel : les permissions de base ne lui sont pas ajoutées, et son ARN alimente toujours le Harness (la chaîne brute executionRoleArn ne peut pas être remplacée).
• modelResourceArns — les ARN de modèle Bedrock et de profil d’inférence que le rôle d’exécution généré peut invoquer, remplaçant la liste par défaut.
• vpc, vpcSubnets et securityGroups — exécutez le Harness dans un VPC afin qu’il puisse atteindre des ressources privées, voir Exécution dans un VPC.

Ses membres publics sont harness (le CfnHarness), executionRole, grantPrincipal, le getter harnessArn, connections (dans un VPC), addToRolePolicy(statement) pour les extensions de rôle d’exécution, et grantInvokeAccess(grantee) pour autoriser les appelants.

Déployez la pile avec votre projet d’infrastructure comme d’habitude — voir le guide d’infrastructure CDK.

Terraform

Le module Terraform pour déployer votre Harness se trouve dans le dossier common/terraform. Référencez-le depuis une configuration Terraform :

packages/infra/src/main.tf

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

Le module expose les variables suivantes :

• model_id — le modèle Bedrock ou le profil d’inférence que le Harness utilise par défaut.
• allowed_tools — les outils que le Harness peut utiliser. Par défaut aucun, voir Configuration des outils.
• memory — la configuration de mémoire du Harness, voir Configuration de la mémoire.
• environment_variables, max_iterations, timeout_seconds — les champs Harness natifs correspondants.
• execution_role_arn — un rôle IAM existant à utiliser au lieu du rôle généré. Un rôle fourni est utilisé tel quel : ni le rôle ni sa politique de base ne sont créés, donc model_resource_arns et additional_execution_role_policy_statements ne peuvent pas être combinés avec lui.
• model_resource_arns — les ARN de modèle Bedrock et de profil d’inférence que le rôle d’exécution généré peut invoquer, remplaçant la liste par défaut.
• additional_execution_role_policy_statements — une liste d’objets d’instruction IAM (Effect, Action, Resource, Sid et Condition optionnels) ajoutés à la politique du rôle d’exécution généré.
• enable_vpc, vpc_id, subnet_ids — exécutez le Harness dans un VPC afin qu’il puisse atteindre des ressources privées, voir Exécution dans un VPC.
• tags — balises appliquées aux ressources que le module crée.

Les autres champs natifs du fournisseur sont configurés en modifiant la ressource aws_bedrockagentcore_harness générée dans le module lui-même, voir Personnaliser votre Harness.

Le module produit harness_id, harness_arn, execution_role_arn et security_group_id.

Déployez avec le flux de travail plan/apply de votre projet Terraform comme d’habitude — voir le guide de projet Terraform.

Visibilité de l’invite système

Votre infrastructure lit packages/<name>/src/PROMPT.md lorsque vous synthétisez (CDK) ou planifiez (Terraform), donc l’invite est une configuration de déploiement plutôt qu’un stockage secret : son contenu apparaît dans le modèle CloudFormation synthétisé ou dans l’état Terraform.

Accorder l’accès pour invoquer le harness

Vous pouvez accorder à un appelant les permissions d’invoquer le harness comme suit :

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 appelant a besoin à la fois de bedrock-agentcore:InvokeHarness et bedrock-agentcore:InvokeAgentRuntime sur l’ARN du Harness, ce qui est exactement ce que grantInvokeAccess accorde.

Discuter avec votre Harness

La cible chat générée exécute scripts/chat.ts, vous plaçant dans un chat terminal interactif avec votre Harness déployé :

pnpm

pnpm nx run <project>:chat

yarn

yarn nx run <project>:chat

npm

npx nx run <project>:chat

bun

bunx nx run <project>:chat

Chaque tour d’une exécution partage une session, donc le Harness conserve le contexte de conversation jusqu’à ce que vous quittiez. Les identifiants proviennent de la chaîne de fournisseur d’identifiants AWS SDK standard, et la région AWS est dérivée de l’ARN du Harness.

L’ARN du Harness est résolu dans cet ordre :

1. HARNESS_ARN (non vide) : utilisé directement, sans lire la Configuration d’exécution :

   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 : résout l’ARN à partir de l’entrée agentcore.harnesses.<ClassName> publiée par l’infrastructure déployée :

   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

Si aucun n’est défini, le script échoue avec une erreur nommant les deux options.

Personnaliser votre Harness

src/PROMPT.md est l’invite système du Harness : modifiez-la et redéployez pour changer le comportement du Harness. Tout le reste est configuré là où vous instanciez l’infrastructure, ou en modifiant directement le construct ou le module généré. La réexécution du générateur n’écrase jamais les fichiers existants (il ajoute uniquement les fichiers manquants et fusionne les métadonnées du projet), donc vos modifications de l’invite et de l’infrastructure générée sont préservées.

CDK

Chaque propriété Harness native du module aws-cdk-lib/aws-bedrockagentcore épinglé est disponible via les props du construct — fournisseurs de modèles alternatifs, définitions d’outils, mémoire, compétences, configuration d’environnement, troncature, autorisation JWT personnalisée et limites d’exécution — et les props explicites ont la priorité sur les valeurs par défaut générées. Alternativement, modifiez le construct généré dans packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Terraform

Les variables du module couvrent les champs que la plupart des déploiements configurent — model_id, allowed_tools, memory, environment_variables, max_iterations, timeout_seconds — plus le rôle d’exécution et le placement VPC. Terraform n’a pas d’équivalent à la propagation de props du construct CDK, donc les champs natifs du fournisseur restants sont configurés en modifiant la ressource aws_bedrockagentcore_harness dans packages/common/terraform/src/app/harnesses/<name>/<name>.tf : fournisseurs de modèles alternatifs (gemini_model_config, openai_model_config), blocs tool, blocs skill, environment_artifact, configuration du système de fichiers et du cycle de vie sous environment, truncation, et authorizer_configuration avec un custom_jwt_authorizer.

Omettre la configuration de l’autorisateur (la valeur par défaut) signifie l’autorisation entrante IAM ; configurez un autorisateur JWT personnalisé via le champ natif pour changer cela.

Configuration des outils

Le Harness se déploie sans outils, il commence donc avec le moins de capacités. Optez pour les outils qu’il peut utiliser :

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"]
}

Restreignez @builtin à des modèles spécifiques tels que @builtin/file_operations pour limiter ce que la boucle d’agent peut faire. Voir Outils Harness pour les outils intégrés que vous pouvez ajouter.

Configuration de la mémoire

Le service provisionne une mémoire gérée pour le Harness par défaut, et le rôle d’exécution généré se voit accorder l’accès à celle-ci — limité à l’ARN de mémoire que le service attribue, et accordé uniquement tant que le Harness utilise la mémoire gérée que l’infrastructure a créée. Configurez la mémoire explicitement pour ajuster cette mémoire gérée, pointer le Harness vers une ressource de mémoire que vous possédez, ou désactiver la mémoire :

CDK

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

Fournir memory remplace la mémoire gérée par défaut, donc le construct n’ajoute pas l’autorisation de mémoire au rôle d’exécution : ajoutez ce dont la configuration a besoin avec addToRolePolicy.

Terraform

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

Définissez exactement l’un de managed_memory_configuration (ajuster la mémoire gérée du service), agentcore_memory_configuration (utiliser une ressource de mémoire que vous possédez, par ARN) ou disabled (pas de mémoire). Choisir agentcore_memory_configuration ou disabled supprime l’autorisation de mémoire gérée du rôle d’exécution ; pour votre propre ressource de mémoire, accordez l’accès via additional_execution_role_policy_statements.

Exécution dans un VPC

CDK

Fournissez un vpc pour exécuter le Harness à l’intérieur, afin qu’il puisse atteindre des ressources privées telles qu’une base de données. Le construct implémente IConnectable, donc ces ressources lui accordent l’accès de la même manière qu’elles le feraient pour n’importe quelle autre :

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

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

Le Harness est placé dans les sous-réseaux privés du VPC avec sortie, dans un groupe de sécurité créé pour lui. Remplacez l’un ou l’autre avec vpcSubnets et securityGroups. Les deux nécessitent vpc, et connections n’est disponible que lorsque le Harness s’exécute dans un VPC.

Terraform

Définissez enable_vpc avec vpc_id et subnet_ids pour exécuter le Harness dans un VPC, afin qu’il puisse atteindre des ressources privées telles qu’une base de données :

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
}

Le module crée un groupe de sécurité pour le Harness, autorisant uniquement le HTTPS sortant. Sa sortie security_group_id est ce que les ressources que le Harness doit atteindre référencent dans leurs propres règles d’entrée :

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 est null sauf si enable_vpc est true, et vpc_id et subnet_ids sont tous deux requis lorsqu’il l’est.

Remplacements par invocation

Les valeurs configurées dans l’infrastructure sont des valeurs par défaut de déploiement. Le service accepte également des remplacements par invocation pour les champs Harness pris en charge (tels que les modèles, les outils et les compétences) dans la requête InvokeHarness ; les valeurs par défaut de déploiement s’appliquent partout où un champ n’est pas remplacé.

Valider les remplacements d’invocation

Les remplacements par invocation sont des entrées de confiance à la limite du service : tout appelant autorisé peut remplacer les champs pris en charge. Si des utilisateurs non fiables peuvent atteindre une application qui transmet des remplacements à InvokeHarness, validez-les et autorisez-les au niveau de la couche applicative (par exemple, liste blanche de modèles et d’outils), gardez le rôle d’exécution limité aux ressources requises, et n’accordez pas bedrock-agentcore:InvokeAgentRuntimeCommand sauf si vous en avez spécifiquement besoin.