AgentCore Harness

Generate an Amazon Bedrock AgentCore Harness project. A Harness is a managed agent loop powered by Strands Agents: it owns deployment defaults for the model, system prompt, tools, memory, skills, environments, truncation, authorization, and execution limits, while the service accepts per-invocation overrides for supported fields. Reusing the same Runtime Session ID continues the same Harness session.

Usage

Generate an 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

You can also perform a dry-run to see what files would be changed

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. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - agentcore-harness
5. Fill in the required parameters
6. Click Generate

Options

Parameter	Type	Default	Description
name Required	string	-	The name of your AgentCore Harness project. Must contain at least one non-whitespace character which can be normalized into a kebab-case project name (eg. my-harness).
directory	string	-	Parent directory where the harness project is placed. Defaults to packages. Must be a relative path which does not contain parent directory (..) segments.
subDirectory	string	-	The sub directory the project is placed in. Defaults to the kebab-case harness name. Must be a relative path which does not contain parent directory (..) segments.
infra	agentcore | none	agentcore	The type of infrastructure to generate for hosting your harness. Defaults to agentcore. Select none for no hosting.
iac	inherit | cdk | terraform	inherit	The preferred IaC provider for generated harness infrastructure. Defaults to inherit, which uses the provider configured for your workspace.
preferInstallDependencies	boolean	-	Whether to prefer installing dependencies after the generator runs. Defaults to true. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator creates a standalone project at packages/<name>/. Because AWS runs the agent loop for you, the project holds only the prompt that shapes it and a script for talking to it:

• Directorypackages/<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

Infrastructure is generated when infra is agentcore (the default). With infra: none no infrastructure is generated — set HARNESS_ARN to invoke a Harness managed elsewhere, and re-run the generator with infra: agentcore later to add infrastructure; existing project files (including your edits) are preserved.

Since this generator vends infrastructure as code based on your chosen iac, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

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

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

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

Generated Project

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

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

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

      • …
  • project.json Project build targets and configuration

Generated Project

This project is generated using the terraform#project generator and therefore configures the same build targets.

CDK

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

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

Terraform

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

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

The generated infrastructure manages the Harness through the native resource (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) with your generated defaults, creates an IAM execution role with the baseline permissions described below, and uses IAM inbound authorization (no custom JWT authorizer is configured by default).

The Harness ARN is registered at agentcore.harnesses.<ClassName> in Runtime Configuration, preserving any existing entries.

Deploying your AgentCore Harness

The generator creates CDK or Terraform infrastructure as code based on your selected iac provider. You can use this to deploy your Harness through your usual infrastructure workflow.

CDK

The CDK construct for deploying your Harness lives in the common/constructs folder. Instantiate it from a CDK application:

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');
  }
}

The construct’s props interface (MyHarnessProps) extends Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, so any native Harness property can be supplied and takes precedence over the generated defaults:

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

The construct also accepts:

• allowedTools — the tools the Harness may use. The Harness deploys with none unless you supply them, see Configuring tools.
• executionRole — an existing IAM role to use instead of the generated role. A supplied role is used as-is: the baseline permissions are not added to it, and its ARN always feeds the Harness (the raw executionRoleArn string cannot be overridden).
• modelResourceArns — the Bedrock model and inference-profile ARNs the generated execution role may invoke, replacing the default list.
• vpc, vpcSubnets and securityGroups — run the Harness in a VPC so it can reach private resources, see Running in a VPC.

Its public members are harness (the CfnHarness), executionRole, grantPrincipal, the harnessArn getter, connections (in a VPC), addToRolePolicy(statement) for execution role extensions, and grantInvokeAccess(grantee) for authorizing callers.

Deploy the stack with your infrastructure project as usual — see the CDK infrastructure guide.

Terraform

The Terraform module for deploying your Harness is in the common/terraform folder. Reference it from a Terraform configuration:

packages/infra/src/main.tf

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

The module exposes three variables:

• model_id — the Bedrock model or inference profile the Harness uses by default.
• model_resource_arns — the Bedrock model and inference-profile ARNs the execution role may invoke, replacing the default list.
• additional_execution_role_policy_statements — a list of IAM statement objects (Effect, Action, Resource, optional Sid and Condition) appended to the execution role policy.

