AgentCore Harness

Gere um projeto Amazon Bedrock AgentCore Harness. Um Harness é um loop de agente gerenciado alimentado por Strands Agents: ele possui padrões de implantação para o modelo, prompt do sistema, ferramentas, memória, habilidades, ambientes, truncamento, autorização e limites de execução, enquanto o serviço aceita substituições por invocação para campos suportados. Reutilizar o mesmo Runtime Session ID continua a mesma sessão do Harness.

Uso

Gerar um 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - agentcore-harness
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	O nome do seu projeto AgentCore Harness. Deve conter pelo menos um caractere que não seja espaço em branco e que possa ser normalizado em um nome de projeto no formato kebab-case (ex: my-harness).
directory	string	-	Diretório pai onde o projeto harness é colocado. O padrão é packages. Deve ser um caminho relativo que não contenha segmentos de diretório pai (..).
subDirectory	string	-	O subdiretório onde o projeto é colocado. O padrão é o nome do harness no formato kebab-case. Deve ser um caminho relativo que não contenha segmentos de diretório pai (..).
infra	agentcore | none	agentcore	O tipo de infraestrutura a ser gerada para hospedar seu harness. O padrão é agentcore. Selecione none para nenhuma hospedagem.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido para a infraestrutura do harness gerada. O padrão é inherit, que usa o provedor configurado para seu workspace.
preferInstallDependencies	boolean	-	Se deve preferir instalar dependências após a execução do gerador. O padrão é true. Defina como false para adiar a instalação ao agrupar múltiplos geradores (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projeto do Nx); instale uma vez no final.

Saída do Gerador

O gerador cria um projeto autônomo em packages/<name>/. Como a AWS executa o loop do agente para você, o projeto contém apenas o prompt que o molda e um script para conversar com ele:

• Directorypackages/<name>/

  • src/PROMPT.md O prompt do sistema do Harness
  • scripts/chat.ts Cliente de chat multi-turno para o Harness implantado
  • project.json Adiciona o target chat
  • README.md Instruções de chat e customização

Infraestrutura

A infraestrutura é gerada quando infra é agentcore (o padrão). Com infra: none nenhuma infraestrutura é gerada — defina HARNESS_ARN para invocar um Harness gerenciado em outro lugar, e execute novamente o gerador com infra: agentcore mais tarde para adicionar infraestrutura; os arquivos de projeto existentes (incluindo suas edições) são preservados.

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de 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

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

CDK

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

  • <name>.ts Construto CDK contendo o Harness e a função de execução

Terraform

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

  • <name>.tf Módulo Terraform contendo o Harness e a função de execução

A infraestrutura gerada gerencia o Harness através do recurso nativo (CDK aws_bedrockagentcore.CfnHarness, Terraform aws_bedrockagentcore_harness) com seus padrões gerados, cria uma função de execução IAM com as permissões básicas descritas abaixo, e usa autorização de entrada IAM (nenhum autorizador JWT personalizado é configurado por padrão).

O ARN do Harness é registrado em agentcore.harnesses.<ClassName> na Configuração de Runtime, preservando quaisquer entradas existentes.

Implantando seu AgentCore Harness

O gerador cria infraestrutura como código CDK ou Terraform com base no seu provedor iac selecionado. Você pode usar isso para implantar seu Harness através do seu fluxo de trabalho de infraestrutura usual.

CDK

O construto CDK para implantar seu Harness está na pasta common/constructs. Instancie-o a partir de uma aplicação 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');
  }
}

A interface de props do construto (MyHarnessProps) estende Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>, então qualquer propriedade nativa do Harness pode ser fornecida e tem precedência sobre os padrões gerados:

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

O construto também aceita:

• allowedTools — as ferramentas que o Harness pode usar. O Harness é implantado sem nenhuma a menos que você as forneça, veja Configurando ferramentas.
• executionRole — uma função IAM existente para usar em vez da função gerada. Uma função fornecida é usada como está: as permissões básicas não são adicionadas a ela, e seu ARN sempre alimenta o Harness (a string bruta executionRoleArn não pode ser substituída).
• modelResourceArns — os ARNs de modelo e perfil de inferência do Bedrock que a função de execução gerada pode invocar, substituindo a lista padrão.
• vpc, vpcSubnets e securityGroups — execute o Harness em uma VPC para que ele possa alcançar recursos privados, veja Executando em uma VPC.

Seus membros públicos são harness (o CfnHarness), executionRole, grantPrincipal, o getter harnessArn, connections (em uma VPC), addToRolePolicy(statement) para extensões da função de execução, e grantInvokeAccess(grantee) para autorizar chamadores.

Implante a stack com seu projeto de infraestrutura como de costume — veja o guia de infraestrutura CDK.

Terraform

O módulo Terraform para implantar seu Harness está na pasta common/terraform. Referencie-o a partir de uma configuração Terraform:

packages/infra/src/main.tf

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

O módulo expõe três variáveis:

• model_id — o modelo Bedrock ou perfil de inferência que o Harness usa por padrão.
• model_resource_arns — os ARNs de modelo e perfil de inferência do Bedrock que a função de execução pode invocar, substituindo a lista padrão.
• additional_execution_role_policy_statements — uma lista de objetos de declaração IAM (Effect, Action, Resource, Sid e Condition opcionais) anexados à política da função de execução.

