TypeScript Agent Guardrails

Gắn một Amazon Bedrock Guardrail vào TypeScript Agent. Guardrail là một tập hợp các quy tắc mà Amazon Bedrock áp dụng cho các tin nhắn mà agent của bạn gửi đến model và cho các câu trả lời của model. Nếu không có guardrail, người dùng có thể hỏi agent của bạn về bất kỳ chủ đề nào, và model có thể lặp lại dữ liệu cá nhân như địa chỉ email trong các câu trả lời của nó.

Generator thêm một file chính sách chứa các quy tắc của bạn, code áp dụng guardrail cho model của agent, và cơ sở hạ tầng tạo guardrail trong tài khoản AWS của bạn.

Cách hoạt động

guardrail.json bên cạnh agent.ts của bạn chứa các quy tắc: các chủ đề mà agent của bạn phải từ chối và các loại dữ liệu cá nhân (PII, personally identifiable information) mà nó phải ẩn hoặc chặn.
CDK construct hoặc Terraform module của bạn đọc guardrail.json khi bạn synthesize hoặc plan. Nó tạo guardrail và một phiên bản được đánh số của nó. Phiên bản guardrail là một snapshot chỉ đọc của các quy tắc.
Cơ sở hạ tầng ghi ID và số phiên bản của guardrail vào runtime config, ứng dụng AWS AppConfig nơi cơ sở hạ tầng của bạn lưu trữ các chi tiết của các tài nguyên đã triển khai. Entry là agentcore.guardrails.<AgentClass>, được đặt tên theo class của agent, ví dụ agentcore.guardrails.MyAgent. Mỗi agent được bảo vệ có entry riêng của nó.
guardrail.ts xây dựng Bedrock model mà lệnh gọi new Agent({...}) của bạn sử dụng. Trước mỗi lệnh gọi model, model đọc entry của agent từ runtime config và áp dụng guardrail đó.

Cách sử dụng

Tạo Agent Guardrails

Bạn sẽ cần một dự án TypeScript hiện có chứa một agent được tạo bằng generator ts#agent.

Chạy generator này@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

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - ts#agent#guardrails
Điền các tham số bắt buộc
Nhấp Generate

Xây dựng lệnh của bạn2

projectBắt buộc

agent

--dry-runBạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

Tùy chọn

Tùy chọn của generator2 tùy chọn

projectBắt buộcstring: Dự án chứa TypeScript Agent
agentstring: Tên của Agent component cần bảo vệ. Bắt buộc khi dự án chứa nhiều hơn một TypeScript Agent.

Kết quả từ Generator

Generator thêm các file sau bên cạnh agent của bạn, trong đó <agent> là tên của agent component của bạn (mặc định là agent):

Thư mục<your-project>/src/<agent>/
- agent.ts Agent của bạn, giờ được tạo với model: getGuardrailedModel()
- guardrail.json Các quy tắc mà guardrail của bạn áp dụng
- guardrail.ts Xây dựng Bedrock model với guardrail được áp dụng

Nó cũng thêm cơ sở hạ tầng cho nhà cung cấp iac mà bạn đã chọn, trong đó <agent-name> là tên kebab-case của construct hoặc module của agent:

CDK
Terraform

Thư mụcpackages/common/constructs/src/app/guardrails/<agent-name>/
- <agent-name>-guardrail.ts CDK construct chứa guardrail và phiên bản của nó

Generator chỉnh sửa agent.ts như sau:

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.

Chạy generator lại trên cùng một agent sẽ không thay đổi file nào, và nó giữ nguyên các chỉnh sửa của bạn đối với guardrail.json.

Nếu agent của bạn được tạo với infra: none, generator chỉ thêm các file agent và in ra một cảnh báo. Sau đó bạn tự tạo guardrail và ghi ID và phiên bản của nó vào runtime config tại agentcore.guardrails.<AgentClass> dưới dạng { guardrailId, guardrailVersion }.

Agent đã đặt model

Nếu lệnh gọi new Agent({...}) của bạn đã đặt model, generator sẽ để agent.ts không thay đổi. Nó in ra tên file và các dòng cần thêm. Để giữ các tùy chọn model của riêng bạn, hãy tạo model của bạn với class GuardrailedBedrockModel từ guardrail.ts. Nó nhận các tùy chọn giống như BedrockModel, ví dụ:

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

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

Guardrail kiểm tra gì

Guardrail kiểm tra hai thứ trên mỗi lệnh gọi model:

cuộc hội thoại mà agent của bạn gửi đến model, bao gồm tin nhắn mới nhất của người dùng
câu trả lời của model, trước khi agent của bạn stream nó trả lại cho người dùng

