Agent Receipts

로그는 무슨 일이 일어났는지 알려주지만, 영수증은 그것을 증명합니다.

Live Demo agent-receipts MCP server npm version License: MIT macOS Windows Linux

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

실제 사례

저는 자동차 정비소를 위한 멀티 테넌트 SaaS인 ModQuote를 만들었습니다. 개발 과정에서 코드베이스를 감사하고 수정하기 위해 Claude Code를 광범위하게 사용했습니다.

문제는 무언가 잘못되었을 때, Claude가 어떤 입력을 받았는지, 무엇을 변경했는지, 또는 출력이 예상과 일치하는지 증명할 방법이 없었다는 점입니다.

Agent Receipts를 사용하면 이제 모든 Claude Code 세션이 서명된 영수증을 생성합니다:

입력 해시는 Claude가 정확히 어떤 코드를 보았는지 증명합니다.
출력 해시는 Claude가 정확히 무엇을 생성했는지 증명합니다.
제약 조건은 지연 시간이 급증하거나 비용이 예산을 초과할 때 이를 포착합니다.
체인은 다단계 감사 세션의 전체 시퀀스를 보여줍니다.

수정이 예상대로 작동하지 않을 때, 영수증을 가져와 서명을 확인하고 정확한 입력/출력 해시를 볼 수 있었습니다. 추측할 필요도 없고 "Claude가 오해했겠지"라고 생각할 필요도 없습니다.

그것이 로그와 영수증의 차이입니다. 로그는 무슨 일이 일어났는지 알려주지만, 영수증은 그것을 증명합니다.

빠른 시작: MCP 서버

AI 도구 설정에 Agent Receipts MCP 서버를 추가하면 모든 작업에 대해 자동으로 암호학적 영수증이 생성됩니다.

플랫폼 지원: macOS, Windows 및 Linux — Node.js 18+ 필요

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Claude Code

프로젝트 루트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Cursor

프로젝트 루트의 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

빠른 시작: SDK

npm install @agent-receipts/sdk

import { AgentReceipts } from '@agent-receipts/sdk'

const ar = new AgentReceipts()

const receipt = await ar.track({
  action: 'generate_report',
  input: { query: 'Q4 revenue' },
  output: { total: 142000 },
})

console.log(receipt.receipt_id)  // rcpt_8f3k2j4n...
console.log(receipt.signature)   // ed25519 signature

빠른 시작: CLI

npx @agent-receipts/cli init          # Generate signing keys
npx @agent-receipts/cli keys          # Show public key
npx @agent-receipts/cli list          # List all receipts
npx @agent-receipts/cli verify <id>   # Verify a receipt signature

작동 원리

에이전트가 작업 수행 — API 호출, 코드 생성, 데이터 조회
입력/출력 SHA-256 해싱 — 원시 데이터는 절대 기기를 떠나지 않습니다.
영수증 생성 — 작업, 해시, 타임스탬프, 에이전트 ID, 메타데이터
Ed25519 서명 생성 — 로컬에서 생성된 개인 키 사용
누구나 검증 가능 — 공개 키를 공유하면 수신자가 독립적으로 검증할 수 있습니다.

MCP 도구 참조

MCP 서버는 AI 에이전트가 직접 호출할 수 있는 14개의 도구를 제공합니다:

도구	설명	주요 매개변수
`track_action`	자동 해싱을 통해 에이전트 작업 추적	`action`, `input`, `output`, `constraints`
`create_receipt`	사전 계산된 해시로 영수증 생성	`action`, `input_hash`, `output_hash`, `constraints`
`complete_receipt`	결과와 함께 보류 중인 영수증 완료	`receipt_id`, `output`, `status`
`verify_receipt`	영수증의 암호학적 서명 검증	`receipt_id`
`get_receipt`	ID로 영수증 조회	`receipt_id`
`list_receipts`	선택적 필터링을 사용하여 영수증 목록 조회	`agent_id`, `status`, `chain_id`
`get_chain`	타임스탬프 순으로 체인의 모든 영수증 조회	`chain_id`
`get_public_key`	검증을 위한 Ed25519 공개 키 내보내기	—
`judge_receipt`	영수증에 대한 AI 판정 시작	`receipt_id`, `rubric`
`complete_judgment`	결과와 함께 보류 중인 판정 완료	`receipt_id`, `verdict`, `score`, `criteria`
`get_judgments`	영수증에 대한 모든 판정 조회	`receipt_id`
`cleanup`	만료된 영수증 삭제 (TTL)	`dry_run`
`generate_invoice`	날짜 범위 내의 영수증으로 인보이스 생성	`from`, `to`, `format`, `agent_id`
`get_started`	사용 예시가 포함된 시작 가이드 표시	—

