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

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	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).
directory	string	-	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 (..).
subDirectory	string	-	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 (..).
infra	agentcore | none	agentcore	Le type d'infrastructure à générer pour héberger votre harness. Par défaut agentcore. Sélectionnez none pour aucun hébergement.
iac	inherit | cdk | terraform	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.
preferInstallDependencies	boolean	-	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
  • project.json Adds the chat target
  • 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. Le Harness se déploie sans aucun outil sauf si vous les fournissez, 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 trois variables :

• model_id — le modèle Bedrock ou le profil d’inférence que le Harness utilise par défaut.
• model_resource_arns — les ARN de modèle Bedrock et de profil d’inférence que le rôle d’exécution 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.

Tout le reste est configuré sur la ressource aws_bedrockagentcore_harness générée dans le module lui-même.

Le module produit harness_id, harness_arn et execution_role_arn.

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

Le module généré garde la ressource native aws_bedrockagentcore_harness directement modifiable, donc les champs natifs du fournisseur — fournisseurs de modèles alternatifs (gemini_model_config, openai_model_config), blocs tool, memory, blocs skill, environnements (environment, environment_variables, environment_artifact), truncation et authorizer_configuration avec un custom_jwt_authorizer — sont configurés en modifiant packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

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/common/terraform/src/app/harnesses/my-harness/my-harness.tf

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

Ajoutez une variable allowed_tools au module si vous préférez la définir comme argument de module là où vous référencez le module.

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.

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

Ajoutez un bloc network_configuration à l’environment.agent_core_runtime_environment de la ressource aws_bedrockagentcore_harness générée, puis référencez le groupe de sécurité dans lequel vous le placez depuis les règles de vos autres ressources :

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

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.