> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 정책 엔진

> 에이전트별 지출 한도, 주소 화이트리스트, 속도 제어, 사람 승인 라우팅을 구성합니다.

## 개요

정책 엔진은 MPC 서명 레이어에 도달하기 전에 모든 거래를 평가합니다. 정책은 에이전트별로 적용되며 SDK 또는 REST API를 통해 언제든지 업데이트할 수 있습니다. 첫 번째 정책 위반이 즉시 거래를 중단합니다.

## 정책 유형

### 지출 한도

에이전트의 지출 규모를 제어합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  maxTransactionAmount: "500",   // Max per single transaction (USDC)
  dailyLimit: "5000",            // Rolling 24-hour total
  monthlyLimit: "50000",         // Rolling 30-day total
});
```

| 규칙                     | 설명            | 기간    |
| ---------------------- | ------------- | ----- |
| `maxTransactionAmount` | 단일 결제의 최대 금액  | 거래별   |
| `dailyLimit`           | 24시간 누적 최대 금액 | 롤링 기간 |
| `monthlyLimit`         | 30일 누적 최대 금액  | 롤링 기간 |

### 주소 제어

에이전트가 전송할 수 있는 주소를 제한합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  // Whitelist mode: only send to these addresses
  allowedAddresses: [
    "0xTrustedVendor1",
    "0xTrustedVendor2",
    "0xTrustedExchange",
  ],

  // Blacklist mode: block specific addresses
  blockedAddresses: [
    "0xKnownScam",
  ],
});
```

<Note>
  `allowedAddresses`가 설정되면 해당 주소만 허용됩니다. `allowedAddresses`와 `blockedAddresses`가 모두 설정된 경우 `allowedAddresses`가 우선합니다.
</Note>

### 토큰 제어

에이전트가 거래할 수 있는 토큰을 제한합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  allowedTokens: ["USDC", "USDT"],  // Only stablecoins
});
```

### 속도 제어

폭주 에이전트를 방지하기 위해 거래 빈도를 제한합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  velocityLimit: {
    maxCount: 100,        // Max number of transactions
    windowSeconds: 3600,  // Per hour
  },
});
```

### 시간 기반 제어

거래가 발생할 수 있는 시간을 제한합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  schedule: {
    timezone: "America/New_York",
    allowedHours: { start: 9, end: 17 },  // 9 AM - 5 PM
    allowedDays: [1, 2, 3, 4, 5],         // Monday - Friday
  },
});
```

### 사람 승인

고액 거래를 사람 검토로 라우팅합니다:

```typescript theme={null}
await aw.policies.update("agent_abc123", {
  requireHumanApproval: true,
  humanApprovalThreshold: "1000",  // Transactions above $1000
  approvalTimeout: 3600,           // 1 hour to approve before auto-reject
  approvers: [
    "user_admin1@company.com",
    "user_admin2@company.com",
  ],
});
```

<Info>
  사람 승인은 Growth 및 Enterprise 플랜에서 사용할 수 있습니다. 거래가 승인을 요구하면 웹훅 이벤트가 전송되고 거래는 `pending_approval` 상태가 됩니다.
</Info>

## 정책 평가 순서

정책은 이 순서대로 확인됩니다. 첫 번째 실패가 거래를 중단합니다:

<Steps>
  <Step title="에이전트 상태">
    에이전트가 활성 상태인가 (동결되지 않았는가)?
  </Step>

  <Step title="토큰 확인">
    이 토큰이 `allowedTokens` 목록에 있는가?
  </Step>

  <Step title="주소 확인">
    수신자가 `allowedAddresses`에 있고 `blockedAddresses`에 없는가?
  </Step>

  <Step title="금액 확인">
    `maxTransactionAmount`를 초과하는가?
  </Step>

  <Step title="일일 한도">
    이 거래로 일일 누적 한도를 초과하는가?
  </Step>

  <Step title="월별 한도">
    이 거래로 월별 누적 한도를 초과하는가?
  </Step>

  <Step title="속도 확인">
    에이전트가 거래 속도(`velocityLimit`)를 초과했는가?
  </Step>

  <Step title="일정 확인">
    허용된 시간 및 요일 내에 있는가?
  </Step>

  <Step title="사람 승인">
    임계값에 따라 사람 검토가 필요한가?
  </Step>

  <Step title="인프라 안전망">
    Paratro가 적용한 하드 리밋 (재정의 불가).
  </Step>
</Steps>

## 정책 위반 이벤트

정책이 거래를 차단하면 API는 상세한 오류를 반환합니다:

```json theme={null}
{
  "code": "policy_violation",
  "type": "invalid_request_error",
  "message": "Transaction would exceed daily limit"
}
```

웹훅 이벤트로도 위반 사항을 수신할 수 있습니다:

```typescript theme={null}
await aw.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: ["policy.violated"],
});
```

## 정책 템플릿

일반적인 구성을 위한 템플릿을 사용합니다:

```typescript theme={null}
// Conservative: tight limits for testing
await aw.policies.applyTemplate("agent_abc123", "conservative");

// Standard: balanced limits for production
await aw.policies.applyTemplate("agent_abc123", "standard");

// Custom: define and reuse your own templates
await aw.policies.createTemplate("my-template", {
  maxTransactionAmount: "200",
  dailyLimit: "2000",
  allowedTokens: ["USDC"],
  velocityLimit: { maxCount: 50, windowSeconds: 3600 },
});

await aw.policies.applyTemplate("agent_abc123", "my-template");
```

## 모범 사례

<Tip>
  제한적으로 시작하고 점진적으로 확장하세요. 엄격한 한도로 시작하여 에이전트의 동작에 대한 확신이 생기면 늘려가세요.
</Tip>

* **allowedAddresses 사용** — 금액 한도에만 의존하지 말고 신뢰할 수 있는 주소를 화이트리스트에 추가하세요.
* **고액에 대해 사람 승인 활성화** — 사람이 거래를 검토하는 임계값을 설정하세요.
* **정책 위반 모니터링** — 웹훅을 통해 위반 사항을 추적하여 잘못 구성된 에이전트를 식별하세요.
* **속도 제한 사용** — 에이전트가 반복적으로 거래를 시도하는 폭주 루프를 방지하세요.
* **주간 정책 검토** — 에이전트 동작이 진화함에 따라 정책을 업데이트하세요.