분석 결과 읽기

​

읽는 순서

​

extractedData 봉투

{
  "extractedData": {
    "company": {
      "name": {
        "value": "주식회사 에이씨엠이 트레이딩",
        "reasoning": "사업자등록증의 법인명 항목과 통장 사본의 예금주가 일치합니다.",
        "sourceStep": 1
      },
      "registration_number": {
        "value": null,
        "reasoning": "추출 결과에 사업자등록번호가 포함되지 않았습니다.",
        "sourceStep": 1
      }
    },
    "ubo_register": [
      { "name": { "value": "홍길동", "reasoning": "실소유자 확인서 1행", "sourceStep": 3 },
        "share_pct": { "value": 60, "reasoning": "실소유자 확인서 1행", "sourceStep": 3 } }
    ]
  }
}

• 값을 얻지 못한 필드도 value: null로 자리를 유지합니다. extractedData의 필드 목록은 출력 스키마와 항상 같습니다.
• 상위 객체 자체가 산출되지 않으면 그 아래 경로는 만들지 않습니다. 이때 details[]에 상위 항목의 reasonCode: "PARENT_MISSING" 한 건이 남습니다.
• reasoning은 분석 완료 시점에 저장된 값입니다. 다시 조회해도 바뀌지 않습니다.
• sourceStep은 실행 순서 번호라 워크플로우를 수정하면 다음 분석부터 달라질 수 있습니다. 단계를 안정적으로 가리키려면 agentAuditLog.steps[].work_id를 쓰세요.
• 0과 false는 유효한 값입니다. 비어 있음의 기준은 null / "" / [] / {}입니다.

​

봉투가 없는 경우

​

비어 있는 필드의 사유

{
  "category": "JSON_OUTPUT",
  "type": "OUTPUT_MISSING",
  "target": "company.registration_number",
  "reasonCode": "NOT_IN_FINAL_OUTPUT",
  "message": "사업자등록증에서 법인명과 대표자는 확인했으나 등록번호 항목을 찾지 못했습니다.",
  "stepId": 1
}

• reasonCode는 확장 가능한 열거형입니다. 표에 없는 값이 와도 오류 없이 처리하세요. type(OUTPUT_MISSING / OUTPUT_EMPTY 등 고정 6종)과는 별개의 축입니다.
• reasonCode · message · stepId는 JSON_OUTPUT 항목에만 붙습니다. STEP · TOOL 항목에는 없습니다.
• message는 담당 단계가 남긴 판단 근거이고, 봉투의 reasoning은 필드 단위 사유를 우선합니다. 두 문장은 다를 수 있으므로 필드별 맥락은 reasoning을 먼저 읽으세요.
• target은 실제 인스턴스 경로입니다. 배열은 원소 수만큼 인덱스로 펼쳐집니다(ubo_register[0].name). 빈 배열이나 배열 키 부재는 ubo_register 한 건으로 계상합니다.
• Omni는 원본 문서를 다시 검사하지 않습니다. “문서에 그 값이 없었다”는 판정은 하지 않으며, 상한선은 “추출 결과에 포함되지 않았다”(NOT_IN_FINAL_OUTPUT)입니다.

​

사유를 제공하지 못하는 경우

​

extractionStatus는 쓰지 마세요

​

판정 값 읽기

​

confidence와 confidenceScore

​

어떤 플레이북으로 판정했는가

​

감사 로그 읽기

• 단계 식별: step은 실행 순서, work_id는 플레이북 액션의 고정 ID입니다. GET /workflows/:workflowId의 workflowActions[].workId와 대응합니다.
• 단계 판정: status(passed / needs_review / failed)와 reasoning이 대시보드 Summary 탭의 판단 줄입니다. rule은 그 단계가 수행한 지시입니다.
• 외부 엔진 호출: mcpcalls[]의 success와 error_code로 실패를 판단하세요. HTTP 상태 코드는 없습니다. fallback_to_rag: true는 엔진 실패 후 문서 검색으로 대체 실행했다는 뜻입니다.
• 같은 호출을 액션 기준으로 보려면 rawActionResults.{action}.mcpResults[]를 쓰세요. 이쪽은 카멜 케이스(durationMs, errorCode, fallbackToRag)입니다.
• 실행되지 않은 단계는 systemMetadata.workflowHistory[]에도 나오지 않습니다. 전체 단계 정의는 워크플로우 응답의 workflowActions에서 확인하세요. 미실행 단계는 details[]에 STEP_NOT_EXECUTED로 남습니다.

​

후속 처리 패턴

a = get_analysis(analysis_id)
if a["status"] != "completed":
    return retry_later()

fmt = a.get("systemMetadata", {}).get("outputFormatting")
raw_mode = fmt is None and a["outputSchema"] is None or (fmt and fmt["status"] in ("skipped", "fallback_raw"))

if a["verificationStatus"] == "verified" and a["confidence"]["score"] >= 80 and not raw_mode:
    approve(a["extractedData"])
elif a["verificationStatus"] == "rejected":
    reject(reason=[s for s in a["agentAuditLog"]["steps"] if s["status"] == "failed"])
else:
    route_to_reviewer(a, missing=[d for d in a["details"] if d["category"] == "JSON_OUTPUT"])

• 검토자에게는 details[]의 target · reasonCode · message와 봉투의 reasoning을 함께 보여주면 원인 파악이 빠릅니다.
• 아이템을 보강한 뒤 같은 프로파일에서 다시 분석하면 새 analysisId가 발급됩니다. 이전 결과는 유지되며 대시보드의 Run 선택으로 비교할 수 있습니다.
• 사람이 읽는 리포트가 필요하면 GET /analyses/:analysisId/report로 PDF를 받으세요.