Garde-fous d'agent TypeScript

Attachez un garde-fou Amazon Bedrock à un agent TypeScript. Un garde-fou est un ensemble de règles qu’Amazon Bedrock applique aux messages que votre agent envoie au modèle et aux réponses du modèle. Sans garde-fou, un utilisateur peut interroger votre agent sur n’importe quel sujet, et le modèle peut répéter des données personnelles telles que des adresses e-mail dans ses réponses.

Le générateur ajoute un fichier de politique qui contient vos règles, le code qui applique le garde-fou au modèle de votre agent, et l’infrastructure qui crée le garde-fou dans votre compte AWS.

Comment cela fonctionne

guardrail.json à côté de votre agent.ts contient les règles : les sujets que votre agent doit refuser et les types de données personnelles (PII, informations personnellement identifiables) qu’il doit masquer ou bloquer.
Votre construct CDK ou module Terraform lit guardrail.json lorsque vous synthétisez ou planifiez. Il crée le garde-fou et une version numérotée de celui-ci. Une version de garde-fou est un instantané en lecture seule des règles.
L’infrastructure écrit l’ID et le numéro de version du garde-fou dans runtime config, l’application AWS AppConfig où votre infrastructure stocke les détails des ressources déployées. L’entrée est agentcore.guardrails.<AgentClass>, nommée d’après la classe de votre agent, par exemple agentcore.guardrails.MyAgent. Chaque agent gardé a sa propre entrée.
guardrail.ts construit le modèle Bedrock que votre appel new Agent({...}) utilise. Avant chaque appel de modèle, le modèle lit l’entrée de l’agent depuis runtime config et applique ce garde-fou.

Utilisation

Générer des garde-fous d’agent

Vous aurez besoin d’un projet TypeScript existant contenant un agent créé avec le générateur ts#agent.

Exécuter ce générateur@aws/nx-plugin:ts#agent#guardrails

CLI
VSCode

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

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

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

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

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - ts#agent#guardrails
Remplissez les paramètres requis
Cliquez sur Generate

Composez votre commande2

projectRequis

agent

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Options

Options du générateur2 options

projectRequisstring: Le projet contenant le TypeScript Agent
agentstring: Le nom du composant Agent à protéger. Requis lorsque le projet contient plus d'un TypeScript Agent.

Sortie du générateur

Le générateur ajoute les fichiers suivants à côté de votre agent, où <agent> est le nom de votre composant d’agent (agent par défaut) :

Répertoire<your-project>/src/<agent>/
- agent.ts Votre agent, maintenant créé avec model: getGuardrailedModel()
- guardrail.json Les règles que votre garde-fou applique
- guardrail.ts Construit le modèle Bedrock avec le garde-fou appliqué

Il ajoute également l’infrastructure pour votre fournisseur iac sélectionné, où <agent-name> est le nom en kebab-case du construct ou module de votre agent :

CDK
Terraform

Répertoirepackages/common/constructs/src/app/guardrails/<agent-name>/
- <agent-name>-guardrail.ts Construct CDK contenant le garde-fou et sa version

Le générateur modifie agent.ts comme ceci :

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.

Exécuter à nouveau le générateur sur le même agent ne modifie aucun fichier, et il conserve vos modifications de guardrail.json.

Si votre agent a été généré avec infra: none, le générateur ajoute uniquement les fichiers de l’agent et affiche un avertissement. Vous créez alors le garde-fou vous-même et écrivez son ID et sa version dans runtime config à agentcore.guardrails.<AgentClass> sous la forme { guardrailId, guardrailVersion }.

Un agent qui définit déjà un modèle

Si votre appel new Agent({...}) définit déjà model, le générateur laisse agent.ts inchangé. Il affiche le nom du fichier et les lignes à ajouter. Pour conserver vos propres options de modèle, créez votre modèle avec la classe GuardrailedBedrockModel de guardrail.ts. Elle prend les mêmes options que BedrockModel, par exemple :

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

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

Ce que le garde-fou vérifie

Le garde-fou vérifie deux choses à chaque appel de modèle :

la conversation que votre agent envoie au modèle, y compris le dernier message de l’utilisateur
la réponse du modèle, avant que votre agent ne la diffuse à l’utilisateur

