> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 핵심 개념
> Omni의 데이터 계층, 플레이북, 분석 수명주기, 판정 값, 크레딧 카테고리를 한 페이지에서 정리합니다.
Omni 문서 전체에서 반복해서 등장하는 개념입니다. 대시보드와 API 어느 쪽을 쓰든 이 페이지의 용어를 기준으로 설명합니다.
## 데이터 계층
```
Project 프로젝트 — API 키·멤버·크레딧의 단위
└── Workflow 워크플로우 — 정책 + 플레이북 + 출력 스키마
└── Profile 프로파일 — 검증 대상 하나 (예: 거래처 한 곳)
└── Folder 폴더 — 프로파일 안의 문서 묶음 (기본 폴더 자동 생성)
└── Item 아이템 — 파일·텍스트·JSON 한 건
└── Analysis 분석 — 프로파일 전체를 플레이북으로 검증한 결과
```
| 계층 | 식별자 접두사 | 만드는 곳 | 제한 |
| -------- | ----------- | ---------- | ------------------------------------ |
| Project | `proj_` | 대시보드 | 사용자당 5개 |
| Workflow | `wf_` | 대시보드 | 프로젝트당 10개 |
| Profile | `pf_` | 대시보드 · API | 워크플로우당 무제한 |
| Folder | `fd_` | 대시보드 · API | 프로파일당 여러 개, 기본 폴더 1개 자동 생성 |
| Item | `item_` | 대시보드 · API | 개수 제한 없음. 파일 하나 10MB, 프로파일당 누적 100MB |
| Analysis | `analysis_` | 대시보드 · API | 체험판 프로젝트는 하루 10회 |
프로젝트와 워크플로우는 대시보드에서만 만듭니다. API 키는 프로젝트 단위로 발급되며, 그 키로는 해당 프로젝트에 속한 워크플로우·프로파일·아이템·분석만 다룰 수 있습니다.
## 워크플로우와 플레이북
워크플로우는 **정책(자연어)** · **AI 모델** · **출력 스키마**로 구성됩니다. 워크플로우를 저장하면 Omni가 정책을 해석해 **플레이북**을 만듭니다. 플레이북은 분석이 실제로 따라가는 실행 계획입니다.
| 구성 요소 | 설명 | API 필드 |
| ------- | ------------------------------------------------------------------- | -------------------------------------------- |
| 플레이북 ID | `PB-YYYYMMDD-XXXXXX` 형식. 정책 텍스트나 정책 문서가 바뀌어 플레이북을 **재생성**할 때만 새로 발급 | `playbookId` |
| 플레이북 버전 | 액션·엔진·참고 사항을 편집할 때마다 patch 버전이 증가. ID는 유지 | `playbookVersion` |
| 액션 | 플레이북의 단계 하나. 이름(`snake_case`)과 설명을 가지며 순서대로 실행 | `workflowActions[]` |
| 액션 ID | 액션의 안정 식별자. 순서를 바꿔도 변하지 않음 | `workflowActions[].workId`, 감사 로그의 `work_id` |
| Step 엔진 | 액션에 연결된 외부 검증 엔진(예: AML 스크리닝). 정책 내용에 따라 자동 연결되며 수정 화면에서 바꿀 수 있음 | `workflowActions[].engines[]` |
| 참고 사항 | 액션별로 에이전트에게 주는 추가 지시. 액션당 최대 20개, 항목당 500자 | `workflowActions[].referenceNotes[]` |
플레이북을 편집해도 이미 끝난 분석은 바뀌지 않습니다. 분석은 실행 시점의 플레이북을 **동결**해 보관하며, 응답의 `playbookSnapshot`·`playbookVersion`·`snapshotStatus`로 어느 버전이 쓰였는지 확인할 수 있습니다.
## 분석 수명주기
```
POST /profiles/:id/analyze → pending → processing → completed
└→ failed
```
| 상태 | 의미 | 다음 행동 |
| ------------ | -------------------------------------- | ------------------------ |
| `pending` | 큐에 등록됨 | 폴링 계속 |
| `processing` | 에이전트가 플레이북 실행 중 | 폴링 계속 |
| `completed` | 결과 확정 | `verificationStatus`로 분기 |
| `failed` | 실행 실패. `error.code`·`error.message` 확인 | 아이템 상태 점검 후 재실행 |
분석은 비동기입니다. 요청은 `202 Accepted`와 `analysisId`를 즉시 돌려주고, 결과는 [`GET /analyses/:analysisId`](/ko/omni/api-reference/get-analysis)를 폴링해 받습니다. 같은 프로파일에서 분석이 진행 중이면 새 분석 요청은 `409`로 거부됩니다.
분석을 실행하려면 프로파일의 모든 아이템이 `ACTIVE` 상태여야 합니다.
| 아이템 상태 | 의미 |
| --------- | ---------------------- |
| `PENDING` | 업로드됨, 텍스트 추출(OCR) 진행 중 |
| `ACTIVE` | 분석에 사용할 수 있음 |
| `FAILED` | 처리 실패. 삭제 후 다시 업로드 |
## 판정 값 세 가지
분석 결과에는 서로 다른 층위의 판정이 함께 들어 있습니다. 후속 처리를 분기할 때는 최상위 `verificationStatus`를 쓰세요.
| 층위 | 필드 | 값 |
| -------- | ------------------------------ | ------------------------------------------ |
| 분석 전체 | `verificationStatus` | `verified` · `pending_review` · `rejected` |
| 플레이북 단계 | `agentAuditLog.steps[].status` | `passed` · `needs_review` · `failed` |
| 개별 검증 항목 | `findings[].result` | `passed` · `warning` · `failed` |
| `verificationStatus` | 산정 규칙 | 권장 처리 |
| -------------------- | ------------------------ | ------------ |
| `verified` | 모든 단계 `passed` | 자동 승인 |
| `pending_review` | `needs_review` 단계가 하나 이상 | 담당자 검토 큐로 |
| `rejected` | `failed` 단계가 하나 이상 | 거부 또는 에스컬레이션 |
## Analysis Score
분석이 **정의된 대로 얼마나 완결되게 수행됐는지**를 0–100으로 나타냅니다. AI의 확신도가 아닙니다. API에서는 `confidence` 객체로 제공됩니다.
| 항목 | 가중치 | 계산 |
| ------------------- | --- | ---------------------------------- |
| Step Execution | 40% | 플레이북 단계 중 실제로 실행된 비율 |
| Step Quality | 20% | 실행된 단계의 통과 여부와 지정 엔진 호출 여부 |
| Output Completeness | 40% | 출력 스키마의 말단 필드 중 값이 채워진 비율(배열은 원소별) |
점수 구간에 따라 `HIGH`(80–100) · `MEDIUM`(65–79) · `LOW`(0–64) 등급이 붙습니다. `confidenceScore`(0–1)는 이와 별개로 에이전트가 남긴 확신도이며 비어 있을 수 있습니다.
## 출력 스키마와 추출 데이터
출력 스키마는 워크플로우마다 정의하는 JSON Schema입니다. 분석 결과의 `extractedData`는 이 구조를 그대로 따르며, 말단 필드마다 값과 판정 사유가 함께 내려옵니다.
```json theme={null}
"company": {
"name": {
"value": "주식회사 에이씨엠이 트레이딩",
"reasoning": "사업자등록증의 법인명 항목에서 추출",
"sourceStep": 1
}
}
```
스키마가 없는 워크플로우나 출력 조립에 실패한 분석은 이 봉투 없이 액션별 원본 구조를 돌려줍니다. 판별 방법과 필드가 비는 경우의 해석은 [분석 결과 읽기](/ko/omni/guides/reading-analysis-results)에서 다룹니다.
## 크레딧
프로젝트의 크레딧 사용량은 세 카테고리로 집계됩니다.
| 카테고리 | 청구 시점 | 예 |
| ----------- | ------------------------- | ------------------------- |
| Environment | 매일 00:00 UTC, 프로젝트 상태와 무관 | 워크플로우 유지 |
| Operation | API 요청이 성공했을 때 | 프로파일 생성, 파일 아이템 추가, 분석 실행 |
| Tools | 분석 중 외부 엔진 호출이 성공했을 때 | AML 스크리닝 |
내역은 대시보드의 [크레딧 사용량](/ko/omni/dashboard/project/credit-usage) 탭에서 확인합니다.
## 다음 단계
프로젝트 생성부터 첫 분석 결과 읽기까지.
`extractedData` 봉투, 미추출 사유, 감사 로그 해석.