검증된 지원 에이전트

실제 AI 에이전트로, Claude Agent SDK로 구축되었으며, 백엔드로 가는 유일한 경로는 KYA-OS로 보호되는 MCP 서버를 통해서입니다. (KYA-OS는 Vouched가 Decentralized Identity Foundation에 기증한 개방형 에이전트 ID 및 위임 표준입니다.)

이 시나리오는 Vouched의 자체 반복 예시를 반영합니다: $50 환불은 자동으로 처리하지만 그보다 큰 금액은 사람의 승인이 필요한 지원 에이전트입니다. 여기의 모든 것은 실제입니다 - 실제 Ed25519 서명 암호화 ID, 실제 W3C 위임 자격 증명, 이를 발급하는 실제 동의 HTTP 서버, 그리고 실제 도구 호출을 수행하는 실제 에이전트. 유일하게 모의(mock)된 것은 주문 데이터입니다(아래 "왜 모의인가" 참조).

Agent calls issue_refund($30)  -> executes immediately, proof attached
Agent calls issue_refund($500) -> needs_authorization -> human approves at a real URL -> agent retries -> succeeds

왜 이것이 존재하는가

AI 에이전트는 이제 사용자를 대신하여 행동합니다 - 주문 상태 확인, 환불 발행, 자금 이동 - 그리고 그들이 대신하는 인간과 구별할 수 없는 자격 증명을 사용합니다. 세션 쿠키는 세 가지 별개의 질문을 하나의 구별할 수 없는 HTTP 요청으로 축소합니다: 실제로 행동하는 사람은 누구인지, 누구의 권한으로 행동하는지, 그 특정 행동이 그 권한 내에 있는지입니다. KYA-OS는 이 세 가지 질문을 별도로 답변하므로, 낮은 위험의 행동은 완전히 자동화할 수 있고(누가 했는지에 대한 서명된 증명 포함) 높은 위험의 행동은 에이전트가 그 특정 권한을 위임받았음을 증명해야 하며, 종종 실시간 인간 동의 단계를 거칩니다.

Vouched의 자체 자료는 두 가지 예시를 반복적으로 언급합니다: 지원/환불 에이전트("$50 환불은 자동으로 처리하지만 $5,000 이상은 승인 필요")와 여행 예약 에이전트("항공편 상태는 조회하지만 승인 없이는 항공편을 예약하지 않음")입니다. 이 저장소는 첫 번째 예시를 실제로 처음부터 끝까지 구축합니다.

빠른 시작

npm install
npm run verify   # deterministic, no LLM needed - proves the whole lifecycle works
npm run agent    # the real thing - a live Claude Agent SDK agent driving 3 scripted turns

npm run verify는 src/verify-lifecycle.ts를 실행합니다: 하나의 프로세스에서 수명 주기의 모든 부분을 실행하는 자체 포함 스크립트입니다(증명 생성, 증명 검증, 반드시 실패해야 하는 의도적 변조 테스트, 전체 needs_authorization -> 실제 consent-server 승인 -> 자동 적용 재시도 -> 성공 루프) 그리고 각 검사에 대해 PASS/FAIL을 출력합니다. API 키가 필요 없습니다 - LLM을 호출하지 않습니다.

npm run agent는 src/agent.ts를 실행합니다: Claude Agent SDK로 구축된 실제 에이전트로, stdio를 통해 src/server.ts에 MCP 도구 소스로 연결됩니다. 세 가지 프롬프트를 실행합니다 - 주문 확인, $30 환불 발행, $500 환불 발행 - 그리고 세 번째에서 의도적으로 인증 링크에서 멈춥니다. 그 멈춤이 핵심입니다: 에이전트는 증명이나 자격 증명을 결코 보지 못하고, 때때로 인간에게 인증 링크를 전달하도록 요청하는 도구만 볼 뿐입니다. ANTHROPIC_API_KEY가 설정되어 있어야 합니다(또는 인증된 claude CLI 세션).

각 파일의 내용

자신의 MCP 서버에 적용하기

kya-tools.ts의 패턴은 모든 MCP 서버에 일반화됩니다:

1. 서버의 ID를 래핑하세요: createKyaOsMiddleware({ identity, session: {...}, autoSession: true }, crypto).

2. 각 도구를 분류하세요. 읽기 전용 또는 낮은 위험: kyaos.wrapWithProof('tool_name', handler) - 서명된 증명으로 귀속되며, 게이트되지 않습니다. 높은 위험: kyaos.wrapWithDelegation('tool_name', { scopeId, consentUrl, formatChallenge }, kyaos.wrapWithProof('tool_name', handler)) - 해당 범위의 위임 자격 증명이 제시될 때까지 차단됩니다.

3. consentUrl을 자신의 승인 페이지로 지정하거나, consent-server.ts와 public/consent.html을 그대로 재사용하세요.

4. 위임 게이트 처리기를 formatAsConsentLink()로 래핑하세요(kya-tools.ts 참조) - 승인된 자격 증명이 호출자의 재시도 시 자동으로 적용되도록, 누구도 수동으로 자격 증명을 붙여넣지 않습니다.

이것은 단지 이 데모가 실행된다는 증거가 아니라 통합 가이드의 형태입니다.

왜 모의인가, 실제 통합이 아닌 이유

check_order_status와 issue_refund는 작은 고정 인메모리 데이터셋에서 작동합니다 - 실제 주문, 실제 고객, 실제 결제 프로세서, PCI/PII 관련 항목이 없습니다. 여기서 시연되는 것은 KYA-OS ID와 위임이지, 전자상거래나 결제 엔지니어링이 아니며, 실제 통합은 그 이야기에 아무 이점도 없이 데이터 처리 및 보안 표면을 추가할 뿐입니다.

이것이 의도적으로 아직 다루지 않는 것

• Checkpoint (Vouched의 에이전트 트래픽 탐지 계층) - 진정한 무료 셀프 서비스 가입이 있지만, 이는 이 저장소의 범위를 벗어난 개인 계정 생성 단계입니다.

• Multiple frameworks - Vouched의 자체 문서에는 Next.js, Express, Python, HTML, 직접 API가 나열되어 있습니다. 이 저장소는 Node/TypeScript 전용입니다. @kya-os/mcp의 API가 전송에 구애받지 않으므로 Express 변형이 자연스러운 다음 단계입니다.

• IdentiClaw / KnowThat.ai - Vouched의 KYA 제품군의 다른 두 계층; 공개 문서는 아직 부족합니다.

기반

@kya-os/mcp - Model Context Protocol을 위한 KYA-OS의 MIT 라이선스 참조 구현으로, Vouched가 Decentralized Identity Foundation의 Trusted AI Agents Working Group에 기증했습니다.