@aws/nx-plugin-mcp 1.0.15 → 1.1.1

package/bin/aws-nx-mcp.js

@@ -55949,6 +55949,14 @@ const generatorsJsonEntries = {
 		"metric": "g30",
 		"guidePages": ["ts-agent"]
 	},
+	"ts#agent#guardrails": {
+		"factory": "./src/ts/agent/guardrails/generator",
+		"schema": "./src/ts/agent/guardrails/schema.json",
+		"description": "Add an Amazon Bedrock Guardrail to a TypeScript Agent",
+		"metric": "g76",
+		"guidePages": ["ts-agent-guardrails"],
+		"experimental": true
+	},
 	"ts#agent#mcp-connection": {
 		"factory": "./src/ts/agent/mcp-connection/generator",
 		"schema": "./src/ts/agent/mcp-connection/schema.json",

package/docs/guides/runtime-config.mdx

@@ -19,7 +19,7 @@ Four built-in namespaces are used by generated constructs:
   - **API URLs** — registered automatically by API constructs
   - **Cognito settings** — registered automatically by the UserIdentity construct
   - **Agent runtime ARNs** — added by the connection generator when you connect a React website to an Agent
-- **`agentcore`** — AgentCore runtime ARNs for agents and MCP servers. Registered automatically by the agent/MCP constructs and used for server-side discovery (agent → agent via A2A, agent → MCP server).
+- **`agentcore`** — AgentCore runtime ARNs for agents and MCP servers, and the guardrail ID and version of each agent guarded with `ts#agent#guardrails`. Registered automatically by the agent/MCP and guardrail constructs and used for server-side discovery (agent → agent via A2A, agent → MCP server).
 - **`dynamodb`** — table names, registered automatically by DynamoDB table constructs and read by the generated table client.
 - **`database`** — Aurora connection details, registered automatically by relational database constructs and read by the generated database client.
 

package/docs/guides/ts-agent-guardrails.mdx

@@ -0,0 +1,250 @@
+---
+title: TypeScript Agent Guardrails
+description: Attach an Amazon Bedrock Guardrail to a TypeScript Strands Agent
+generator: ts#agent#guardrails
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import RunGenerator from '@components/run-generator.astro';
+
+Attach an [Amazon Bedrock Guardrail](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) to a <Link path="guides/ts-agent">TypeScript Agent</Link>. A guardrail is a set of rules that Amazon Bedrock applies to the messages your agent sends to the model and to the model's answers. Without one, a user can ask your agent about any topic, and the model can repeat personal data such as email addresses back in its answers.
+
+The generator adds a policy file that holds your rules, the code that applies the guardrail to your agent's model, and the infrastructure that creates the guardrail in your AWS account.
+
+## How this works
+
+- `guardrail.json` next to your `agent.ts` holds the rules: the topics your agent must refuse and the types of personal data (PII, personally identifiable information) it must hide or block.
+- Your CDK construct or Terraform module reads `guardrail.json` when you synthesize or plan. It creates the guardrail and a numbered version of it. A guardrail version is a read-only snapshot of the rules.
+- The infrastructure writes the guardrail's ID and version number to <Link path="guides/runtime-config">runtime config</Link>, the AWS AppConfig application where your infrastructure stores the details of deployed resources. The entry is `agentcore.guardrails.<AgentClass>`, named after your agent's class, for example `agentcore.guardrails.MyAgent`. Each guarded agent has its own entry.
+- `guardrail.ts` builds the Bedrock model that your `new Agent({...})` call uses. Before each model call, the model reads the agent's entry from runtime config and applies that guardrail.
+
+## Usage
+
+### Generate Agent Guardrails
+
+You will need an existing TypeScript project containing an agent created with the `ts#agent` generator.
+
+<RunGenerator generator="ts#agent#guardrails" />
+
+### Options
+
+<GeneratorParameters generator="ts#agent#guardrails" />
+
+## Generator Output
+
+The generator adds the following files next to your agent, where `<agent>` is the name of your agent component (`agent` by default):
+
+<FileTree>
+  - \<your-project>/src/\<agent>/
+    - agent.ts Your agent, now created with `model: getGuardrailedModel()`
+    - guardrail.json The rules your guardrail applies
+    - guardrail.ts Builds the Bedrock model with the guardrail applied
+</FileTree>
+
+It also adds the infrastructure for your selected `iac` provider, where `<agent-name>` is the kebab-case name of your agent's construct or module:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src/app/guardrails/\<agent-name>/
+        - \<agent-name>-guardrail.ts CDK construct containing the guardrail and its version
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src/app/guardrails/\<agent-name>/
+        - \<agent-name>-guardrail.tf Terraform module containing the guardrail and its version
+    </FileTree>
+  </Fragment>
+</Infrastructure>
+
+The generator edits `agent.ts` like this:
+
+```diff lang="ts"
++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.
+```
+
+Running the generator again on the same agent changes no file, and it keeps your edits to `guardrail.json`.
+
+If your agent was generated with `infra: none`, the generator adds only the agent files and prints a warning. You then create the guardrail yourself and write its ID and version to runtime config at `agentcore.guardrails.<AgentClass>` as `{ guardrailId, guardrailVersion }`.
+
+### An agent that already sets a model
+
+If your `new Agent({...})` call already sets `model`, the generator leaves `agent.ts` unchanged. It prints the file name and the lines to add. To keep your own model options, create your model with the `GuardrailedBedrockModel` class from `guardrail.ts`. It takes the same options as `BedrockModel`, for example:
+
+```ts title="agent.ts"
+import { GuardrailedBedrockModel } from './guardrail.js';
+
+const agent = new Agent({
+  model: new GuardrailedBedrockModel({ modelId: 'my-model-id' }),
+  // ...
+});
+```
+
+## What the guardrail checks
+
+The guardrail checks two things on every model call:
+
+- the conversation your agent sends to the model, including the user's latest message
+- the model's answer, before your agent streams it back to the user
+
+When the guardrail blocks a user's message, the user gets the `blockedInputMessaging` text, and the model is not called. Strands also replaces the blocked message in the agent's conversation history with `[User input redacted.]`. When it blocks an answer, the user gets the `blockedOutputsMessaging` text. When an `ANONYMIZE` rule matches, the answer contains a placeholder such as `{EMAIL}` instead of the value.
+
+The guardrail does not check tool definitions, the arguments the model passes to your tools, or the results your tools return. For example, if a tool returns a customer's email address from a database, the guardrail does not hide it from the model. Treat tool results as untrusted, as the <Link path="guides/ts-agent">TypeScript Agent guide</Link> describes under "Securing your Agent".
+
+## Editing guardrail.json
+
+The vended policy is an example for the generated maths agent. It refuses investment advice and hides or blocks three types of personal data:
+
+```json title="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" }
+  ]
+}
+```
+
+The fields are:
+
+- `blockedInputMessaging`: the reply a user gets when the guardrail blocks their message. At most 500 characters.
+- `blockedOutputsMessaging`: the reply a user gets when the guardrail blocks the model's answer. At most 500 characters.
+- `deniedTopics`: topics your agent must refuse. Each topic has a `name` (at most 100 letters, digits, spaces and the characters `-_!?.`), a `definition` of at most 1000 characters that describes the topic, and optional `examples` of at most 100 characters each.
+- `piiEntities`: types of personal data to act on. `type` is a [sensitive information type](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-sensitive-filters.html) such as `EMAIL`, `PHONE` or `US_SOCIAL_SECURITY_NUMBER`. `action` is `ANONYMIZE` to replace the value with a placeholder, or `BLOCK` to block the whole message or answer.
+
+Write a topic `definition` that describes the topic itself. For example, "Recommendations about which specific stocks to buy" works better than "Do not give investment advice".
+
+### Why the version is numbered
+
+Each time you change `guardrail.json` and deploy, the infrastructure creates a new numbered guardrail version and writes it to runtime config. The version's description holds the SHA-256 hash of `guardrail.json`, so a change to the file changes the description, and a new version replaces the old one. With the CDK construct, the hash also covers any guardrail properties you pass.
+
+Your running agent does not need a restart. It caches what it reads from runtime config for 5 seconds, so it uses the new version within 5 seconds of the AppConfig deployment. The old version is deleted after the AppConfig deployment: CloudFormation deletes it in its cleanup step, and Terraform deletes it after the deployment module when you add the guardrail module to that module's `depends_on`, as shown in [Wiring the guardrail to your agent](#wiring-the-guardrail-to-your-agent).
+
+Your agent never uses the `DRAFT` version. `DRAFT` always holds the latest rules, so an edit made in the AWS console would reach your running agent without a deployment. `guardrail.ts` throws an error if the version in runtime config is not a version number.
+
+## Wiring the guardrail to your agent
+
+The generator does not change your stack or your root Terraform module, in the same way that the `ts#agent` generator leaves deploying the agent to you. When it finishes, it prints the code below with your agent's names filled in. Add it to create the guardrail, write its runtime-config entry and allow the agent to apply the guardrail:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts title="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 });
+```
+
+The construct writes the guardrail's ID and version to runtime config at `agentcore.guardrails.MyAgent`, and grants the `agent` permission to apply the guardrail. The agent construct already allows the agent to read runtime config.
+
+The construct exposes:
+
+- `guardrail` (the `CfnGuardrail`) and `version` (the `CfnGuardrailVersion`)
+- `guardrailId`, `guardrailArn` and `guardrailVersion`
+- `grantApply(grantee)`, which grants `bedrock:ApplyGuardrail` on the guardrail to another principal
+
+It also adds the `GuardrailId` and `GuardrailVersion` stack outputs. Its props are `agent` and any `CfnGuardrail` properties. The `CfnGuardrail` properties take precedence over `guardrail.json`. For example, add content filters:
+
+```ts
+new MyAgentGuardrail(this, 'MyAgentGuardrail', {
+  agent,
+  contentPolicyConfig: {
+    filtersConfig: [
+      { type: 'HATE', inputStrength: 'HIGH', outputStrength: 'HIGH' },
+    ],
+  },
+});
+```
+  </Fragment>
+  <Fragment slot="terraform">
+Add the `my_agent_guardrail` module as shown, in the root module where you deploy your agent. Add its `additional_iam_policy_statements` line to your existing `my_agent` module block. Add `module.my_agent_guardrail` to the `depends_on` list of your `runtime_config_appconfig_deployment` module, so the deployment includes the guardrail's runtime-config entry and Terraform deletes an old guardrail version only after the deployment. If your root module does not deploy the agent yet, add the agent's module first, as described in <Link path="guides/ts-agent#infrastructure-as-code">the TypeScript Agent guide</Link>.
+
+```hcl title="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,
+  ]
+}
+```
+
+If your agent module already sets `additional_iam_policy_statements`, combine the lists:
+
+```hcl
+  additional_iam_policy_statements = concat(module.my_agent_guardrail.iam_policy_statements, local.my_statements)
+```
+
+The module writes the guardrail's ID and version to runtime config at `agentcore.guardrails.MyAgent`. The `agentcore` namespace is in the default `namespaces` of the runtime-config modules, so you do not need to add it. The agent module already allows the agent to read runtime config.
+
+The module takes a `tags` variable and outputs `guardrail_id`, `guardrail_arn`, `guardrail_version` and `iam_policy_statements`. To add other guardrail policies, such as content filters, edit the `aws_bedrock_guardrail` resource in the module.
+
+The module sets `create_before_destroy` on the guardrail version, so Terraform creates the new version before it deletes the old one.
+  </Fragment>
+</Infrastructure>
+
+### A missing runtime-config entry
+
+If you forget the wiring, runtime config has no entry for your agent. The model then throws an error before it calls Bedrock, so the agent does not run without its guardrail. For `MyAgent`, the error is:
+
+```
+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.
+```
+
+The agent starts with every protocol (`http`, `a2a` and `ag-ui`), and each request fails with this error.
+
+## Local development
+
+The `<agent>-dev` target sets `LOCAL_DEV=true`. When `LOCAL_DEV` is `true` and the `RUNTIME_CONFIG_APP_ID` environment variable is not set, `guardrail.ts` does not read runtime config. It prints a warning once and the agent runs without a guardrail:
+
+<NxCommands commands={['agent-dev your-project']} />
+
+To test your rules locally, deploy the guardrail first. Then set `RUNTIME_CONFIG_APP_ID` to the ID of your deployed runtime-config application, from the `RuntimeConfigApplicationId` stack output (CDK) or `module.runtime_config_appconfig.application_id` (Terraform). Your shell also needs AWS credentials that can read AppConfig and apply the guardrail:
+
+<NxCommands commands={['agent-dev your-project']} env={{ RUNTIME_CONFIG_APP_ID: '<application-id>' }} />
+
+The agent then reads only its own entry, so several guarded agents can run locally against the same application. If the agent cannot read runtime config, or the entry is missing, it prints the warning once and runs without a guardrail.
+
+The `<agent>-serve` target does not set `LOCAL_DEV`, so it needs `RUNTIME_CONFIG_APP_ID` and the deployed entry, otherwise each request fails as described above. The `<agent>-chat` target connects to a running agent and needs no runtime config itself.
+
+## Cost and latency
+
+Amazon Bedrock charges for each guardrail policy that evaluates text, on both the input and the answer. See [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/).
+
+Each model call also takes longer, because the guardrail checks the answer before your agent streams it to the user.
+
+## Limitations
+
+- This generator supports agents created with `ts#agent`. It does not support the AgentCore Harness.
+- `guardrail.json` holds denied topics and PII entities only. Add other policies, such as content filters and word filters, with the construct's props (CDK) or by editing the module (Terraform).
+- The guardrail does not check tool results, as described in [What the guardrail checks](#what-the-guardrail-checks).

package/docs/guides/ts-agent.mdx

@@ -552,20 +552,13 @@ Refer to the <Link path="/guides/connection/react-agui">`connection` generator g
 
 <Snippet name="agent/securing-your-agent" parentHeading="Securing your Agent" />
 
+The <Link path="guides/ts-agent-guardrails">`ts#agent#guardrails` generator</Link> does this for you. It adds a `guardrail.json` policy file and the CDK construct or Terraform module that creates the guardrail, and it creates your agent with the guardrailed model:
+
 ```typescript
 // agent.ts
-import { Agent } from '@strands-agents/sdk';
-import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
-
-const model = new BedrockModel({
-  modelId: process.env.MODEL_ID,
-  guardrailConfig: {
-    guardrailIdentifier: process.env.GUARDRAIL_ID!,
-    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
-  },
-});
+import { getGuardrailedModel } from './guardrail.js';
 
-const agent = new Agent({ model, /* ... */ });
+const agent = new Agent({ model: getGuardrailedModel(), /* ... */ });
 ```
 
 See the Strands [Guardrails](https://strandsagents.com/docs/user-guide/safety-security/guardrails/) guide for more detail.

package/generators.json

@@ -350,6 +350,14 @@
       "metric": "g30",
       "guidePages": ["ts-agent"]
     },
+    "ts#agent#guardrails": {
+      "factory": "./src/ts/agent/guardrails/generator",
+      "schema": "./src/ts/agent/guardrails/schema.json",
+      "description": "Add an Amazon Bedrock Guardrail to a TypeScript Agent",
+      "metric": "g76",
+      "guidePages": ["ts-agent-guardrails"],
+      "experimental": true
+    },
     "ts#agent#mcp-connection": {
       "factory": "./src/ts/agent/mcp-connection/generator",
       "schema": "./src/ts/agent/mcp-connection/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.15",
+  "version": "1.1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/ts/agent/guardrails/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "ts#agent#guardrails",
+  "title": "ts#agent#guardrails",
+  "x-label": "Agent Guardrails",
+  "description": "Add an Amazon Bedrock Guardrail to a TypeScript Agent",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project containing the TypeScript Agent",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "Select the project containing the TypeScript Agent to guard",
+      "x-dropdown": "projects"
+    },
+    "agent": {
+      "type": "string",
+      "description": "The name of the Agent component to guard. Required when the project contains more than one TypeScript Agent."
+    }
+  },
+  "required": ["project"]
+}