SDK API 참조

`new AgentReceipts(config?)`

const ar = new AgentReceipts({
  dataDir: '~/.agent-receipts',  // optional, defaults to ~/.agent-receipts
})

`ar.track(params)` — 완료된 작업 추적

const receipt = await ar.track({
  action: 'analyze_data',
  input: { dataset: 'sales_2024' },
  output: { summary: 'Revenue up 12%' },
  agent_id: 'analyst-v2',
  chain_id: 'chain_abc',              // optional, auto-generated if omitted
  parent_receipt_id: 'rcpt_prev',     // optional, links to parent receipt
})

`ar.start(params)` — 보류 중인 영수증 시작

const receipt = await ar.start({
  action: 'long_running_task',
  input: { job_id: '12345' },
})

`ar.complete(receiptId, params)` — 보류 중인 영수증 완료

const completed = await ar.complete(receipt.receipt_id, {
  output: { result: 'done' },
  status: 'completed',
})

`ar.verify(receiptId)` — 영수증 서명 검증

const { verified, receipt } = await ar.verify('rcpt_8f3k2j4n')
// verified: true | false

`ar.get(receiptId)` — ID로 영수증 조회

const receipt = await ar.get('rcpt_8f3k2j4n')

`ar.list(filter?)` — 영수증 목록 조회

const result = await ar.list({ agent_id: 'my-agent', status: 'completed' })
// result.data: ActionReceipt[]
// result.pagination: { page, limit, total, total_pages, has_next, has_prev }

`ar.getPublicKey()` — 서명 공개 키 조회

const publicKey = await ar.getPublicKey()
// 64-char hex string (Ed25519 public key)

`ar.track()` with Constraints

const receipt = await ar.track({
  action: 'generate_summary',
  input: { document_id: 'doc-q4-2024' },
  output: { summary: 'Revenue grew 12% YoY...' },
  latency_ms: 1200,
  cost_usd: 0.005,
  constraints: [
    { type: 'max_latency_ms', value: 5000 },
    { type: 'max_cost_usd', value: 0.01 },
    { type: 'min_confidence', value: 0.8 },
  ],
})
// receipt.constraint_result.passed → true/false

`ar.getJudgments(receiptId)` — 판정 조회

const judgments = await ar.getJudgments('rcpt_8f3k2j4n')

`ar.cleanup()` — 만료된 영수증 삭제

const { deleted, remaining } = await ar.cleanup()

`ar.generateInvoice(params)` — 영수증으로 인보이스 생성

const invoice = await ar.generateInvoice({
  from: '2026-01-01',
  to: '2026-01-31',
  agent_id: 'my-agent',       // optional filter
  group_by: 'agent',          // optional: agent | action | day
})

CLI 참조

명령어	설명
`init`	데이터 디렉토리 생성 및 서명 키 생성
`keys`	공개 키 표시
`keys --export`	공개 키를 JSON으로 내보내기
`keys --import <hex>`	개인 키 가져오기 (64 16진수 문자)
`inspect <id	file>`	영수증을 보기 좋게 출력
`verify <id	file>`	영수증 서명 검증
`verify <id	file> --key `	외부 공개 키로 검증
`list`	영수증 목록 조회 (기본값: 50)
`list --agent <id> --status <s>`	에이전트 또는 상태별 필터링
`list --json`	JSON으로 출력
`chain <chain_id>`	체인의 모든 영수증 표시
`chain <chain_id> --tree`	체인을 시각적 트리로 표시
`stats`	집계된 영수증 통계 표시
`judgments <id>`	영수증에 대한 판정 목록 조회
`cleanup`	만료된 영수증 삭제
`cleanup --dry-run`	삭제될 항목 미리보기
`export <id>`	단일 영수증을 JSON으로 내보내기
`export --all`	모든 영수증을 압축된 JSON으로 내보내기
`export --all --pretty`	모든 영수증을 서식화된 JSON으로 내보내기
`invoice --from <date> --to <date>`	날짜 범위 내 영수증으로 인보이스 생성
`invoice --format <fmt>`	json, csv, md 또는 html로 출력
`seed --demo`	테스트용 데모 데이터 시드
`seed --demo --count <n>`	사용자 지정 개수의 데모 영수증 시드
`seed --demo --clean`	시드 전 모든 영수증 삭제
`watch`	실시간으로 새로운 영수증 감시
`watch --agent <id>`	에이전트, 작업 또는 상태별 필터링 감시

영수증 형식

