개요
Atlas Agent Engine 정책 엔진을 사용하면 조직 관리자가 에이전트 실행을 런타임에 제어할 수 있습니다. 관리자는 조직 범위, 프로젝트 범위 또는 둘 다 내에서 정책을 작성합니다. 컨트롤 플레인은 프로젝트 에 적용 정책을 하나의 효과적인 구성으로 병합하고, 오케스트레이션 엔진(OE)은 실행할 때마다 해당 구성을 적용합니다.
정책은 호출하는 도구 및 모델, 한 번의 실행 으로 수행할 수 있는 작업량 등 에이전트 수행하는 조치를 제어합니다. 정책은 두 가지 범주로 나뉩니다.
허용 목록은 에이전트 호출할 수 있는 도구와 모델을 제한합니다.
실행 예산은 도구 호출 수, LLM(Large 언어 Model) 호출 수, 실행 기간 등 단일실행으로 소비할 수 있는 리소스를 제한합니다.
에이전트 통과하는 콘텐츠를 제어하려면 콘텐츠 가드레일 사용을 참조하세요.
정책 유형
각 정책 유형에는 정책 값의 형태를 설명하는 종류가 있습니다. 종류는 정책 엔진이 조직 과 프로젝트 정책을 병합하는 방법을 결정합니다. 다음과 같은 정책 유형을 사용할 수 있습니다.
정책 유형 | Kind | 설명 |
|---|---|---|
| 허용 목록 | 에이전트 호출할 수 있는 도구 설정하다 입니다. OE는 각 도구를 호출하기 전에 이 정책을 평가합니다. 에이전트 목록에 없는 도구를 호출하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
| 허용 목록 | 에이전트 호출할 수 있는 모델 설정하다 입니다. OE는 각 LLM 호출 전에 이 정책을 평가합니다. 에이전트 목록에 없는 모델을 호출하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
| Numeric cap | 에이전트 한 번의 실행으로 수행할 수 있는 최대 도구 호출 수입니다. 실행이 한도에 도달한 후 에이전트 도구 호출을 시도하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
| Numeric cap | 에이전트 한 번 실행할 수 있는 최대 LLM 호출 수입니다. 실행이 한도에 도달한 후 에이전트 LLM 호출을 시도하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
| Numeric cap | 단일 실행의 최대 경과 시간(밀리초)입니다. OE는 각 도구 호출과 LLM 호출 전에 경과 시간을 확인합니다. 실행이 제한에 도달하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. OE는 이미 진행 중인 통화를 중지하지 않습니다. |
| Numeric cap | 단일 실행으로 사용할 수 있는 최대 LLM 토큰 수입니다. 실행이 한도에 도달한 후 에이전트 LLM 호출을 시도하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
| Numeric cap | 한 세션이 해당 세션의 모든 실행에서 사용할 수 있는 최대 LLM 토큰 수입니다. 세션이 한도에 도달한 후 에이전트 LLM 호출을 시도하면 OE는 실행을 중지하고 정책 거부 오류를 반환합니다. |
정책 거부 오류에 대해 학습 시행을 참조하세요.
토큰 합계는 LLM 호출 이전이 아닌 각 모델 응답 이후에 누적됩니다. 자세한 내용은 제한 사항을 참조하세요.
에이전트 하위 에이전트 에게 작업 위임하면 하위 에이전트는 상위 에이전트의 루트 세션을 상속하므로 두 에이전트는 모두 동일한 세션에서 실행 . 그들의 결합된 토큰은 에이전트 당 별도의 총계가 아닌 하나의 총 MAX_TOKENS_PER_SESSION 에 계산됩니다. 에이전트 간 위임에 대해 자세히 학습 에이전트 간 통신 사용을 참조하세요.
도구 및 카탈로그 일치
AUTHORIZED_TOOLS 허용 목록 항목은 도구 이름 또는 도구를 게시하는 카탈로그의 식별자(예: stripe/payments)와 일치합니다. 카탈로그 식별자는 나중에 카탈로그에서 추가하는 도구를 포함하여 카탈로그가 게시하는 모든 도구를 허용 목록에 추가합니다.
사용자 지정 도구를 포함하여 카탈로그 식별자가 없는 도구는 도구 이름으로만 일치합니다. 이러한 도구 중 하나를 허용하려면 해당 도구의 이름을 허용 목록에 추가하세요.
정책 범위 및 상속
조직 범위 또는 프로젝트 범위 내에서 정책을 작성할 수 있습니다. 조직 정책은 조직 의 모든 프로젝트 에 적용됩니다. 모든 프로젝트 정책은 최소한 동일한 종류의 조직 정책만큼 제한적이어야 합니다. 두 범위가 동일한 정책 유형을 정의하면 정책 엔진은 이를 프로젝트 에 대한 하나의 유효한 값으로 병합합니다.
병합 규칙은 정책 종류에 따라 다릅니다. 다음 표에는 각 정책 종류와 해당 병합 규칙이 나열되어 있습니다.
정책 종류 | 병합 규칙 | 프로젝트 제약 조건 |
|---|---|---|
허용 목록 | 유효 값은 조직 허용 목록과 프로젝트 허용 목록의 교집합입니다. | 프로젝트 조직 허용 목록에서 생략한 값을 추가할 수 없습니다. |
Numeric cap | 유효 값은 조직 한도와 프로젝트 한도 중 더 낮은 값입니다. | 프로젝트 조직 한도보다 높게 한도를 설정하다 수 없습니다. |
같은 종류의 조직 정책보다 덜 제한적인 프로젝트 정책을 저장하면 Atlas Agent Engine이 요청 거부합니다. 프로젝트 의 한도를 높이거나 허용 목록을 늘리려면 조직 관리자가 먼저 조직 정책을 변경해야 합니다.
적용
OE는 각 실행 중 특정 체크포인트에서 효과적인 정책을 평가합니다.
체크포인트 | 정책 평가 |
|---|---|
사전 도구 호출 |
|
사전 LLM 호출 |
|
정책 검사가 실패하면 OE는 실행을 중지하고 호출자에게 정책 거부 오류를 반환합니다. 오류에는 policy_denied의 error_code와 거부 이유를 식별하는 Policy denied: <reason> 형식의 메시지가 포함됩니다.
참고
특정 유형의 정책이 실행에 적용되지 않는 경우 OE는 해당 조치 제한하지 않습니다. 유효한 정책이 없는 프로젝트 정책 제한 없이 실행됩니다.
정책 전파
정책을 생성, 업데이트 또는 삭제 하면 Atlas Agent Engine이 약 1분 이내에 변경 사항을 적용합니다. Atlas Agent Engine은 먼저 영향을 받는 각 프로젝트 에 대해 유효한 구성을 다시 빌드한 다음, 해당 구성을 프로젝트의 에이전트를 실행하는 OE에 전달합니다.
각 실행은 시작될 때 유효한 정책의 스냅샷 생성하고 해당 스냅샷 전체 수명 동안 사용합니다. 정책 변경 사항은 변경 사항이 전파된 후에 시작되는 실행에만 적용 . 정책 변경은 진행 중인 실행에 영향을 주지 않습니다.
Atlas Agent 엔진이 변경 사항을 전달할 수 없는 경우 OE는 마지막으로 수신한 구성을 계속 시행하다 . 변경 사항을 받지 못한 프로젝트를 확인하려면 조직 정책 롤아웃 확인을 참조하세요.
정책 생성 및 편집
플랫폼 UI 또는 REST API 에서 정책을 만들고 편집할 수 있습니다.
프로젝트 정책을 관리 하려면 Manage > 프로젝트 의 Policies . 조직 정책을 관리 하려면 조직 설정에서 Policies로 이동하세요. 어느 페이지에서든 각 정책 유형에 대한 정책을 생성하고, 읽고, 업데이트, 삭제 수 있습니다. 프로젝트 Policies 페이지에서 프로젝트 정책을 활성화 하거나 비활성화할 수 있습니다. 플랫폼 UI 조직 정책 활성화 또는 비활성화를 지원 하지 않습니다.
참고
고객 대면 REST API 정책 작업을 노출합니다. 요청에는 작업에 필요한 역할 가진 사용자의 베어러 인증 필요합니다. Atlas Agent Engine의 사용자 역할에 대해 자세히 학습 조직, 프로젝트, 작업 공간 관리 및 조직 보기를 참조하세요.
다음 표에는 사용 가능한 프로젝트 엔드포인트가 나열되어 있습니다.
메서드 | 엔드포인트 | 필수 역할 | 참조 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
다음 표에는 사용 가능한 조직 엔드포인트가 나열되어 있습니다.
메서드 | 엔드포인트 | 필수 역할 | 참조 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
조직 허용 목록 미리 보기
허용 목록은 교차로 병합되므로 조직 허용 목록에서 값을 제거하면 프로젝트 에 허용된 값이 없게 될 수 있습니다. 조직 정책에 대한 변경 사항을 저장하기 전에 ORG_OWNER 역할 사용하여 다음 엔드포인트를 호출합니다.
POST /api/v1/organizations/{orgId}/policies/preview
API 응답은 유효 허용 목록이 비게 되는 각 프로젝트 이름을 지정하고 프로젝트 현재 시행 중인 허용 목록을 표시합니다. 자세한 학습 은 영향을 받는 프로젝트 미리 보기를 참조하세요.
정책 활성화 및 비활성화
Atlas Agent 엔진은 효과적인 구성을 구축할 때 비활성화된 정책을 건너뜁니다. 조직 과 프로젝트 정책 모두 enabled 플래그가 있습니다. 정책을 활성화 하거나 비활성화하려면 정책 범위에 대해 PUT API 엔드포인트를 호출하고 enabled 플래그를 설정하다 . 플랫폼 UI 에서 프로젝트 정책을 활성화 하거나 비활성화할 수도 있습니다. 자세히 학습 정책 생성 및 편집을 참조하세요.
정책을 비활성화하면 Atlas Agent 엔진은 정책의 구성 및 기록을 보존합니다. 정책을 다시 활성화하면 Atlas Agent 엔진이 동일한 구성을 복원합니다.
유효 정책 보기
유효 보기는 조직 및 프로젝트 범위가 프로젝트 에 대해 어떻게 해결되는지 보여줍니다. 유효 뷰를 조회 하려면 프로젝트 읽기 역할 과 함께 다음 프로젝트 엔드포인트를 사용합니다.
GET /api/v1/projects/{projectId}/policies/effective
API 응답에는 모든 정책 유형, OE가 시행하는 병합된 유효 값, 각 범위가 정의하는 값, 시행 중인 범위가 나열됩니다. Atlas Agent Engine이 사용자를 대신하여 조직 값을 읽으므로, 조직 역할 보유하지 않고도 상속된 기준을 볼 수 있습니다. 자세한 학습 은 효과적인 정책 나열을 참조하세요.
조직 정책 롤아웃 확인
Atlas Agent Engine에서 프로젝트는 함께 정책 변경을 받는 것이 아니라 한 번에 하나씩 정책 변경을 받습니다. 조직 정책 롤아웃이 진행되는 동안 일부 프로젝트에서는 새 정책이 시행하다 다른 프로젝트에서는 여전히 이전 정책이 시행하다 . 조직 정책 롤아웃의 진행 상황을 보려면 ORG_OWNER 또는 ORG_READ_ONLY 역할 있는 다음 엔드포인트를 사용하세요.
GET /api/v1/organizations/{orgId}/policies/rollout
API 응답은 지연된 각 프로젝트, 프로젝트 유효 구성을 재구축하거나 수신하지 않은 이유, Atlas Agent 엔진이 유효 구성을 재구축하거나 수신하기 위해 시도한 횟수를 식별합니다. API 응답은 Atlas Agent 엔진이 로그에 기록하는 기본 오류 텍스트를 생략합니다. 자세히 학습 조직 정책 출시 상태 보기를 참조하세요.
프로젝트 저장된 정책을 수신하지 못하면 Atlas Agent 엔진은 해당 프로젝트 에 정책 전달을 다시 시도하고 이미 변경 사항을 수신한 프로젝트는 그대로 둡니다. 잘못된 정책 값과 같이 빌드 다시 시도하여 실패를 해결할 수 없는 경우 Atlas Agent 엔진은 해당 프로젝트 빌드 시도를 즉시 중지합니다. 연결할 수 없는 프로젝트 와 같이 일시적인 오류인 경우 Atlas Agent 엔진은 프로젝트 빌드 다시 시도하며 시도 사이의 지연 시간을 늘립니다. Atlas Agent Engine은 10 시도가 실패한 후 프로젝트 빌드 재시도를 중지합니다.
시도 횟수는 다음에 사용자가 정책을 편집할 때 재설정됩니다. Atlas Agent 엔진이 프로젝트 재시도를 중지하는 경우 정책을 수정하고 다시 저장하여 프로젝트 롤아웃 대기열로 되돌립니다.
정책 거부 모니터링
플랫폼 UI 정책이 조직 및 프로젝트에서 호출을 거부하는 빈도를 보고합니다. 플랫폼 UI 지표 읽는 방법을 학습 정책 거부 보기를 참조하세요.
제한 사항
정책 엔진에는 다음과 같은 제한 사항이 있습니다.
새 정책 또는 업데이트된 정책이 적용되는 데 최대 1분이 걸립니다. 정책은 전파된 후에 시작되는 실행에만 적용됩니다. 가드레일은 거의 즉시 적용됩니다.
OE는 한 번의 호출로 한도를 초과할 수 있습니다. OE는 각 호출 전에 기간과 토큰 사용을 확인합니다. 호출이
MAX_EXECUTION_DURATION_MS또는MAX_TOKENS_PER_EXECUTION제한에 도달하지 않은 경우, 호출이 이러한 제한을 초과하더라도 다음 호출을 수행합니다.OE는 두 번 이상 호출하여 세션 토큰 상한을 초과할 수 있습니다. 하나의 세션에서 동시에 여러 실행이 실행됩니다. Atlas Agent 엔진은 모든 진행 중인 통화가 완료된 후에만 세션 상한을 확인합니다.
MAX_TOKENS_PER_SESSION값은 해당 호출을 합한 토큰으로 구성된 최대값을 초과할 수 있습니다.토큰 대문자는 메모리 추출을 제외합니다. 메모리 추출이 소비하는 토큰은
MAX_TOKENS_PER_EXECUTION또는MAX_TOKENS_PER_SESSION값에 포함되지 않습니다.거부 횟수에는 모델 거부가 제외됩니다. View Policy Denials(정책 거부 보기) 지표는 요청된 모델이
AUTHORIZED_MODELS정책 유형에 정의되어 있지 않은 경우의 거부를 계산하지 않습니다.카탈로그가 없는 도구는 이름으로만 일치합니다. 사용자 지정 도구와 같이 카탈로그 식별자가 없는 도구는 도구 이름으로만
AUTHORIZED_TOOLS정책 유형 항목을 일치시킵니다. 자세히 학습 도구 및 카탈로그 일치를 참조하세요.네트워크 송신은 별도로 관리됩니다. 정책 엔진은 네트워크 송신을 제어하지 않습니다. 네트워크 이그레스 제한을 구성하는 방법을 학습 네트워크 이그레스 정책 관리를 참조하세요.