AgentCore Harness

Genera un progetto Amazon Bedrock AgentCore Harness. Un Harness è un ciclo di agenti gestito alimentato da Strands Agents: possiede i valori predefiniti di distribuzione per il modello, il prompt di sistema, gli strumenti, la memoria, le competenze, gli ambienti, il troncamento, l’autorizzazione e i limiti di esecuzione, mentre il servizio accetta override per invocazione per i campi supportati. Riutilizzare lo stesso Runtime Session ID continua la stessa sessione Harness.

Utilizzo

Genera 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - agentcore-harness
5. Compila i parametri richiesti
6. Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
name Obbligatorio	string	-	Il nome del tuo progetto AgentCore Harness. Deve contenere almeno un carattere non vuoto che possa essere normalizzato in un nome di progetto kebab-case (es. my-harness).
directory	string	-	Directory padre dove viene posizionato il progetto harness. Il valore predefinito è packages. Deve essere un percorso relativo che non contenga segmenti di directory padre (..).
subDirectory	string	-	La sotto-directory in cui viene posizionato il progetto. Il valore predefinito è il nome harness in kebab-case. Deve essere un percorso relativo che non contenga segmenti di directory padre (..).
infra	agentcore | none	agentcore	Il tipo di infrastruttura da generare per l'hosting del tuo harness. Il valore predefinito è agentcore. Seleziona none per nessun hosting.
iac	inherit | cdk | terraform	inherit	Il provider IaC preferito per l'infrastruttura harness generata. Il valore predefinito è inherit, che utilizza il provider configurato per il tuo workspace.
preferInstallDependencies	boolean	-	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Il valore predefinito è true. Imposta a false per differire l'installazione quando si eseguono più generatori in batch (un'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo del progetto Nx); installa una volta alla fine.

Output del generatore

Il generatore crea un progetto autonomo in packages/<name>/. Poiché AWS esegue il ciclo dell’agente per te, il progetto contiene solo il prompt che lo modella e uno script per comunicare con esso:

• Directorypackages/<name>/

  • src/PROMPT.md Il prompt di sistema dell’Harness
  • scripts/chat.ts Client di chat multi-turno per l’Harness distribuito
  • project.json Aggiunge il target chat
  • README.md Istruzioni per la chat e la personalizzazione

Infrastruttura

L’infrastruttura viene generata quando infra è agentcore (il valore predefinito). Con infra: none non viene generata alcuna infrastruttura — imposta HARNESS_ARN per invocare un Harness gestito altrove e riesegui il generatore con infra: agentcore in seguito per aggiungere l’infrastruttura; i file di progetto esistenti (incluse le tue modifiche) vengono preservati.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

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

Progetto Generato

Questo progetto è generato utilizzando il generatore ts#project e quindi configura gli stessi target di build.

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

Progetto Generato

Questo progetto è generato utilizzando il generatore terraform#project e quindi configura gli stessi target di build.

CDK

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

  • <name>.ts Costrutto CDK contenente l’Harness e il ruolo di esecuzione

Terraform

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

  • <name>.tf Modulo Terraform contenente l’Harness e il ruolo di esecuzione

L’infrastruttura generata gestisce l’Harness attraverso la risorsa nativa (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) con i tuoi valori predefiniti generati, crea un ruolo di esecuzione IAM con le autorizzazioni di base descritte di seguito e utilizza l’autorizzazione in entrata IAM (nessun autorizzatore JWT personalizzato è configurato per impostazione predefinita).

L’ARN dell’Harness è registrato in agentcore.harnesses.<ClassName> nella Configurazione Runtime, preservando eventuali voci esistenti.

Distribuzione del tuo AgentCore Harness

Il generatore crea infrastruttura come codice CDK o Terraform in base al provider iac selezionato. Puoi utilizzarlo per distribuire il tuo Harness attraverso il tuo consueto flusso di lavoro dell’infrastruttura.

CDK