Khi guardrail chặn tin nhắn của người dùng, người dùng nhận được văn bản blockedInputMessaging, và model không được gọi. Strands cũng thay thế tin nhắn bị chặn trong lịch sử hội thoại của agent bằng [User input redacted.]. Khi nó chặn một câu trả lời, người dùng nhận được văn bản blockedOutputsMessaging. Khi một quy tắc ANONYMIZE khớp, câu trả lời chứa một placeholder như {EMAIL} thay vì giá trị.

Guardrail không kiểm tra các định nghĩa tool, các đối số mà model truyền cho các tool của bạn, hoặc các kết quả mà các tool của bạn trả về. Ví dụ, nếu một tool trả về địa chỉ email của khách hàng từ cơ sở dữ liệu, guardrail không ẩn nó khỏi model. Xử lý kết quả tool như không đáng tin cậy, như hướng dẫn TypeScript Agent mô tả trong phần “Securing your Agent”.

Chỉnh sửa guardrail.json

Chính sách được cung cấp là một ví dụ cho agent toán học được tạo. Nó từ chối lời khuyên đầu tư và ẩn hoặc chặn ba loại dữ liệu cá nhân:

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

Các trường là:

blockedInputMessaging: câu trả lời mà người dùng nhận được khi guardrail chặn tin nhắn của họ. Tối đa 500 ký tự.
blockedOutputsMessaging: câu trả lời mà người dùng nhận được khi guardrail chặn câu trả lời của model. Tối đa 500 ký tự.
deniedTopics: các chủ đề mà agent của bạn phải từ chối. Mỗi chủ đề có một name (tối đa 100 chữ cái, chữ số, khoảng trắng và các ký tự -_!?.), một definition tối đa 1000 ký tự mô tả chủ đề, và các examples tùy chọn tối đa 100 ký tự mỗi cái.
piiEntities: các loại dữ liệu cá nhân cần hành động. type là một loại thông tin nhạy cảm như EMAIL, PHONE hoặc US_SOCIAL_SECURITY_NUMBER. action là ANONYMIZE để thay thế giá trị bằng một placeholder, hoặc BLOCK để chặn toàn bộ tin nhắn hoặc câu trả lời.

Viết một definition chủ đề mô tả chính chủ đề đó. Ví dụ, “Recommendations about which specific stocks to buy” hoạt động tốt hơn “Do not give investment advice”.

Tại sao phiên bản được đánh số

Mỗi lần bạn thay đổi guardrail.json và triển khai, cơ sở hạ tầng tạo một phiên bản guardrail được đánh số mới và ghi nó vào runtime config. Mô tả của phiên bản chứa hash SHA-256 của guardrail.json, vì vậy một thay đổi đối với file sẽ thay đổi mô tả, và một phiên bản mới thay thế phiên bản cũ. Với CDK construct, hash cũng bao gồm bất kỳ thuộc tính guardrail nào bạn truyền.

Agent đang chạy của bạn không cần khởi động lại. Nó cache những gì nó đọc từ runtime config trong 5 giây, vì vậy nó sử dụng phiên bản mới trong vòng 5 giây sau khi triển khai AppConfig. Phiên bản cũ bị xóa sau khi triển khai AppConfig: CloudFormation xóa nó trong bước cleanup của nó, và Terraform xóa nó sau deployment module khi bạn thêm guardrail module vào depends_on của module đó, như được hiển thị trong Kết nối guardrail với agent của bạn.

Agent của bạn không bao giờ sử dụng phiên bản DRAFT. DRAFT luôn chứa các quy tắc mới nhất, vì vậy một chỉnh sửa được thực hiện trong AWS console sẽ đến agent đang chạy của bạn mà không cần triển khai. guardrail.ts ném ra một lỗi nếu phiên bản trong runtime config không phải là một số phiên bản.

Kết nối guardrail với agent của bạn

Generator không thay đổi stack của bạn hoặc root Terraform module của bạn, theo cách tương tự như generator ts#agent để việc triển khai agent cho bạn. Khi nó hoàn thành, nó in ra code bên dưới với các tên agent của bạn được điền vào. Thêm nó để tạo guardrail, ghi entry runtime-config của nó và cho phép agent áp dụng guardrail:

CDK
Terraform

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

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

Construct ghi ID và phiên bản của guardrail vào runtime config tại agentcore.guardrails.MyAgent, và cấp quyền cho agent để áp dụng guardrail. Agent construct đã cho phép agent đọc runtime config.

Construct expose:

