기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AgentCore에서 정책 시작하기

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

사전 조건

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

AgentCore CLI는 배포 중에 CDK 부트스트랩 스택을 확인합니다. 부트스트랩이 필요한 경우 대화형 배포에서 확인을 요청합니다. agentcore deploy --yes를 사용하여 자동으로 권한을 부여합니다.

1단계: 설정 및 설치

AgentCore CLI를 설치합니다.

npm install -g @aws/agentcore

새 AgentCore 프로젝트 생성:

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

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

게이트웨이 추가

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

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

환급 처리 도구를 정의하는 도구 스키마를 사용하여 Lambda 함수를 게이트웨이 대상으로 등록합니다. 프로젝트 디렉터리에 다음 내용이 포함된 refund_tools.json 파일을 생성합니다.

[
  {
    "name": "process_refund",
    "description": "Process a customer refund request for a given dollar amount",
    "inputSchema": {
      "type": "object",
      "description": "Input for processing a refund",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "The refund amount in dollars"
        }
      },
      "required": ["amount"]
    }
  }
]

정책 엔진 추가

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

Cedar 정책 생성

Cedar 정책 파일을 직접 제공합니다. Cedar는 정책 설명에서 와일드카드 리소스를 허용하지 않습니다. 이를 위해서는 2단계 배포가 필요합니다. 먼저 게이트웨이를 생성하는 정책 없이 배포한 다음 게이트웨이 ARN을 검색합니다. 그런 다음 정책을 추가하고 다시 배포합니다.

또는 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.

다음은 USD $1000 미만의 환급을 허용하는 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 대상을 등록하며 정책 엔진을 프로비저닝합니다. ARN 기반 Cedar 정책 파일을 제공한 경우이 배포 후 추가하고 agentcore 배포를 다시 실행하여 연결합니다. 이 프로세스는 배포당 약 2~3분이 걸립니다.

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

agentcore status

4단계: 정책 테스트

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

agentcore 상태의 출력에 표시된 게이트웨이 URL은 기본 엔드포인트입니다. MCP 요청은 해당 엔드포인트의 /mcp 경로로 이동하므로 요청을 보내기 전에 URL에 /mcp를 추가합니다.

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

USD $500의 환불 금액이 USD $1000 한도 미만이므로 정책 엔진은 요청을 허용합니다.

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

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

USD $2000의 환불 금액이 USD $1000 한도를 초과하므로 정책 엔진은 요청을 거부합니다.

curl -X POST ++<GATEWAY_URL>++/mcp \
  -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.