TypeScript Agent Guardrails

TypeScript Agent에 Amazon Bedrock Guardrail을 연결합니다. 가드레일은 에이전트가 모델에 보내는 메시지와 모델의 답변에 Amazon Bedrock이 적용하는 규칙 집합입니다. 가드레일이 없으면 사용자가 에이전트에게 어떤 주제에 대해서든 질문할 수 있고, 모델이 이메일 주소와 같은 개인 데이터를 답변에 반복할 수 있습니다.

제너레이터는 규칙을 담은 정책 파일, 에이전트의 모델에 가드레일을 적용하는 코드, 그리고 AWS 계정에 가드레일을 생성하는 인프라를 추가합니다.

작동 방식

agent.ts 옆에 있는 guardrail.json은 규칙을 담고 있습니다: 에이전트가 거부해야 하는 주제와 숨기거나 차단해야 하는 개인 데이터(PII, 개인 식별 정보) 유형입니다.
CDK 구성 또는 Terraform 모듈은 합성 또는 계획 시 guardrail.json을 읽습니다. 가드레일과 번호가 매겨진 버전을 생성합니다. 가드레일 버전은 규칙의 읽기 전용 스냅샷입니다.
인프라는 가드레일의 ID와 버전 번호를 runtime config에 씁니다. runtime config는 인프라가 배포된 리소스의 세부 정보를 저장하는 AWS AppConfig 애플리케이션입니다. 항목은 agentcore.guardrails.<AgentClass>이며, 에이전트의 클래스 이름을 따서 명명됩니다. 예를 들어 agentcore.guardrails.MyAgent입니다. 각 보호된 에이전트에는 자체 항목이 있습니다.
guardrail.ts는 new Agent({...}) 호출이 사용하는 Bedrock 모델을 빌드합니다. 각 모델 호출 전에 모델은 runtime config에서 에이전트의 항목을 읽고 해당 가드레일을 적용합니다.

사용법

Agent Guardrails 생성

ts#agent 제너레이터로 생성된 에이전트를 포함하는 기존 TypeScript 프로젝트가 필요합니다.

이 제너레이터 실행@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

설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
VSCode에서 Nx 콘솔 열기
클릭 Generate (UI) "Common Nx Commands" 섹션에서
검색 @aws/nx-plugin - ts#agent#guardrails
필수 매개변수 입력
클릭 Generate

명령 구성하기2

project필수

agent

--dry-run어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

옵션

제너레이터 옵션2 옵션

project필수string: TypeScript Agent를 포함하는 프로젝트
agentstring: 보호할 Agent 컴포넌트의 이름입니다. 프로젝트에 둘 이상의 TypeScript Agent가 포함된 경우 필수입니다.

제너레이터 출력

제너레이터는 에이전트 옆에 다음 파일을 추가합니다. 여기서 <agent>는 에이전트 컴포넌트의 이름입니다(기본값은 agent):

디렉터리<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

또한 선택한 iac 제공자에 대한 인프라를 추가합니다. 여기서 <agent-name>은 에이전트의 구성 또는 모듈의 케밥 케이스 이름입니다:

CDK
Terraform

디렉터리packages/common/constructs/src/app/guardrails/<agent-name>/
- <agent-name>-guardrail.ts CDK construct containing the guardrail and its version

제너레이터는 다음과 같이 agent.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.

동일한 에이전트에서 제너레이터를 다시 실행하면 파일이 변경되지 않으며, guardrail.json에 대한 편집 내용이 유지됩니다.

에이전트가 infra: none으로 생성된 경우, 제너레이터는 에이전트 파일만 추가하고 경고를 출력합니다. 그런 다음 가드레일을 직접 생성하고 agentcore.guardrails.<AgentClass>의 runtime config에 ID와 버전을 { guardrailId, guardrailVersion }으로 작성해야 합니다.

이미 모델을 설정한 에이전트

new Agent({...}) 호출이 이미 model을 설정한 경우, 제너레이터는 agent.ts를 변경하지 않습니다. 파일 이름과 추가할 줄을 출력합니다. 자체 모델 옵션을 유지하려면 guardrail.ts의 GuardrailedBedrockModel 클래스로 모델을 생성하세요. BedrockModel과 동일한 옵션을 사용합니다. 예를 들어:

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

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

가드레일이 확인하는 내용

가드레일은 모든 모델 호출에서 두 가지를 확인합니다:

사용자의 최신 메시지를 포함하여 에이전트가 모델에 보내는 대화
에이전트가 사용자에게 스트리밍하기 전의 모델 답변