{
  "receipt_id": "rcpt_8f3k2j4n",
  "chain_id": "chain_x9f2k",
  "parent_receipt_id": null,
  "receipt_type": "action",
  "agent_id": "my-agent",
  "org_id": "my-org",
  "action": "generate_report",
  "status": "completed",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "output_summary": "Generated Q4 report",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-02-07T14:32:01.442Z",
  "completed_at": "2026-02-07T14:32:02.100Z",
  "latency_ms": 658,
  "cost_usd": 0.003,
  "signature": "ed25519:<hex>"
}

입력과 출력은 클라이언트 측에서 SHA-256으로 해싱됩니다. 원시 데이터는 절대 환경을 떠나지 않습니다. 영수증에는 해시만 저장됩니다.

검증

영수증을 검증해야 하는 사람과 공개 키를 공유하세요:

# Export your public key
npx @agent-receipts/cli keys --export

# Verify a receipt with an external public key
npx @agent-receipts/cli verify receipt.json --key <public-key-hex>

검증은 영수증의 결정론적 필드에 대해 Ed25519 서명을 다시 계산하고 저장된 서명과 일치하는지 확인합니다. 네트워크 요청이 없는 완전한 오프라인 방식입니다.

구성

환경 변수	설명	기본값
`AGENT_RECEIPTS_DATA_DIR`	데이터 디렉토리 경로	`~/.agent-receipts`
`AGENT_RECEIPTS_AGENT_ID`	기본 에이전트 ID	`local-agent`
`AGENT_RECEIPTS_ORG_ID`	조직 ID	`local-org`
`AGENT_RECEIPTS_ENVIRONMENT`	환경 레이블 (`development`, `production`, `staging`, `test`)	`production`
`RECEIPT_SIGNING_PRIVATE_KEY`	Ed25519 개인 키 (16진수)	자동 생성

저장소

모든 데이터는 데이터 디렉토리에 로컬로 저장됩니다:

~/.agent-receipts/
├── keys/
│   ├── private.key          # Ed25519 private key (mode 0600)
│   └── public.key           # Ed25519 public key
├── receipts/
│   └── *.json               # Legacy JSON files (auto-migrated)
├── receipts.db              # SQLite database (primary storage)
└── config.json              # Agent and org configuration

v0.2.7부터 영수증은 빠른 필터링과 페이지네이션을 위해 인덱싱된 쿼리를 지원하는 SQLite에 저장됩니다. 기존 JSON 영수증 파일은 첫 시작 시 자동으로 마이그레이션됩니다.

아키텍처

┌─────────────────────────────────────────────┐
│                  CLI                         │
│           @agent-receipts/cli                 │
├─────────────────────────────────────────────┤
│           SDK            │   MCP Server      │
│   @agent-receipts/sdk     │ @agent-receipts/   │
│                          │   mcp-server      │
├──────────────────────────┴──────────────────┤
│              Crypto + Schema                 │
│   @agent-receipts/crypto  @agent-receipts/     │
│                            schema            │
└─────────────────────────────────────────────┘

schema — Zod 스키마, TypeScript 타입, 작업 영수증 프로토콜을 위한 JSON 스키마
crypto — Ed25519 키 생성, 서명, 검증, 정규 직렬화
mcp-server — 영수증 엔진, 저장소 및 키 관리를 포함한 MCP 프로토콜 서버
sdk — 엔진을 래핑하는 고수준 Node.js SDK
cli — 영수증 검사, 검증 및 관리를 위한 명령줄 도구
dashboard — 영수증 시각화 및 관리를 위한 미션 컨트롤 웹 UI

대시보드 (Mission Control)

시스템의 모든 영수증, 체인, 에이전트, 제약 조건 및 판정을 시각화합니다.

npx @agent-receipts/dashboard

http://localhost:3274에서 미션 컨트롤을 열어 모든 영수증을 시각화, 검증 및 관리하세요.

기능: 실시간 영수증 피드, 체인 시각화, 제약 조건 상태 모니터링, 판정 점수, 서명 검증, 인보이스 생성, 다크 모드, 전체 검색.

13개 페이지: 개요, 영수증, 영수증 상세, 체인, 체인 상세, 에이전트, 에이전트 상세, 제약 조건, 판정, 인보이스, 검증, 설정, 작동 원리.

예시

예시	설명
`examples/basic`	검증을 포함한 간단한 작업 추적
`examples/chained`	부모/자식 영수증 연결을 포함한 다단계 파이프라인
`examples/pipeline`	체인 영수증을 포함한 문서 분석 파이프라인
`examples/constraints`	통과/실패 규칙을 포함한 제약 조건 검증
`examples/judge`	루브릭을 포함한 AI 판정 평가
`examples/ttl`	영수증 TTL 및 정리

패키지