Il costrutto CDK per distribuire il tuo Harness si trova nella cartella common/constructs. Istanzialo da un’applicazione 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’interfaccia props del costrutto (MyHarnessProps) estende Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, quindi qualsiasi proprietà nativa dell’Harness può essere fornita e ha la precedenza sui valori predefiniti generati:

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

Il costrutto accetta anche:

• allowedTools — gli strumenti che l’Harness può utilizzare. L’Harness viene distribuito senza strumenti a meno che tu non li fornisca, vedi Configurazione degli strumenti.
• executionRole — un ruolo IAM esistente da utilizzare al posto del ruolo generato. Un ruolo fornito viene utilizzato così com’è: le autorizzazioni di base non vengono aggiunte ad esso e il suo ARN alimenta sempre l’Harness (la stringa executionRoleArn grezza non può essere sovrascritta).
• modelResourceArns — gli ARN del modello Bedrock e del profilo di inferenza che il ruolo di esecuzione generato può invocare, sostituendo l’elenco predefinito.
• vpc, vpcSubnets e securityGroups — esegui l’Harness in un VPC in modo che possa raggiungere risorse private, vedi Esecuzione in un VPC.

I suoi membri pubblici sono harness (il CfnHarness), executionRole, grantPrincipal, il getter harnessArn, connections (in un VPC), addToRolePolicy(statement) per le estensioni del ruolo di esecuzione e grantInvokeAccess(grantee) per autorizzare i chiamanti.

Distribuisci lo stack con il tuo progetto di infrastruttura come al solito — vedi la guida all’infrastruttura CDK.

Terraform

Il modulo Terraform per distribuire il tuo Harness si trova nella cartella common/terraform. Fai riferimento ad esso da una configurazione Terraform:

packages/infra/src/main.tf

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

Il modulo espone tre variabili:

• model_id — il modello Bedrock o il profilo di inferenza che l’Harness utilizza per impostazione predefinita.
• model_resource_arns — gli ARN del modello Bedrock e del profilo di inferenza che il ruolo di esecuzione può invocare, sostituendo l’elenco predefinito.
• additional_execution_role_policy_statements — un elenco di oggetti di istruzione IAM (Effect, Action, Resource, Sid e Condition opzionali) aggiunti alla policy del ruolo di esecuzione.

Tutto il resto è configurato sulla risorsa aws_bedrockagentcore_harness generata nel modulo stesso.

Il modulo restituisce harness_id, harness_arn e execution_role_arn.

Distribuisci con il consueto flusso di lavoro plan/apply del tuo progetto Terraform — vedi la guida al progetto Terraform.

Visibilità del prompt di sistema

La tua infrastruttura legge packages/<name>/src/PROMPT.md quando sintetizzi (CDK) o pianifichi (Terraform), quindi il prompt è una configurazione di distribuzione piuttosto che un archivio segreto: il suo contenuto appare nel template CloudFormation sintetizzato o nello stato Terraform.

Concessione dell’accesso per invocare l’harness

Puoi concedere a un chiamante le autorizzazioni per invocare l’harness come segue:

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 chiamante necessita sia di bedrock-agentcore:InvokeHarness che di bedrock-agentcore:InvokeAgentRuntime sull’ARN dell’Harness, che è esattamente ciò che grantInvokeAccess concede.

Chattare con il tuo Harness

Il target chat generato esegue scripts/chat.ts, portandoti in una chat interattiva da terminale con il tuo Harness distribuito:

pnpm

pnpm nx run <project>:chat

yarn

yarn nx run <project>:chat

npm

npx nx run <project>:chat

bun

bunx nx run <project>:chat

Ogni turno di un’esecuzione condivide una sessione, quindi l’Harness mantiene il contesto della conversazione fino a quando non esci. Le credenziali provengono dalla catena di provider di credenziali standard dell’AWS SDK e la regione AWS è derivata dall’ARN dell’Harness.

L’ARN dell’Harness viene risolto in questo ordine:

1. HARNESS_ARN (non vuoto): utilizzato direttamente, senza leggere la Configurazione Runtime:

   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: risolve l’ARN dalla voce agentcore.harnesses.<ClassName> pubblicata dall’infrastruttura distribuita:

   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

