AgentCore에서 정책 시작하기

이 자습서에서는 AgentCore CLI를 사용하여 AgentCore에서 정책을 설정하고 이를 Amazon Bedrock AgentCore Gateway와 통합하는 방법을 알아봅니다. 환급 금액에 대한 비즈니스 규칙을 적용하는 Cedar 정책을 사용하여 환급 처리 도구를 생성합니다.

사전 조건

시작하기 전에 다음이 있는지 확인합니다.

1단계: 설정 및 설치

AgentCore CLI를 설치합니다.

npm install -g @aws/agentcore

새 AgentCore 프로젝트 생성:

2단계: 정책 엔진이 있는 게이트웨이 추가

AgentCore CLI를 사용하여 게이트웨이, Lambda 함수 대상 및 정책 엔진을 프로젝트에 추가합니다.

게이트웨이 추가

인바운드 권한 부여 없이 게이트웨이를 생성하고(이 자습서에서는 간소화를 위해) 에이전트를 여기에 연결합니다.

환급 도구를 사용하여 Lambda 함수 대상 추가

환급 처리 도구를 정의하는 도구 스키마를 사용하여 Lambda 함수를 게이트웨이 대상으로 등록합니다.

정책 엔진 추가

정책 엔진을 생성하고 ENFORCE 모드에서 게이트웨이에 연결합니다.

Cedar 정책 생성

Cedar 정책 파일을 직접 제공합니다.

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --source refund_policy.cedar

또는 3단계에서 리소스를 배포한 후 자연어 설명에서 Cedar 정책을 생성할 수 있습니다.

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --generate "Only allow refunds under 1000 dollars" \
  --gateway PolicyGateway

--generate 플래그는 자연어를 Cedar로 변환하기 위해 게이트웨이 ARN이 필요한 AWS API를 호출하기 때문에 게이트웨이를 먼저 배포해야 합니다. 이 접근 방식은 게이트웨이 ARNs 자동으로 해석하므로 정책을 생성하는 가장 간단한 경로입니다.

설정 이해

위의 CLI 명령은 AgentCore 프로젝트에서 여러 리소스를 구성합니다. 다음은 각 구성 요소에 대한 자세한 설명입니다.

게이트웨이 생성

agentcore 게이트웨이 추가 명령은 MCP 서버 엔드포인트 역할을 하는 게이트웨이를 생성합니다. 를 설정하면이 자습서에서 간소화를 위해 인바운드 권한이 --authorizer-type NONE 비활성화됩니다. 프로덕션 환경에서는 IAM 또는 JWT 권한 부여를 사용하여 게이트웨이를 보호합니다.

Lambda 대상 추가

agentcore add gateway-target 명령은 Lambda 함수를 게이트웨이의 대상으로 등록합니다. 도구 스키마 파일은 에이전트가 환불 금액과 같이 함수에 전달할 수 있는 입력을 정의합니다.

정책 엔진 생성

agentcore add policy-engine 명령은 에이전트 도구 호출을 평가하고 승인하는 Cedar 정책 모음인 정책 엔진을 생성합니다. 정책 엔진은 게이트웨이 경계의 모든 요청을 가로채고 정의된 정책에 따라 각 작업을 허용할지 거부할지를 결정합니다. 이렇게 하면 에이전트의 코드 외부에서 결정적인 권한 부여가 제공되므로 에이전트가 구현되는 방식에 관계없이 일관된 보안이 적용됩니다.

Cedar 정책 생성

Cedar는 권한 부여 정책을 작성하기 AWS 위해에서 개발한 오픈 소스 정책 언어입니다. agentcore 정책 추가 명령은 게이트웨이를 통해 도구 호출을 관리하는 Cedar 정책을 생성합니다. 를 사용하여 자연어 설명에서 정책을 생성하거나 --generate를 사용하여 Cedar 정책 파일을 직접 제공할 수 있습니다--source.

다음은 1,000 USD 미만의 환급을 허용하는 Cedar 정책의 예입니다.

permit(principal,
  action == AgentCore::Action::"RefundTarget___process_refund",
  resource == AgentCore::Gateway::"<gateway-arn>")
when {
  context.input.amount < 1000
};

정책은 다음을 사용합니다.

게이트웨이에 정책 연결

agentcore add policy-engine 명령의 --attach-to-gateways 및 --attach-mode ENFORCE 플래그는 ENFORCE 모드에서 정책 엔진을 게이트웨이에 연결합니다. 이 모드에서는 다음을 수행합니다.

이렇게 하면 게이트웨이를 통한 모든 에이전트 작업이 보안 정책에 의해 관리됩니다.

3단계: 배포

모든 리소스를 AWS다음에 배포합니다.

agentcore deploy

AgentCore CLI는 게이트웨이를 생성하고, Lambda 대상을 등록하고, 정책 엔진을 프로비저닝하고, Cedar 정책을 연결합니다. 이 프로세스는 약 2~3분이 걸립니다.

배포가 완료되면 리소스의 상태를 확인할 수 있습니다.

agentcore status

4단계: 정책 테스트

게이트웨이에 요청을 전송하여 정책을 테스트합니다. 게이트웨이는 --authorizer-type NONE를 사용하기 때문에 curl을 사용하여 직접 요청을 보낼 수 있습니다.

테스트 1: 500 USD 환불(허용되어야 함)

환불 금액 500 USD가 1,000 USD 한도 미만이므로 정책 엔진이 요청을 허용합니다.

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":500}}}'

테스트 2: 2,000 USD 환불(거부해야 함)

환불 금액 2,000 USD가 1,000 USD 한도를 초과하므로 정책 엔진은 요청을 거부합니다.

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'

빌드한 내용

이 자습서를 통해 다음을 생성했습니다.

문제 해결

설정 또는 테스트 중에 문제가 발생하면 다음과 같은 일반적인 문제 및 해결 방법을 참조하세요.

정리

이 자습서에서 생성된 리소스를 제거하려면 게이트웨이와 정책 엔진을 모두 제거한 다음 재배포합니다.

agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy

게이트웨이를 제거해도 연결된 정책 엔진은 자동으로 제거되지 않습니다. 를 사용하여 정책 엔진을 별도로 제거해야 합니다agentcore remove policy-engine.