Everything else is configured on the generated aws_bedrockagentcore_harness resource in the module itself.

The module outputs harness_id, harness_arn, and execution_role_arn.

Deploy with your Terraform project’s plan/apply workflow as usual — see the Terraform project guide.

System prompt visibility

Your infrastructure reads packages/<name>/src/PROMPT.md when you synthesize (CDK) or plan (Terraform), so the prompt is deployment configuration rather than secret storage: its contents appear in the synthesized CloudFormation template or in Terraform state.

Granting access to invoke the harness

You can grant a caller permissions to invoke the harness as follows:

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

A caller needs both bedrock-agentcore:InvokeHarness and bedrock-agentcore:InvokeAgentRuntime on the Harness ARN, which is exactly what grantInvokeAccess grants.

Chatting with your Harness

The generated chat target runs scripts/chat.ts, dropping you into an interactive terminal chat with your deployed Harness:

pnpm

pnpm nx run <project>:chat

yarn

yarn nx run <project>:chat

npm

npx nx run <project>:chat

bun

bunx nx run <project>:chat

Every turn of a run shares one session, so the Harness keeps the conversation context until you exit. Credentials come from the standard AWS SDK credential provider chain, and the AWS Region is derived from the Harness ARN.

The Harness ARN is resolved in this order:

1. HARNESS_ARN (non-empty): used directly, without reading 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: resolves the ARN from the agentcore.harnesses.<ClassName> entry published by the deployed infrastructure:

   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

With neither set, the script fails with an error naming both options.

Customizing your Harness

src/PROMPT.md is the Harness system prompt: edit it and redeploy to change how the Harness behaves. Everything else is configured where you instantiate the infrastructure, or by editing the generated construct or module directly. Re-running the generator never overwrites existing files (it only adds missing files and merges project metadata), so your edits to the prompt and to the generated infrastructure are preserved.

CDK

Every native Harness property of the pinned aws-cdk-lib/aws-bedrockagentcore module is available through the construct’s props — alternate model providers, tool definitions, memory, skills, environment configuration, truncation, custom JWT authorization, and execution limits — and explicit props take precedence over the generated defaults. Alternatively, edit the generated construct in packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Terraform

The generated module keeps the native aws_bedrockagentcore_harness resource directly editable, so provider-native fields — alternate model providers (gemini_model_config, openai_model_config), tool blocks, memory, skill blocks, environments (environment, environment_variables, environment_artifact), truncation, and authorizer_configuration with a custom_jwt_authorizer — are configured by editing packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

Omitting authorizer configuration (the default) means IAM inbound authorization; configure a custom JWT authorizer through the native field to change that.

Configuring tools

The Harness deploys with no tools, so it starts with the least capability. Opt in to the tools it may use:

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

Add an allowed_tools variable to the module if you would rather set it as a module argument where you reference the module.

Narrow @builtin to specific patterns such as @builtin/file_operations to restrict what the agent loop can do. See Harness tools for the built-in tools you can add.

Running in a VPC

CDK

Supply a vpc to run the Harness inside it, so it can reach private resources such as a database. The construct implements IConnectable, so those resources grant it access the same way they would any other:

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

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

The Harness is placed in the VPC’s private subnets with egress, in a security group created for it. Override either with vpcSubnets and securityGroups. Both require vpc, and connections is only available when the Harness runs in a VPC.

Terraform

Add a network_configuration block to the generated aws_bedrockagentcore_harness resource’s environment.agent_core_runtime_environment, then reference the security group you place it in from your other resources’ rules:

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

Per-invocation overrides

The values configured in infrastructure are deployment defaults. The service also accepts per-invocation overrides for supported Harness fields (such as models, tools, and skills) in the InvokeHarness request; deployment defaults apply wherever a field is not overridden.

Validate invocation overrides

Per-invocation overrides are trusted inputs at the service boundary: any authorized caller can override supported fields. If untrusted users can reach an application that forwards overrides to InvokeHarness, validate and authorize them at the application layer (for example, allowlist models and tools), keep the execution role scoped to required resources, and do not grant bedrock-agentcore:InvokeAgentRuntimeCommand unless you specifically need it.