AI 에이전트 감사 로그 스키마와 이벤트 설계

핵심 정리

식별자, 순서, 테넌트, 시각, 스키마 버전과 무결성 정보를 모든 이벤트가 공유하는 고정 구조에 담습니다.
요청, 권한 판단, 모델 실행, 도구 시도, 승인과 외부 결과를 별도 이벤트로 기록하고 안정적인 ID로 연결합니다.
새 이벤트 버전을 허용하기 전에 호환성, 마스킹, 접근 권한과 내보내기 검증을 시험합니다.

공통 이벤트 구조와 업무 상세 필드를 분리합니다

공통 구조는 모든 생성 서비스에서 같아야 합니다. 이벤트 ID와 유형, 스키마 버전, 테넌트, 실행 ID와 상위 ID, 행위자, 생성 서비스, 환경, 리전, 발생 시각과 수집 시각, 순서, 무결성 정보를 포함하고 업무별 내용은 유형이 정해진 상세 필드에 둡니다.

고정된 공통 구조가 있으면 모델 게이트웨이, 에이전트 런타임, 승인 서비스, 도구 어댑터의 이벤트를 함께 조회하고 검증할 수 있습니다. 같은 개념을 서비스마다 다른 이름으로 남기는 문제도 줄어듭니다.

데이터베이스 행 번호 대신 전역에서 중복되지 않는 이벤트 ID와 안정적인 실행 ID를 사용합니다.
업무상 행위자와 실제 경계에서 사용한 서비스 계정 또는 자격증명을 구분합니다.
지연 전송을 확인할 수 있도록 이벤트 발생 시각과 수집 시각을 함께 기록합니다.
해시를 계산할 때 적용한 표준화 방식과 해시 버전을 명시합니다.

버전 1 감사 이벤트 예시도구 실행 결과를 행위자, 권한 판단, 승인, 외부 결과, 이전 이벤트 해시와 연결한 예시입니다.JSON Schema 내려받기 예시 이벤트 내려받기

{
  "schema_version": "1.0.0",
  "event_id": "0198f2f2-7a3b-7d64-8e21-b7c9386c1801",
  "event_type": "tool.completed",
  "tenant_id": "tenant_acme",
  "execution_id": "exec_20260823_1042",
  "parent_event_id": "0198f2f2-6e31-7ad4-91ab-c5f93104dd12",
  "actor": {
    "type": "ai_agent",
    "id": "agent:invoice-reviewer",
    "credential_id": "workload:invoice-reviewer"
  },
  "source": {
    "service": "agent-runtime",
    "version": "2026.08.1"
  },
  "environment": "production",
  "region": "us-east-1",
  "event_time": "2026-08-23T10:42:31.184Z",
  "observed_at": "2026-08-23T10:42:31.229Z",
  "sequence": 42,
  "integrity": {
    "canonicalization": "jcs-v1",
    "hash_algorithm": "sha-256",
    "payload_hash": "sha256:77418e964aac33bbf7ad94e7a43b833c08d53dd8156a6ea1ad18d25e6c3c26fe",
    "previous_event_hash": "sha256:b2e95e6a232cebc7a1ee00d8331212c888af5fb4225620f15adf7e5cc9444e46"
  },
  "payload": {
    "tool": {
      "name": "erp.create_credit_note",
      "version": "2.3.1"
    },
    "operation_id": "op_1042",
    "attempt": 1,
    "authorization": {
      "decision": "allow",
      "policy_id": "finance-credit-note-v4"
    },
    "approval_id": "approval_7842",
    "idempotency_key": "credit-note:CN-2026-1042",
    "input_digest": "sha256:8cbb1f38093a5e9af1206feb9fd7f310e5333822f07778c2ede5629c666c9761",
    "outcome": "succeeded",
    "external_reference": {
      "system": "erp",
      "type": "credit_note",
      "id": "CN-2026-1042"
    },
    "result_digest": "sha256:7e17a509ba134cf46597d97909f2a6eac27ce54b6fba1d4e30b816620af808d0"
  }
}

판단과 외부 결과를 별도 이벤트로 정의합니다

하나의 큰 이벤트에 요청, 승인, 실행, 완료를 모두 담지 않습니다. 요청 접수, 정책 판단, 모델 호출, 도구 제안, 사람 승인, 도구 시도, 외부 시스템 접수, 완료, 거부, 실패, 결과 불명을 각각 기록합니다.

실행 ID와 작업 ID, 시도 번호, 멱등성 키를 연결하면 타임아웃 뒤 재시도와 새로운 업무 판단을 구분할 수 있습니다. 대상 시스템의 거래 ID도 정확한 권한과 입력까지 역추적할 수 있습니다.

기존 증적을 깨뜨리지 않게 스키마를 버전 관리합니다

스키마 변경을 호환성 계약으로 다룹니다. 가능하면 선택 필드를 추가하고 의미가 달라질 때는 새 이벤트 버전을 발행합니다. 이미 확정된 증적의 과거 필드 의미를 사후에 바꾸면 안 됩니다.

보관 중인 과거 내보내기 자료로 생성자와 조회자, 검증기를 함께 시험합니다. 새 배포는 잘못된 이벤트를 거부하고 지원하지 않는 버전을 격리하며, 왕복 내보내기에 필요한 알 수 없는 필드는 보존해야 합니다.

개인정보 통제와 독립 검토를 스키마에 포함합니다

필드를 필수, 선택, 민감, 해시, 토큰화, 외부 참조로 분류합니다. 적용한 마스킹 정책과 키 버전은 기록하되 자격증명과 제한 없는 프롬프트 원문은 공통 이벤트 구조에 넣지 않습니다.

내보내기에는 스키마 정의, 이벤트 파일, 체크섬, 연결 순서 또는 머클 정보, 누락하거나 보호한 필드 목록을 포함합니다. 검토자는 불필요한 원본 데이터를 받지 않고도 구조와 무결성을 확인할 수 있어야 합니다.

AI 에이전트를 위한 감사 로그 스키마 설계