Se nessuno dei due è impostato, lo script fallisce con un errore che nomina entrambe le opzioni.

Personalizzazione del tuo Harness

src/PROMPT.md è il prompt di sistema dell’Harness: modificalo e ridistribuisci per cambiare il comportamento dell’Harness. Tutto il resto è configurato dove istanzi l’infrastruttura, o modificando direttamente il costrutto o il modulo generato. Rieseguire il generatore non sovrascrive mai i file esistenti (aggiunge solo i file mancanti e unisce i metadati del progetto), quindi le tue modifiche al prompt e all’infrastruttura generata vengono preservate.

CDK

Ogni proprietà nativa dell’Harness del modulo aws-cdk-lib/aws-bedrockagentcore bloccato è disponibile attraverso le props del costrutto — provider di modelli alternativi, definizioni di strumenti, memoria, competenze, configurazione dell’ambiente, troncamento, autorizzazione JWT personalizzata e limiti di esecuzione — e le props esplicite hanno la precedenza sui valori predefiniti generati. In alternativa, modifica il costrutto generato in packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Terraform

Il modulo generato mantiene la risorsa nativa aws_bedrockagentcore_harness direttamente modificabile, quindi i campi nativi del provider — provider di modelli alternativi (gemini_model_config, openai_model_config), blocchi tool, memory, blocchi skill, ambienti (environment, environment_variables, environment_artifact), truncation e authorizer_configuration con un custom_jwt_authorizer — sono configurati modificando packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

Omettere la configurazione dell’autorizzatore (il valore predefinito) significa autorizzazione in entrata IAM; configura un autorizzatore JWT personalizzato attraverso il campo nativo per cambiarlo.

Configurazione degli strumenti

L’Harness viene distribuito senza strumenti, quindi inizia con la minima capacità. Opta per gli strumenti che può utilizzare:

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

Aggiungi una variabile allowed_tools al modulo se preferisci impostarla come argomento del modulo dove fai riferimento al modulo.

Restringi @builtin a pattern specifici come @builtin/file_operations per limitare ciò che il ciclo dell’agente può fare. Vedi Strumenti Harness per gli strumenti integrati che puoi aggiungere.

Esecuzione in un VPC

CDK

Fornisci un vpc per eseguire l’Harness al suo interno, in modo che possa raggiungere risorse private come un database. Il costrutto implementa IConnectable, quindi quelle risorse gli concedono l’accesso nello stesso modo in cui lo farebbero con qualsiasi altro:

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

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

L’Harness viene posizionato nelle subnet private del VPC con egress, in un gruppo di sicurezza creato per esso. Sovrascrivi uno dei due con vpcSubnets e securityGroups. Entrambi richiedono vpc, e connections è disponibile solo quando l’Harness viene eseguito in un VPC.

Terraform

Aggiungi un blocco network_configuration all’environment.agent_core_runtime_environment della risorsa aws_bedrockagentcore_harness generata, quindi fai riferimento al gruppo di sicurezza in cui lo posizioni dalle regole delle tue altre risorse:

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

Override per invocazione

I valori configurati nell’infrastruttura sono valori predefiniti di distribuzione. Il servizio accetta anche override per invocazione per i campi Harness supportati (come modelli, strumenti e competenze) nella richiesta InvokeHarness; i valori predefiniti di distribuzione si applicano ovunque un campo non venga sovrascritto.

Convalida gli override di invocazione

Gli override per invocazione sono input affidabili al confine del servizio: qualsiasi chiamante autorizzato può sovrascrivere i campi supportati. Se utenti non affidabili possono raggiungere un’applicazione che inoltra gli override a InvokeHarness, convalidali e autorizzali a livello di applicazione (ad esempio, lista consentita di modelli e strumenti), mantieni il ruolo di esecuzione limitato alle risorse richieste e non concedere bedrock-agentcore:InvokeAgentRuntimeCommand a meno che tu non ne abbia specificamente bisogno.