# Verified Support Agent

A real AI agent, built with the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk), whose only path to a backend is through an MCP server secured with [KYA-OS](https://modelcontextprotocol-identity.io/mcp) (the open agentic identity and delegation standard, donated to the [Decentralized Identity Foundation](https://blog.identity.foundation/kya-os/) by [Vouched](https://kya.vouched.id/)).

The scenario mirrors Vouched's own recurring example: a support agent that can process a $50 refund automatically but needs a human to approve anything larger. Everything here is real - a real Ed25519-signed cryptographic identity, a real W3C Delegation Credential, a real consent HTTP server issuing it, and a real agent making the tool calls. The only thing that's mocked is the order data (see "Why mocked" below).

```
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
```

## Why this exists

AI agents now act on behalf of users - checking order status, issuing refunds, moving money - using credentials that make them indistinguishable from the human they're acting for. A session cookie collapses three separate questions into one indistinguishable HTTP request: **who** is actually acting, **on whose authority**, and **is this specific action inside that authority**. KYA-OS answers those three questions separately, so low-stakes actions can be fully automated (with a signed proof of who did them) and high-stakes actions require the agent to prove it was delegated that specific authority, often with a live human consent step.

Vouched's own materials return to two examples repeatedly: a support/refund agent ("process a $50 refund automatically but need approval above $5,000") and a travel-booking agent ("view flight status but not book flights without approval"). This repo builds the first one for real, end to end.

## Quick start

```bash
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` runs `src/verify-lifecycle.ts`: a self-contained script that exercises every part of the lifecycle in one process (proof generation, proof verification, a deliberate tamper test that must fail, the full `needs_authorization -> real consent-server approval -> auto-applied retry -> success` loop) and prints `PASS`/`FAIL` per check. No API key needed - it never calls an LLM.

`npm run agent` runs `src/agent.ts`: a real agent, built with the Claude Agent SDK, connected to `src/server.ts` as an MCP tool source over stdio. It drives three prompts - checking an order, issuing a $30 refund, and issuing a $500 refund - and stops at the authorization link on the third one, on purpose. That pause is the point: the agent never sees a proof or a credential, it just sees a tool that sometimes asks it to relay an authorization link to a human. Needs `ANTHROPIC_API_KEY` set (or an authenticated `claude` CLI session).

## What's in each file

| File | Purpose |
|---|---|
| `src/kya-tools.ts` | The KYA-OS-specific logic: proof/delegation wrapping, the refund threshold, the mock order data. **This is the file to read to adapt this pattern.** |
| `src/server.ts` | MCP transport wiring around `kya-tools.ts` - stdio only, run with `--stdio`. |
| `src/consent-server.ts` | A real HTTP server that renders the authorization page and issues delegation credentials on approval. |
| `src/agent.ts` | The Claude Agent SDK agent - the actual "AI agent" in this repo. |
| `src/verify-lifecycle.ts` | Deterministic proof of the full lifecycle, no LLM required. |
| `src/crypto-provider.ts` | Real Ed25519 sign/verify via `node:crypto`, wired into `@kya-os/mcp`'s `CryptoProvider` interface. |

## Adapt this to your own MCP server

The pattern in `kya-tools.ts` generalizes to any MCP server:

1. Wrap your server's identity: `createKyaOsMiddleware({ identity, session: {...}, autoSession: true }, crypto)`.
2. Classify each tool. Read-only or low-stakes: `kyaos.wrapWithProof('tool_name', handler)` - attributable via a signed proof, not gated. High-stakes: `kyaos.wrapWithDelegation('tool_name', { scopeId, consentUrl, formatChallenge }, kyaos.wrapWithProof('tool_name', handler))` - blocked until a delegation credential with that scope is presented.
3. Point `consentUrl` at your own authorization page, or reuse `consent-server.ts` and `public/consent.html` as-is.
4. Wrap the delegation-gated handler in `formatAsConsentLink()` (see `kya-tools.ts`) so an approved credential is auto-applied on the caller's retry - nobody ever pastes a credential back by hand.

That's the shape of an integration guide, not just evidence this one demo runs.

## Why mocked, not a real integration

`check_order_status` and `issue_refund` operate on a small fixed in-memory dataset - no real orders, no real customers, no real payment processor, nothing PCI/PII-relevant. The thing being demonstrated here is KYA-OS identity and delegation, not e-commerce or payments engineering, and a real integration would add data-handling and security surface for zero benefit to that story.

## What this deliberately doesn't cover yet

- **Checkpoint** (Vouched's agent-traffic-detection layer) - it has a genuine free self-serve signup, but that's a personal account-creation step outside the scope of this repo.
- **Multiple frameworks** - Vouched's own docs list Next.js, Express, Python, HTML, and direct API. This repo is Node/TypeScript only; an Express variant is a natural next step given `@kya-os/mcp`'s API is transport-agnostic.
- **IdentiClaw / KnowThat.ai** - the other two layers of Vouched's KYA suite; their public docs are still thin.

## Built on

[`@kya-os/mcp`](https://github.com/decentralized-identity/kya-os-mcp) - MIT-licensed reference implementation of KYA-OS for the Model Context Protocol, donated by Vouched to the Decentralized Identity Foundation's Trusted AI Agents Working Group.