Todo o resto é configurado no recurso aws_bedrockagentcore_harness gerado no próprio módulo.

O módulo produz harness_id, harness_arn, e execution_role_arn.

Implante com o fluxo de trabalho plan/apply do seu projeto Terraform como de costume — veja o guia de projeto Terraform.

Visibilidade do prompt do sistema

Sua infraestrutura lê packages/<name>/src/PROMPT.md quando você sintetiza (CDK) ou planeja (Terraform), então o prompt é configuração de implantação em vez de armazenamento secreto: seu conteúdo aparece no template CloudFormation sintetizado ou no estado do Terraform.

Concedendo acesso para invocar o harness

Você pode conceder permissões a um chamador para invocar o harness da seguinte forma:

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

Um chamador precisa de ambos bedrock-agentcore:InvokeHarness e bedrock-agentcore:InvokeAgentRuntime no ARN do Harness, que é exatamente o que grantInvokeAccess concede.

Conversando com seu Harness

O target chat gerado executa scripts/chat.ts, colocando você em um chat de terminal interativo com seu Harness implantado:

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 uma execução compartilha uma sessão, então o Harness mantém o contexto da conversa até você sair. As credenciais vêm da cadeia de provedores de credenciais padrão do AWS SDK, e a região AWS é derivada do ARN do Harness.

O ARN do Harness é resolvido nesta ordem:

1. HARNESS_ARN (não vazio): usado diretamente, sem ler a Configuração de 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: resolve o ARN da entrada agentcore.harnesses.<ClassName> publicada pela infraestrutura implantada:

   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

Com nenhum definido, o script falha com um erro nomeando ambas as opções.

Customizando seu Harness

src/PROMPT.md é o prompt do sistema do Harness: edite-o e reimplante para mudar como o Harness se comporta. Todo o resto é configurado onde você instancia a infraestrutura, ou editando o construto ou módulo gerado diretamente. Executar novamente o gerador nunca sobrescreve arquivos existentes (ele apenas adiciona arquivos ausentes e mescla metadados do projeto), então suas edições no prompt e na infraestrutura gerada são preservadas.

CDK

Toda propriedade nativa do Harness do módulo fixado aws-cdk-lib/aws-bedrockagentcore está disponível através das props do construto — provedores de modelo alternativos, definições de ferramentas, memória, habilidades, configuração de ambiente, truncamento, autorização JWT personalizada e limites de execução — e props explícitas têm precedência sobre os padrões gerados. Alternativamente, edite o construto gerado em packages/common/constructs/src/app/harnesses/<name>/<name>.ts.

Terraform

O módulo gerado mantém o recurso nativo aws_bedrockagentcore_harness diretamente editável, então campos nativos do provedor — provedores de modelo alternativos (gemini_model_config, openai_model_config), blocos tool, memory, blocos skill, ambientes (environment, environment_variables, environment_artifact), truncation, e authorizer_configuration com um custom_jwt_authorizer — são configurados editando packages/common/terraform/src/app/harnesses/<name>/<name>.tf.

Omitir a configuração do autorizador (o padrão) significa autorização de entrada IAM; configure um autorizador JWT personalizado através do campo nativo para mudar isso.

Configurando ferramentas

O Harness é implantado sem ferramentas, então ele começa com a menor capacidade. Opte pelas ferramentas que ele pode usar:

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

Adicione uma variável allowed_tools ao módulo se você preferir defini-la como um argumento do módulo onde você referencia o módulo.

Restrinja @builtin a padrões específicos como @builtin/file_operations para restringir o que o loop do agente pode fazer. Veja Harness tools para as ferramentas integradas que você pode adicionar.

Executando em uma VPC

CDK

Forneça uma vpc para executar o Harness dentro dela, para que ele possa alcançar recursos privados como um banco de dados. O construto implementa IConnectable, então esses recursos concedem acesso a ele da mesma forma que fariam com qualquer outro:

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

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

O Harness é colocado nas sub-redes privadas da VPC com saída, em um grupo de segurança criado para ele. Substitua qualquer um com vpcSubnets e securityGroups. Ambos requerem vpc, e connections está disponível apenas quando o Harness é executado em uma VPC.

Terraform

Adicione um bloco network_configuration ao environment.agent_core_runtime_environment do recurso aws_bedrockagentcore_harness gerado, então referencie o grupo de segurança no qual você o coloca a partir das regras de seus outros recursos:

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

Substituições por invocação

Os valores configurados na infraestrutura são padrões de implantação. O serviço também aceita substituições por invocação para campos suportados do Harness (como modelos, ferramentas e habilidades) na solicitação InvokeHarness; os padrões de implantação se aplicam onde quer que um campo não seja substituído.

Valide substituições de invocação

Substituições por invocação são entradas confiáveis no limite do serviço: qualquer chamador autorizado pode substituir campos suportados. Se usuários não confiáveis podem alcançar uma aplicação que encaminha substituições para InvokeHarness, valide e autorize-as na camada da aplicação (por exemplo, lista de permissões de modelos e ferramentas), mantenha a função de execução com escopo para recursos necessários, e não conceda bedrock-agentcore:InvokeAgentRuntimeCommand a menos que você especificamente precise disso.