TypeScript Agent Guardrails

Anexe um Amazon Bedrock Guardrail a um TypeScript Agent. Um guardrail é um conjunto de regras que o Amazon Bedrock aplica às mensagens que seu agente envia ao modelo e às respostas do modelo. Sem um, um usuário pode perguntar ao seu agente sobre qualquer tópico, e o modelo pode repetir dados pessoais, como endereços de e-mail, em suas respostas.

O gerador adiciona um arquivo de política que contém suas regras, o código que aplica o guardrail ao modelo do seu agente e a infraestrutura que cria o guardrail em sua conta AWS.

Como isso funciona

• guardrail.json ao lado do seu agent.ts contém as regras: os tópicos que seu agente deve recusar e os tipos de dados pessoais (PII, informações de identificação pessoal) que ele deve ocultar ou bloquear.
• Seu construto CDK ou módulo Terraform lê guardrail.json quando você sintetiza ou planeja. Ele cria o guardrail e uma versão numerada dele. Uma versão de guardrail é um snapshot somente leitura das regras.
• A infraestrutura escreve o ID e o número da versão do guardrail para runtime config, a aplicação AWS AppConfig onde sua infraestrutura armazena os detalhes dos recursos implantados. A entrada é agentcore.guardrails.<AgentClass>, nomeada após a classe do seu agente, por exemplo agentcore.guardrails.MyAgent. Cada agente protegido tem sua própria entrada.
• guardrail.ts constrói o modelo Bedrock que sua chamada new Agent({...}) usa. Antes de cada chamada de modelo, o modelo lê a entrada do agente do runtime config e aplica esse guardrail.

Uso

Gerar Agent Guardrails

Você precisará de um projeto TypeScript existente contendo um agente criado com o gerador ts#agent.

Execute este gerador@aws/nx-plugin:ts#agent#guardrails

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#agent#guardrails

yarn

$ yarn nx g @aws/nx-plugin:ts#agent#guardrails

npm

$ npx nx g @aws/nx-plugin:ts#agent#guardrails

bun

$ bunx nx g @aws/nx-plugin:ts#agent#guardrails

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 - ts#agent#guardrails
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Monte seu comando2

projectObrigatório

agent

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

Opções

Opções do gerador2 opções

projectObrigatóriostring

O projeto que contém o TypeScript Agent

agentstring

O nome do componente Agent a proteger. Obrigatório quando o projeto contém mais de um TypeScript Agent.

Saída do Gerador

O gerador adiciona os seguintes arquivos ao lado do seu agente, onde <agent> é o nome do seu componente de agente (agent por padrão):

• Directory<your-project>/src/<agent>/

  • agent.ts Seu agente, agora criado com model: getGuardrailedModel()
  • guardrail.json As regras que seu guardrail aplica
  • guardrail.ts Constrói o modelo Bedrock com o guardrail aplicado

Ele também adiciona a infraestrutura para seu provedor iac selecionado, onde <agent-name> é o nome em kebab-case do construto ou módulo do seu agente:

CDK

• Directorypackages/common/constructs/src/app/guardrails/<agent-name>/

  • <agent-name>-guardrail.ts Construto CDK contendo o guardrail e sua versão

Terraform

• Directorypackages/common/terraform/src/app/guardrails/<agent-name>/

  • <agent-name>-guardrail.tf Módulo Terraform contendo o guardrail e sua versão

O gerador edita agent.ts assim:

import { getGuardrailedModel } from './guardrail.js';
import { Agent, tool } from '@strands-agents/sdk';