Lorsque le garde-fou bloque le message d’un utilisateur, l’utilisateur reçoit le texte blockedInputMessaging, et le modèle n’est pas appelé. Strands remplace également le message bloqué dans l’historique de conversation de l’agent par [User input redacted.]. Lorsqu’il bloque une réponse, l’utilisateur reçoit le texte blockedOutputsMessaging. Lorsqu’une règle ANONYMIZE correspond, la réponse contient un espace réservé tel que {EMAIL} au lieu de la valeur.

Le garde-fou ne vérifie pas les définitions d’outils, les arguments que le modèle transmet à vos outils, ou les résultats que vos outils renvoient. Par exemple, si un outil renvoie l’adresse e-mail d’un client depuis une base de données, le garde-fou ne la masque pas au modèle. Traitez les résultats des outils comme non fiables, comme le décrit le guide de l’agent TypeScript sous « Sécuriser votre agent ».

Modifier guardrail.json

La politique fournie est un exemple pour l’agent mathématique généré. Elle refuse les conseils d’investissement et masque ou bloque trois types de données personnelles :

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

Les champs sont :

blockedInputMessaging : la réponse qu’un utilisateur reçoit lorsque le garde-fou bloque son message. 500 caractères maximum.
blockedOutputsMessaging : la réponse qu’un utilisateur reçoit lorsque le garde-fou bloque la réponse du modèle. 500 caractères maximum.
deniedTopics : sujets que votre agent doit refuser. Chaque sujet a un name (100 lettres, chiffres, espaces et caractères -_!?. maximum), une definition de 1000 caractères maximum qui décrit le sujet, et des examples optionnels de 100 caractères maximum chacun.
piiEntities : types de données personnelles sur lesquels agir. type est un type d’information sensible tel que EMAIL, PHONE ou US_SOCIAL_SECURITY_NUMBER. action est ANONYMIZE pour remplacer la valeur par un espace réservé, ou BLOCK pour bloquer l’ensemble du message ou de la réponse.

Écrivez une definition de sujet qui décrit le sujet lui-même. Par exemple, « Recommandations sur les actions spécifiques à acheter » fonctionne mieux que « Ne donnez pas de conseils d’investissement ».

Pourquoi la version est numérotée

Chaque fois que vous modifiez guardrail.json et déployez, l’infrastructure crée une nouvelle version numérotée du garde-fou et l’écrit dans runtime config. La description de la version contient le hachage SHA-256 de guardrail.json, donc une modification du fichier change la description, et une nouvelle version remplace l’ancienne. Avec le construct CDK, le hachage couvre également toutes les propriétés de garde-fou que vous transmettez.

Votre agent en cours d’exécution n’a pas besoin de redémarrage. Il met en cache ce qu’il lit depuis runtime config pendant 5 secondes, donc il utilise la nouvelle version dans les 5 secondes suivant le déploiement AppConfig. L’ancienne version est supprimée après le déploiement AppConfig : CloudFormation la supprime dans son étape de nettoyage, et Terraform la supprime après le module de déploiement lorsque vous ajoutez le module de garde-fou au depends_on de ce module, comme indiqué dans Connecter le garde-fou à votre agent.

Votre agent n’utilise jamais la version DRAFT. DRAFT contient toujours les dernières règles, donc une modification effectuée dans la console AWS atteindrait votre agent en cours d’exécution sans déploiement. guardrail.ts lève une erreur si la version dans runtime config n’est pas un numéro de version.

Connecter le garde-fou à votre agent

Le générateur ne modifie pas votre stack ou votre module Terraform racine, de la même manière que le générateur ts#agent vous laisse déployer l’agent. Lorsqu’il se termine, il affiche le code ci-dessous avec les noms de votre agent remplis. Ajoutez-le pour créer le garde-fou, écrire son entrée runtime-config et permettre à l’agent d’appliquer le garde-fou :

CDK
Terraform

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

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

Le construct écrit l’ID et la version du garde-fou dans runtime config à agentcore.guardrails.MyAgent, et accorde à l’agent la permission d’appliquer le garde-fou. Le construct de l’agent permet déjà à l’agent de lire runtime config.

Le construct expose :

guardrail (le CfnGuardrail) et version (le CfnGuardrailVersion)
guardrailId, guardrailArn et guardrailVersion
grantApply(grantee), qui accorde bedrock:ApplyGuardrail sur le garde-fou à un autre principal