가드레일이 사용자의 메시지를 차단하면 사용자는 blockedInputMessaging 텍스트를 받고 모델은 호출되지 않습니다. Strands는 또한 에이전트의 대화 기록에서 차단된 메시지를 [User input redacted.]로 대체합니다. 답변을 차단하면 사용자는 blockedOutputsMessaging 텍스트를 받습니다. ANONYMIZE 규칙이 일치하면 답변에 값 대신 {EMAIL}과 같은 자리 표시자가 포함됩니다.

가드레일은 도구 정의, 모델이 도구에 전달하는 인수 또는 도구가 반환하는 결과를 확인하지 않습니다. 예를 들어, 도구가 데이터베이스에서 고객의 이메일 주소를 반환하는 경우 가드레일은 모델에서 이를 숨기지 않습니다. TypeScript Agent 가이드의 “Securing your Agent” 섹션에 설명된 대로 도구 결과를 신뢰할 수 없는 것으로 취급하세요.

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

필드는 다음과 같습니다:

blockedInputMessaging: 가드레일이 메시지를 차단할 때 사용자가 받는 응답입니다. 최대 500자입니다.
blockedOutputsMessaging: 가드레일이 모델의 답변을 차단할 때 사용자가 받는 응답입니다. 최대 500자입니다.
deniedTopics: 에이전트가 거부해야 하는 주제입니다. 각 주제에는 name(최대 100자의 문자, 숫자, 공백 및 -_!?. 문자), 주제를 설명하는 최대 1000자의 definition, 그리고 각각 최대 100자의 선택적 examples가 있습니다.
piiEntities: 조치를 취할 개인 데이터 유형입니다. type은 EMAIL, PHONE 또는 US_SOCIAL_SECURITY_NUMBER와 같은 민감한 정보 유형입니다. action은 값을 자리 표시자로 대체하는 ANONYMIZE 또는 전체 메시지나 답변을 차단하는 BLOCK입니다.

주제 자체를 설명하는 주제 definition을 작성하세요. 예를 들어, “Recommendations about which specific stocks to buy”가 “Do not give investment advice”보다 더 잘 작동합니다.

버전에 번호가 매겨지는 이유

guardrail.json을 변경하고 배포할 때마다 인프라는 새로운 번호가 매겨진 가드레일 버전을 생성하고 runtime config에 씁니다. 버전의 설명에는 guardrail.json의 SHA-256 해시가 포함되어 있으므로 파일을 변경하면 설명이 변경되고 새 버전이 이전 버전을 대체합니다. CDK 구성의 경우 해시는 전달하는 모든 가드레일 속성도 포함합니다.

실행 중인 에이전트는 재시작이 필요하지 않습니다. runtime config에서 읽은 내용을 5초 동안 캐시하므로 AppConfig 배포 후 5초 이내에 새 버전을 사용합니다. 이전 버전은 AppConfig 배포 후 삭제됩니다: CloudFormation은 정리 단계에서 삭제하고, Terraform은 에이전트에 가드레일 연결에 표시된 대로 가드레일 모듈을 해당 모듈의 depends_on에 추가하면 배포 모듈 후에 삭제합니다.

에이전트는 DRAFT 버전을 사용하지 않습니다. DRAFT는 항상 최신 규칙을 보유하므로 AWS 콘솔에서 수행한 편집이 배포 없이 실행 중인 에이전트에 도달할 수 있습니다. guardrail.ts는 runtime config의 버전이 버전 번호가 아닌 경우 오류를 발생시킵니다.

에이전트에 가드레일 연결

제너레이터는 ts#agent 제너레이터가 에이전트 배포를 사용자에게 맡기는 것과 같은 방식으로 스택이나 루트 Terraform 모듈을 변경하지 않습니다. 완료되면 에이전트의 이름이 채워진 아래 코드를 출력합니다. 가드레일을 생성하고, runtime-config 항목을 작성하고, 에이전트가 가드레일을 적용할 수 있도록 추가하세요:

CDK
Terraform

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

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

구성은 가드레일의 ID와 버전을 agentcore.guardrails.MyAgent의 runtime config에 쓰고, agent에 가드레일을 적용할 수 있는 권한을 부여합니다. 에이전트 구성은 이미 에이전트가 runtime config를 읽을 수 있도록 허용합니다.

구성은 다음을 노출합니다:

guardrail(CfnGuardrail) 및 version(CfnGuardrailVersion)
guardrailId, guardrailArn 및 guardrailVersion
다른 주체에게 가드레일에 대해 bedrock:ApplyGuardrail을 부여하는 grantApply(grantee)