guardrail (CfnGuardrail) và version (CfnGuardrailVersion)
guardrailId, guardrailArn và guardrailVersion
grantApply(grantee), cấp quyền bedrock:ApplyGuardrail trên guardrail cho một principal khác

Nó cũng thêm các stack output GuardrailId và GuardrailVersion. Props của nó là agent và bất kỳ thuộc tính CfnGuardrail nào. Các thuộc tính CfnGuardrail được ưu tiên hơn guardrail.json. Ví dụ, thêm content filter:

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

Thêm module my_agent_guardrail như được hiển thị, trong root module nơi bạn triển khai agent của mình. Thêm dòng additional_iam_policy_statements của nó vào block module my_agent hiện có của bạn. Thêm module.my_agent_guardrail vào danh sách depends_on của module runtime_config_appconfig_deployment của bạn, để triển khai bao gồm entry runtime-config của guardrail và Terraform chỉ xóa phiên bản guardrail cũ sau khi triển khai. Nếu root module của bạn chưa triển khai agent, hãy thêm module của agent trước, như được mô tả trong hướng dẫn TypeScript Agent.

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

Nếu module agent của bạn đã đặt additional_iam_policy_statements, hãy kết hợp các danh sách:

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

Module ghi ID và phiên bản của guardrail vào runtime config tại agentcore.guardrails.MyAgent. Namespace agentcore nằm trong namespaces mặc định của các runtime-config module, vì vậy bạn không cần thêm nó. Agent module đã cho phép agent đọc runtime config.

Module nhận một biến tags và output guardrail_id, guardrail_arn, guardrail_version và iam_policy_statements. Để thêm các chính sách guardrail khác, chẳng hạn như content filter, hãy chỉnh sửa resource aws_bedrock_guardrail trong module.

Module đặt create_before_destroy trên phiên bản guardrail, vì vậy Terraform tạo phiên bản mới trước khi xóa phiên bản cũ.

Entry runtime-config bị thiếu

Nếu bạn quên kết nối, runtime config không có entry cho agent của bạn. Model sau đó ném ra một lỗi trước khi nó gọi Bedrock, vì vậy agent không chạy mà không có guardrail của nó. Đối với MyAgent, lỗi là:

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.

Agent khởi động với mọi giao thức (http, a2a và ag-ui), và mỗi request thất bại với lỗi này.

Phát triển cục bộ

Target <agent>-dev đặt LOCAL_DEV=true. Khi LOCAL_DEV là true và biến môi trường RUNTIME_CONFIG_APP_ID không được đặt, guardrail.ts không đọc runtime config. Nó in ra một cảnh báo một lần và agent chạy mà không có guardrail:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Để kiểm tra các quy tắc của bạn cục bộ, hãy triển khai guardrail trước. Sau đó đặt RUNTIME_CONFIG_APP_ID thành ID của ứng dụng runtime-config đã triển khai của bạn, từ stack output RuntimeConfigApplicationId (CDK) hoặc module.runtime_config_appconfig.application_id (Terraform). Shell của bạn cũng cần thông tin xác thực AWS có thể đọc AppConfig và áp dụng guardrail:

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

Agent sau đó chỉ đọc entry của chính nó, vì vậy nhiều agent được bảo vệ có thể chạy cục bộ với cùng một ứng dụng. Nếu agent không thể đọc runtime config, hoặc entry bị thiếu, nó in ra cảnh báo một lần và chạy mà không có guardrail.

Target <agent>-serve không đặt LOCAL_DEV, vì vậy nó cần RUNTIME_CONFIG_APP_ID và entry đã triển khai, nếu không mỗi request thất bại như mô tả ở trên. Target <agent>-chat kết nối với một agent đang chạy và không cần runtime config.

Chi phí và độ trễ

Amazon Bedrock tính phí cho mỗi chính sách guardrail đánh giá văn bản, trên cả đầu vào và câu trả lời. Xem giá Amazon Bedrock.

Mỗi lệnh gọi model cũng mất nhiều thời gian hơn, vì guardrail kiểm tra câu trả lời trước khi agent của bạn stream nó cho người dùng.

Hạn chế

Generator này hỗ trợ các agent được tạo bằng ts#agent. Nó không hỗ trợ AgentCore Harness.
guardrail.json chỉ chứa các chủ đề bị từ chối và các thực thể PII. Thêm các chính sách khác, chẳng hạn như content filter và word filter, với props của construct (CDK) hoặc bằng cách chỉnh sửa module (Terraform).
Guardrail không kiểm tra kết quả tool, như được mô tả trong Guardrail kiểm tra gì.