Il ajoute également les sorties de stack GuardrailId et GuardrailVersion. Ses props sont agent et toutes les propriétés CfnGuardrail. Les propriétés CfnGuardrail ont la priorité sur guardrail.json. Par exemple, ajoutez des filtres de contenu :

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

Ajoutez le module my_agent_guardrail comme indiqué, dans le module racine où vous déployez votre agent. Ajoutez sa ligne additional_iam_policy_statements à votre bloc de module my_agent existant. Ajoutez module.my_agent_guardrail à la liste depends_on de votre module runtime_config_appconfig_deployment, afin que le déploiement inclue l’entrée runtime-config du garde-fou et que Terraform supprime une ancienne version du garde-fou uniquement après le déploiement. Si votre module racine ne déploie pas encore l’agent, ajoutez d’abord le module de l’agent, comme décrit dans le guide de l’agent TypeScript.

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

Si votre module d’agent définit déjà additional_iam_policy_statements, combinez les listes :

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

Le module écrit l’ID et la version du garde-fou dans runtime config à agentcore.guardrails.MyAgent. L’espace de noms agentcore est dans les namespaces par défaut des modules runtime-config, vous n’avez donc pas besoin de l’ajouter. Le module de l’agent permet déjà à l’agent de lire runtime config.

Le module prend une variable tags et produit guardrail_id, guardrail_arn, guardrail_version et iam_policy_statements. Pour ajouter d’autres politiques de garde-fou, telles que des filtres de contenu, modifiez la ressource aws_bedrock_guardrail dans le module.

Le module définit create_before_destroy sur la version du garde-fou, donc Terraform crée la nouvelle version avant de supprimer l’ancienne.

Une entrée runtime-config manquante

Si vous oubliez le câblage, runtime config n’a pas d’entrée pour votre agent. Le modèle lève alors une erreur avant d’appeler Bedrock, donc l’agent ne s’exécute pas sans son garde-fou. Pour MyAgent, l’erreur est :

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.

L’agent démarre avec tous les protocoles (http, a2a et ag-ui), et chaque requête échoue avec cette erreur.

Développement local

La cible <agent>-dev définit LOCAL_DEV=true. Lorsque LOCAL_DEV est true et que la variable d’environnement RUNTIME_CONFIG_APP_ID n’est pas définie, guardrail.ts ne lit pas runtime config. Il affiche un avertissement une fois et l’agent s’exécute sans garde-fou :

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Pour tester vos règles localement, déployez d’abord le garde-fou. Ensuite, définissez RUNTIME_CONFIG_APP_ID sur l’ID de votre application runtime-config déployée, depuis la sortie de stack RuntimeConfigApplicationId (CDK) ou module.runtime_config_appconfig.application_id (Terraform). Votre shell a également besoin d’informations d’identification AWS qui peuvent lire AppConfig et appliquer le garde-fou :

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

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

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

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

L’agent lit alors uniquement sa propre entrée, donc plusieurs agents gardés peuvent s’exécuter localement contre la même application. Si l’agent ne peut pas lire runtime config, ou si l’entrée est manquante, il affiche l’avertissement une fois et s’exécute sans garde-fou.

La cible <agent>-serve ne définit pas LOCAL_DEV, elle a donc besoin de RUNTIME_CONFIG_APP_ID et de l’entrée déployée, sinon chaque requête échoue comme décrit ci-dessus. La cible <agent>-chat se connecte à un agent en cours d’exécution et n’a pas besoin de runtime config elle-même.

Coût et latence

Amazon Bedrock facture pour chaque politique de garde-fou qui évalue du texte, à la fois sur l’entrée et sur la réponse. Voir Tarification Amazon Bedrock.

Chaque appel de modèle prend également plus de temps, car le garde-fou vérifie la réponse avant que votre agent ne la diffuse à l’utilisateur.

Limitations

Ce générateur prend en charge les agents créés avec ts#agent. Il ne prend pas en charge le harnais AgentCore.
guardrail.json contient uniquement les sujets refusés et les entités PII. Ajoutez d’autres politiques, telles que les filtres de contenu et les filtres de mots, avec les props du construct (CDK) ou en modifiant le module (Terraform).
Le garde-fou ne vérifie pas les résultats des outils, comme décrit dans Ce que le garde-fou vérifie.