패키지	설명
`@agent-receipts/schema`	작업 영수증 프로토콜을 위한 Zod 스키마 및 TypeScript 타입
`@agent-receipts/crypto`	Ed25519 서명, 검증 및 키 관리
`@agent-receipts/mcp-server`	영수증 엔진 및 저장소를 포함한 MCP 프로토콜 서버
`@agent-receipts/sdk`	영수증 추적 및 검증을 위한 고수준 Node.js SDK
`@agent-receipts/cli`	영수증 관리를 위한 명령줄 도구
`@agent-receipts/dashboard`	미션 컨트롤 웹 UI — `npx @agent-receipts/dashboard`

로드맵

[x] 로컬 우선 영수증 저장소 (인덱싱된 쿼리를 지원하는 SQLite)
[x] Ed25519 서명 및 검증
[x] 14개 도구를 포함한 MCP 서버
[x] Node.js SDK
[x] 전체 명령어 세트를 포함한 CLI
[x] 제약 조건 검증 (6개 내장 타입)
[x] 루브릭 기반 평가를 포함한 AI 판정
[x] 출력 스키마 검증 (JSON 스키마)
[x] 영수증 TTL 및 정리
[x] 인보이스 생성 (JSON, CSV, Markdown, HTML)
[x] 미션 컨트롤 대시보드 (13개 페이지, 다크 모드, 검색)
[x] 대시보드 npm 패키지 — npx @agent-receipts/dashboard
[x] agent-receipts-web.vercel.app에서 라이브 데모 제공
[ ] 블록체인/타임스탬프 서비스에 영수증 고정
[ ] 멀티 에이전트 영수증 공유 프로토콜
[ ] 영수증 압축 및 아카이빙
[ ] 클라우드 데이터베이스를 포함한 호스팅 티어

개발

pnpm install
pnpm build
pnpm test
pnpm dev

라이선스

MIT — LICENSE 참조

agent-receipts

Agent Receipts

실제 사례

빠른 시작: MCP 서버

Claude Desktop

Claude Code

Cursor

빠른 시작: SDK

빠른 시작: CLI

작동 원리

MCP 도구 참조

SDK API 참조

`new AgentReceipts(config?)`

`ar.track(params)` — 완료된 작업 추적

`ar.start(params)` — 보류 중인 영수증 시작

`ar.complete(receiptId, params)` — 보류 중인 영수증 완료

`ar.verify(receiptId)` — 영수증 서명 검증

`ar.get(receiptId)` — ID로 영수증 조회

`ar.list(filter?)` — 영수증 목록 조회

`ar.getPublicKey()` — 서명 공개 키 조회

`ar.track()` with Constraints

`ar.getJudgments(receiptId)` — 판정 조회

`ar.cleanup()` — 만료된 영수증 삭제

`ar.generateInvoice(params)` — 영수증으로 인보이스 생성

CLI 참조

영수증 형식

검증

구성

저장소

아키텍처

대시보드 (Mission Control)

예시

패키지

로드맵

개발

라이선스

Resources

Tools

Latest Blog Posts

MCP directory API

Agent Receipts

실제 사례

빠른 시작: MCP 서버

Claude Desktop

Claude Code

Cursor

빠른 시작: SDK

빠른 시작: CLI

작동 원리

MCP 도구 참조

SDK API 참조

new AgentReceipts(config?)

ar.track(params) — 완료된 작업 추적

ar.start(params) — 보류 중인 영수증 시작

ar.complete(receiptId, params) — 보류 중인 영수증 완료

ar.verify(receiptId) — 영수증 서명 검증

ar.get(receiptId) — ID로 영수증 조회

ar.list(filter?) — 영수증 목록 조회

ar.getPublicKey() — 서명 공개 키 조회

ar.track() with Constraints

ar.getJudgments(receiptId) — 판정 조회

ar.cleanup() — 만료된 영수증 삭제

ar.generateInvoice(params) — 영수증으로 인보이스 생성

CLI 참조

영수증 형식

검증

구성

저장소

아키텍처

대시보드 (Mission Control)

예시

패키지

로드맵

개발

라이선스

Resources

Tools

Latest Blog Posts

MCP directory API

`new AgentReceipts(config?)`

`ar.track(params)` — 완료된 작업 추적

`ar.start(params)` — 보류 중인 영수증 시작

`ar.complete(receiptId, params)` — 보류 중인 영수증 완료

`ar.verify(receiptId)` — 영수증 서명 검증

`ar.get(receiptId)` — ID로 영수증 조회

`ar.list(filter?)` — 영수증 목록 조회

`ar.getPublicKey()` — 서명 공개 키 조회

`ar.track()` with Constraints

`ar.getJudgments(receiptId)` — 판정 조회

`ar.cleanup()` — 만료된 영수증 삭제

`ar.generateInvoice(params)` — 영수증으로 인보이스 생성