또한 GuardrailId 및 GuardrailVersion 스택 출력을 추가합니다. props는 agent와 모든 CfnGuardrail 속성입니다. CfnGuardrail 속성은 guardrail.json보다 우선합니다. 예를 들어, 콘텐츠 필터를 추가하세요:

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

에이전트를 배포하는 루트 모듈에 표시된 대로 my_agent_guardrail 모듈을 추가하세요. 기존 my_agent 모듈 블록에 additional_iam_policy_statements 줄을 추가하세요. runtime_config_appconfig_deployment 모듈의 depends_on 목록에 module.my_agent_guardrail을 추가하여 배포에 가드레일의 runtime-config 항목이 포함되고 Terraform이 배포 후에만 이전 가드레일 버전을 삭제하도록 하세요. 루트 모듈이 아직 에이전트를 배포하지 않는 경우 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,
  ]
}

에이전트 모듈이 이미 additional_iam_policy_statements를 설정한 경우 목록을 결합하세요:

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

모듈은 가드레일의 ID와 버전을 agentcore.guardrails.MyAgent의 runtime config에 씁니다. agentcore 네임스페이스는 runtime-config 모듈의 기본 namespaces에 있으므로 추가할 필요가 없습니다. 에이전트 모듈은 이미 에이전트가 runtime config를 읽을 수 있도록 허용합니다.

모듈은 tags 변수를 받고 guardrail_id, guardrail_arn, guardrail_version 및 iam_policy_statements를 출력합니다. 콘텐츠 필터와 같은 다른 가드레일 정책을 추가하려면 모듈의 aws_bedrock_guardrail 리소스를 편집하세요.

모듈은 가드레일 버전에 create_before_destroy를 설정하므로 Terraform은 이전 버전을 삭제하기 전에 새 버전을 생성합니다.

누락된 runtime-config 항목

연결을 잊어버린 경우 runtime config에 에이전트에 대한 항목이 없습니다. 그러면 모델은 Bedrock을 호출하기 전에 오류를 발생시키므로 에이전트는 가드레일 없이 실행되지 않습니다. MyAgent의 경우 오류는 다음과 같습니다:

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.

에이전트는 모든 프로토콜(http, a2a 및 ag-ui)로 시작되며, 각 요청은 이 오류로 실패합니다.

로컬 개발

<agent>-dev 대상은 LOCAL_DEV=true를 설정합니다. LOCAL_DEV가 true이고 RUNTIME_CONFIG_APP_ID 환경 변수가 설정되지 않은 경우 guardrail.ts는 runtime config를 읽지 않습니다. 한 번 경고를 출력하고 에이전트는 가드레일 없이 실행됩니다:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

로컬에서 규칙을 테스트하려면 먼저 가드레일을 배포하세요. 그런 다음 RuntimeConfigApplicationId 스택 출력(CDK) 또는 module.runtime_config_appconfig.application_id(Terraform)에서 배포된 runtime-config 애플리케이션의 ID로 RUNTIME_CONFIG_APP_ID를 설정하세요. 셸에는 AppConfig를 읽고 가드레일을 적용할 수 있는 AWS 자격 증명도 필요합니다:

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

그러면 에이전트는 자체 항목만 읽으므로 여러 보호된 에이전트가 동일한 애플리케이션에 대해 로컬로 실행될 수 있습니다. 에이전트가 runtime config를 읽을 수 없거나 항목이 누락된 경우 한 번 경고를 출력하고 가드레일 없이 실행됩니다.

<agent>-serve 대상은 LOCAL_DEV를 설정하지 않으므로 RUNTIME_CONFIG_APP_ID와 배포된 항목이 필요합니다. 그렇지 않으면 위에서 설명한 대로 각 요청이 실패합니다. <agent>-chat 대상은 실행 중인 에이전트에 연결하며 runtime config 자체가 필요하지 않습니다.

비용 및 지연 시간

Amazon Bedrock은 입력과 답변 모두에서 텍스트를 평가하는 각 가드레일 정책에 대해 요금을 부과합니다. Amazon Bedrock 요금을 참조하세요.

가드레일이 에이전트가 사용자에게 스트리밍하기 전에 답변을 확인하기 때문에 각 모델 호출도 더 오래 걸립니다.

제한 사항

이 제너레이터는 ts#agent로 생성된 에이전트를 지원합니다. AgentCore Harness는 지원하지 않습니다.
guardrail.json은 거부된 주제와 PII 엔터티만 보유합니다. 콘텐츠 필터 및 단어 필터와 같은 다른 정책은 구성의 props(CDK)를 사용하거나 모듈을 편집(Terraform)하여 추가하세요.
가드레일은 가드레일이 확인하는 내용에 설명된 대로 도구 결과를 확인하지 않습니다.