export const getAgent = async () => {
  const agent = new Agent({
    model: getGuardrailedModel(),
    systemPrompt: `You are a mathematical wizard.

Executar o gerador novamente no mesmo agente não altera nenhum arquivo e mantém suas edições em guardrail.json.

Se seu agente foi gerado com infra: none, o gerador adiciona apenas os arquivos do agente e imprime um aviso. Você então cria o guardrail você mesmo e escreve seu ID e versão para runtime config em agentcore.guardrails.<AgentClass> como { guardrailId, guardrailVersion }.

Um agente que já define um modelo

Se sua chamada new Agent({...}) já define model, o gerador deixa agent.ts inalterado. Ele imprime o nome do arquivo e as linhas a adicionar. Para manter suas próprias opções de modelo, crie seu modelo com a classe GuardrailedBedrockModel de guardrail.ts. Ela aceita as mesmas opções que BedrockModel, por exemplo:

agent.ts

import { GuardrailedBedrockModel } from './guardrail.js';

const agent = new Agent({
  model: new GuardrailedBedrockModel({ modelId: 'my-model-id' }),
  // ...
});

O que o guardrail verifica

O guardrail verifica duas coisas em cada chamada de modelo:

• a conversa que seu agente envia ao modelo, incluindo a mensagem mais recente do usuário
• a resposta do modelo, antes que seu agente a transmita de volta ao usuário

Quando o guardrail bloqueia a mensagem de um usuário, o usuário recebe o texto blockedInputMessaging, e o modelo não é chamado. Strands também substitui a mensagem bloqueada no histórico de conversas do agente por [User input redacted.]. Quando ele bloqueia uma resposta, o usuário recebe o texto blockedOutputsMessaging. Quando uma regra ANONYMIZE corresponde, a resposta contém um placeholder como {EMAIL} em vez do valor.

O guardrail não verifica definições de ferramentas, os argumentos que o modelo passa para suas ferramentas ou os resultados que suas ferramentas retornam. Por exemplo, se uma ferramenta retorna o endereço de e-mail de um cliente de um banco de dados, o guardrail não o oculta do modelo. Trate os resultados das ferramentas como não confiáveis, conforme o guia TypeScript Agent descreve em “Securing your Agent”.

Editando guardrail.json

A política fornecida é um exemplo para o agente de matemática gerado. Ela recusa conselhos de investimento e oculta ou bloqueia três tipos de dados pessoais:

guardrail.json

{
  "blockedInputMessaging": "Sorry, I can't help with that request.",
  "blockedOutputsMessaging": "Sorry, I can't share that answer.",
  "deniedTopics": [
    {
      "name": "Investment advice",
      "definition": "Recommendations about which specific stocks, funds or other investments to buy or sell.",
      "examples": ["Which stocks should I buy this year?"]
    }
  ],
  "piiEntities": [
    { "type": "EMAIL", "action": "ANONYMIZE" },
    { "type": "PHONE", "action": "ANONYMIZE" },
    { "type": "US_SOCIAL_SECURITY_NUMBER", "action": "BLOCK" }
  ]
}

Os campos são:

• blockedInputMessaging: a resposta que um usuário recebe quando o guardrail bloqueia sua mensagem. No máximo 500 caracteres.
• blockedOutputsMessaging: a resposta que um usuário recebe quando o guardrail bloqueia a resposta do modelo. No máximo 500 caracteres.
• deniedTopics: tópicos que seu agente deve recusar. Cada tópico tem um name (no máximo 100 letras, dígitos, espaços e os caracteres -_!?.), uma definition de no máximo 1000 caracteres que descreve o tópico e examples opcionais de no máximo 100 caracteres cada.
• piiEntities: tipos de dados pessoais para agir. type é um tipo de informação sensível como EMAIL, PHONE ou US_SOCIAL_SECURITY_NUMBER. action é ANONYMIZE para substituir o valor por um placeholder, ou BLOCK para bloquear toda a mensagem ou resposta.

Escreva uma definition de tópico que descreva o tópico em si. Por exemplo, “Recommendations about which specific stocks to buy” funciona melhor do que “Do not give investment advice”.

Por que a versão é numerada

Cada vez que você altera guardrail.json e implanta, a infraestrutura cria uma nova versão numerada do guardrail e a escreve para runtime config. A descrição da versão contém o hash SHA-256 de guardrail.json, então uma alteração no arquivo altera a descrição, e uma nova versão substitui a antiga. Com o construto CDK, o hash também cobre quaisquer propriedades de guardrail que você passar.

Seu agente em execução não precisa de uma reinicialização. Ele armazena em cache o que lê do runtime config por 5 segundos, então ele usa a nova versão dentro de 5 segundos da implantação do AppConfig. A versão antiga é excluída após a implantação do AppConfig: CloudFormation a exclui em sua etapa de limpeza, e Terraform a exclui após o módulo de implantação quando você adiciona o módulo guardrail ao depends_on desse módulo, conforme mostrado em Conectando o guardrail ao seu agente.

Seu agente nunca usa a versão DRAFT. DRAFT sempre contém as regras mais recentes, então uma edição feita no console AWS alcançaria seu agente em execução sem uma implantação. guardrail.ts lança um erro se a versão no runtime config não for um número de versão.

Conectando o guardrail ao seu agente

O gerador não altera sua stack ou seu módulo Terraform raiz, da mesma forma que o gerador ts#agent deixa a implantação do agente para você. Quando termina, ele imprime o código abaixo com os nomes do seu agente preenchidos. Adicione-o para criar o guardrail, escrever sua entrada de runtime-config e permitir que o agente aplique o guardrail:

CDK

packages/infra/src/stacks/application-stack.ts

import { MyAgent, MyAgentGuardrail } from '@my-scope/common-constructs';

const agent = new MyAgent(this, 'MyAgent');
new MyAgentGuardrail(this, 'MyAgentGuardrail', { agent });

O construto escreve o ID e a versão do guardrail para runtime config em agentcore.guardrails.MyAgent, e concede ao agent permissão para aplicar o guardrail. O construto do agente já permite que o agente leia runtime config.

O construto expõe:

• guardrail (o CfnGuardrail) e version (o CfnGuardrailVersion)
• guardrailId, guardrailArn e guardrailVersion
• grantApply(grantee), que concede bedrock:ApplyGuardrail no guardrail para outro principal

Ele também adiciona as saídas de stack GuardrailId e GuardrailVersion. Suas props são agent e quaisquer propriedades CfnGuardrail. As propriedades CfnGuardrail têm precedência sobre guardrail.json. Por exemplo, adicione filtros de conteúdo:

new MyAgentGuardrail(this, 'MyAgentGuardrail', {
  agent,
  contentPolicyConfig: {
    filtersConfig: [
      { type: 'HATE', inputStrength: 'HIGH', outputStrength: 'HIGH' },
    ],
  },
});

Terraform

Adicione o módulo my_agent_guardrail conforme mostrado, no módulo raiz onde você implanta seu agente. Adicione sua linha additional_iam_policy_statements ao seu bloco de módulo my_agent existente. Adicione module.my_agent_guardrail à lista depends_on do seu módulo runtime_config_appconfig_deployment, para que a implantação inclua a entrada de runtime-config do guardrail e o Terraform exclua uma versão antiga do guardrail somente após a implantação. Se seu módulo raiz ainda não implanta o agente, adicione o módulo do agente primeiro, conforme descrito no guia TypeScript Agent.

packages/infra/src/main.tf

module "my_agent_guardrail" {
  source = "../../common/terraform/src/app/guardrails/my-agent"
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
  # ...existing arguments...
  additional_iam_policy_statements = module.my_agent_guardrail.iam_policy_statements
}

module "runtime_config_appconfig_deployment" {
  # ...existing arguments...
  depends_on = [
    # ...existing modules...
    module.my_agent_guardrail,
  ]
}

Se seu módulo de agente já define additional_iam_policy_statements, combine as listas:

  additional_iam_policy_statements = concat(module.my_agent_guardrail.iam_policy_statements, local.my_statements)

O módulo escreve o ID e a versão do guardrail para runtime config em agentcore.guardrails.MyAgent. O namespace agentcore está nos namespaces padrão dos módulos de runtime-config, então você não precisa adicioná-lo. O módulo do agente já permite que o agente leia runtime config.

O módulo recebe uma variável tags e gera guardrail_id, guardrail_arn, guardrail_version e iam_policy_statements. Para adicionar outras políticas de guardrail, como filtros de conteúdo, edite o recurso aws_bedrock_guardrail no módulo.

O módulo define create_before_destroy na versão do guardrail, então o Terraform cria a nova versão antes de excluir a antiga.

Uma entrada de runtime-config ausente

Se você esquecer a conexão, runtime config não tem entrada para seu agente. O modelo então lança um erro antes de chamar Bedrock, então o agente não é executado sem seu guardrail. Para MyAgent, o erro é:

No guardrail for this agent in runtime config at agentcore.guardrails.MyAgent. Add the MyAgentGuardrail construct (CDK) or the guardrails/my-agent module (Terraform) to your infrastructure.

O agente inicia com todos os protocolos (http, a2a e ag-ui), e cada solicitação falha com este erro.

Desenvolvimento local

O alvo <agent>-dev define LOCAL_DEV=true. Quando LOCAL_DEV é true e a variável de ambiente RUNTIME_CONFIG_APP_ID não está definida, guardrail.ts não lê runtime config. Ele imprime um aviso uma vez e o agente é executado sem um guardrail:

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Para testar suas regras localmente, implante o guardrail primeiro. Em seguida, defina RUNTIME_CONFIG_APP_ID para o ID da sua aplicação de runtime-config implantada, da saída de stack RuntimeConfigApplicationId (CDK) ou module.runtime_config_appconfig.application_id (Terraform). Seu shell também precisa de credenciais AWS que possam ler AppConfig e aplicar o guardrail:

pnpm

RUNTIME_CONFIG_APP_ID=<application-id> pnpm nx agent-dev your-project

yarn

RUNTIME_CONFIG_APP_ID=<application-id> yarn nx agent-dev your-project

npm

RUNTIME_CONFIG_APP_ID=<application-id> npx nx agent-dev your-project

bun

RUNTIME_CONFIG_APP_ID=<application-id> bunx nx agent-dev your-project

O agente então lê apenas sua própria entrada, então vários agentes protegidos podem ser executados localmente contra a mesma aplicação. Se o agente não puder ler runtime config, ou a entrada estiver ausente, ele imprime o aviso uma vez e é executado sem um guardrail.

O alvo <agent>-serve não define LOCAL_DEV, então ele precisa de RUNTIME_CONFIG_APP_ID e da entrada implantada, caso contrário cada solicitação falha conforme descrito acima. O alvo <agent>-chat se conecta a um agente em execução e não precisa de runtime config.

Custo e latência

O Amazon Bedrock cobra por cada política de guardrail que avalia texto, tanto na entrada quanto na resposta. Consulte preços do Amazon Bedrock.

Cada chamada de modelo também leva mais tempo, porque o guardrail verifica a resposta antes que seu agente a transmita ao usuário.

Limitações

• Este gerador suporta agentes criados com ts#agent. Ele não suporta o AgentCore Harness.
• guardrail.json contém apenas tópicos negados e entidades PII. Adicione outras políticas, como filtros de conteúdo e filtros de palavras, com as props do construto (CDK) ou editando o módulo (Terraform).
• O guardrail não verifica resultados de ferramentas, conforme descrito em O que o guardrail verifica.