# AgentCore에서 정책 시작하기
이 자습서에서는 AgentCore CLI를 사용하여 AgentCore에서 정책을 설정하고 이를 Amazon Bedrock AgentCore Gateway와 통합하는 방법을 알아봅니다. 환급 금액에 대한 비즈니스 규칙을 적용하는 Cedar 정책을 사용하여 환급 처리 도구를 생성합니다.
**Topics**
+ [사전 조건](#policy-getting-started-prerequisites)
+ [1단계: 설정 및 설치](#policy-getting-started-setup)
+ [2단계: 정책 엔진이 있는 게이트웨이 추가](#policy-getting-started-create-script)
+ [3단계: 배포](#policy-getting-started-run-setup)
+ [4단계: 정책 테스트](#policy-getting-started-test)
+ [빌드한 내용](#policy-getting-started-results)
+ [문제 해결](#policy-getting-started-troubleshooting)
+ [정리](#policy-getting-started-cleanup)
## 사전 조건
시작하기 전에 다음이 있는지 확인합니다.
+ ** AWS 자격 증명이 구성된 계정**입니다. 자격 증명을 구성하려면 CLI 시작하기의 단계에 따라 AWS 명령줄 인터페이스를 설치하고 사용할 수 있습니다. [AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
+ **Node.js 18 이상** 설치됨
+ 역할, Lambda 함수, 정책 엔진을 생성하고 Amazon Bedrock AgentCore를 사용하기 위한 **IAM 권한**
+ 환불 요청을 처리하는 **Lambda 함수입니다**. 기존 함수를 사용하거나이 자습서를 위한 함수를 생성할 수 있습니다. 2단계에서 사용할 함수 ARN을 기록해 둡니다.
## 1단계: 설정 및 설치
AgentCore CLI를 설치합니다.
```
npm install -g @aws/agentcore
```
새 AgentCore 프로젝트 생성:
**Example**
1.
```
agentcore create --name PolicyDemo --defaults
cd PolicyDemo
```
`--defaults` 플래그는 기본 Python Strands 에이전트를 사용하여 프로젝트를 생성합니다. **cd** 명령은 후속 명령을 실행해야 하는 프로젝트 디렉터리로 이동합니다.
1. 플래그 `agentcore create` 없이를 실행하여 대화형 마법사를 사용할 수도 있습니다. 마법사는 프로젝트 이름, 에이전트 프레임워크, 모델 공급자 및 기타 옵션을 선택하는 방법을 안내합니다. 프로젝트를 생성한 후 **cd PolicyDemo**를 사용하여 프로젝트 디렉터리로 변경합니다.
## 2단계: 정책 엔진이 있는 게이트웨이 추가
AgentCore CLI를 사용하여 게이트웨이, Lambda 함수 대상 및 정책 엔진을 프로젝트에 추가합니다.
**게이트웨이 추가**
인바운드 권한 부여 없이 게이트웨이를 생성하고(이 자습서에서는 간소화를 위해) 에이전트를 여기에 연결합니다.
**Example**
1.
```
agentcore add gateway --name PolicyGateway --authorizer-type NONE --runtimes PolicyDemo
```
1. 를 실행`agentcore`하여 TUI를 연 다음 **추가**를 선택하고 **게이트웨이**를 선택합니다.
1. 게이트웨이 이름을 입력합니다.
1. 권한 부여자 유형을 선택합니다. 이 자습서에서는 **없음을** 선택합니다.
1. 고급 옵션을 구성하거나 기본값을 수락합니다.
1. 구성을 검토하고 **Enter** 키를 눌러 확인합니다.
**환급 도구를 사용하여 Lambda 함수 대상 추가**
환급 처리 도구를 정의하는 도구 스키마를 사용하여 Lambda 함수를 게이트웨이 대상으로 등록합니다.
**Example**
1.
```
agentcore add gateway-target --name RefundTarget --type lambda-function-arn \
--lambda-arn ++++ \
--tool-schema-file refund_tools.json \
--gateway PolicyGateway
```
를 Lambda 함수의 ARN``으로 바꿉니다. `refund_tools.json` 파일은 환급 도구의 도구 스키마를 정의합니다.
1. 를 실행`agentcore`하여 TUI를 연 다음 **추가**를 선택하고 **게이트웨이 대상**을 선택합니다.
1. 대상 이름을 입력합니다.
1. **Lambda 함수**를 대상 유형으로 선택합니다.
1. Lambda ARN 및 도구 스키마 파일 경로를 입력한 다음 확인합니다.
**정책 엔진 추가**
정책 엔진을 생성하고 ENFORCE 모드에서 게이트웨이에 연결합니다.
**Example**
1.
```
agentcore add policy-engine --name RefundPolicyEngine \
--attach-to-gateways PolicyGateway \
--attach-mode ENFORCE
```
1. 를 실행`agentcore`하여 TUI를 연 다음 **추가**를 선택하고 **정책 엔진**을 선택합니다.
1. 정책 엔진 이름을 입력합니다.
1. 정책 엔진을 연결할 게이트웨이를 선택합니다.
1. 적용 모드를 선택합니다. **ENFORCE**를 선택합니다.
**Cedar 정책 생성**
Cedar 정책 파일을 직접 제공합니다.
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--source refund_policy.cedar
```
**참고**
`resource` 필드의 특정 게이트웨이 ARNs 참조하는 Cedar 정책(아래 예제 참조)에는 2단계 배포가 필요합니다. 먼저 정책을 사용하지 않고 배포하여 게이트웨이를 생성한 다음, **agentcore 상태**에서 게이트웨이 ARN을 검색하고, Cedar 파일을 업데이트하고, 다시 배포하기 전에 정책을 추가합니다. 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 프로젝트에서 여러 리소스를 구성합니다. 다음은 각 구성 요소에 대한 자세한 설명입니다.
**Topics**
+ [게이트웨이 생성](#policy-create-gateway)
+ [Lambda 대상 추가](#policy-add-lambda-target)
+ [정책 엔진 생성](#policy-create-policy-engine)
+ [Cedar 정책 생성](#policy-create-cedar-policy)
+ [게이트웨이에 정책 연결](#policy-attach-to-gateway)
#### 게이트웨이 생성
**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::"")
when {
context.input.amount < 1000
};
```
정책은 다음을 사용합니다.
+ `permit` - 작업 허용(Cedar는 작업 `forbid` 거부도 지원)
+ `principal` - 요청하는 엔터티
+ `action` - 호출되는 특정 도구(RefundTarget\_\_\_process\_refund)
+ `resource` - 정책이 적용되는 게이트웨이 인스턴스
+ `when` 조건 - 추가 요구 사항(금액은 < $1000여야 함)
#### 게이트웨이에 정책 연결
**agentcore add policy-engine** 명령의 `--attach-to-gateways` 및 `--attach-mode ENFORCE` 플래그는 ENFORCE 모드에서 정책 엔진을 게이트웨이에 연결합니다. 이 모드에서는 다음을 수행합니다.
+ 모든 도구 호출을 가로채고 모든 정책에 대해 평가합니다.
+ 기본적으로 명시적으로 허용되지 않는 한 모든 작업이 거부됩니다.
+ 일치하는 `forbid` 정책이 있으면 액세스가 거부됩니다(forbid-wins 의미 체계).
+ 모니터링 및 규정 준수를 위해 정책 결정이 CloudWatch에 기록됩니다.
이렇게 하면 게이트웨이를 통한 모든 에이전트 작업이 보안 정책에 의해 관리됩니다.
## 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 ++++ \
-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 ++++ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'
```
**참고**
를 **agentcore 상태의** 출력에 표시된 게이트웨이 URL``로 바꿉니다.
## 빌드한 내용
이 자습서를 통해 다음을 생성했습니다.
+ **MCP 서버(게이트웨이)** - 도구를 위한 관리형 엔드포인트
+ **Lambda 대상** - 게이트웨이에 등록된 환급 처리 도구
+ **정책 엔진** - Cedar 기반 정책 평가 시스템
+ **Cedar 정책** - 1,000 USD 미만의 환급을 허용하는 거버넌스 규칙
## 문제 해결
설정 또는 테스트 중에 문제가 발생하면 다음과 같은 일반적인 문제 및 해결 방법을 참조하세요.
| 문제 | Solution |
| --- | --- |
| “AccessDeniedException” | bedrock-agentcore에 대한 IAM 권한 확인:\* |
| 게이트웨이가 응답하지 않음 | DNS 전파를 위해 배포 후 30\~60초 대기 |
| 배포 실패 | **agentcore 상태를** 실행하여 리소스 상태 확인 및 오류 메시지 검토 |
| 정책이 적용되지 않음 | **agentcore 상태를** 실행하여 정책 엔진이 ENFORCE 모드에서 연결되어 있는지 확인 |
| 배포 중 Cedar 검증 오류 | Cedar 정책은 특정 리소스 ARNs 사용해야 합니다. 와일드카드 리소스(예: `permit(principal, action, resource);` )는 거부됩니다. Cedar 정책의 `resource` 필드에서 **agentcore 상태의** 게이트웨이 ARN을 사용합니다. |
| 도구 호출이 예기치 않게 거부됨 | 정책 엔진이 적용 중이고 Cedar 정책이 요청을 거부했습니다. 정책의 `action` 및 `resource` 필드가 수행 중인 도구 호출과 일치하는지 확인합니다. |
| 정책 검증 오류와 함께 배포 실패 | 기본 검증 모드는 스키마 확인과 의미 체계 검증을 모두 `FAIL_ON_ANY_FINDINGS` 실행하여가 결과를 생성하는 경우 정책을 거부합니다. 의미 체계 검증이 필요하지 않은 경우 스키마 검사만 실행`IGNORE_ALL_FINDINGS`하도록 검증 모드를 로 설정할 수 있습니다. 프로덕션의 경우 스키마 검사와 의미 체계 검증을 모두 통과하도록 Cedar 정책을 수정합니다. |
## 정리
이 자습서에서 생성된 리소스를 제거하려면 게이트웨이와 정책 엔진을 모두 제거한 다음 재배포합니다.
```
agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy
```
게이트웨이를 제거해도 연결된 정책 엔진은 자동으로 제거되지 않습니다. 를 사용하여 정책 엔진을 별도로 제거해야 합니다`agentcore remove policy-engine`.