Agente de soporte verificado

Un agente de IA real, construido con el Claude Agent SDK, cuya única vía hacia un backend es a través de un servidor MCP protegido con KYA-OS (el estándar abierto de identidad y delegación agéntica, donado a la Decentralized Identity Foundation por Vouched).

El escenario refleja el ejemplo recurrente de Vouched: un agente de soporte que puede procesar un reembolso de $50 automáticamente pero necesita un humano para aprobar cualquier cantidad mayor. Todo aquí es real: una identidad criptográfica real firmada con Ed25519, un Credencial de Delegación W3C real, un servidor HTTP de consentimiento real que lo emite, y un agente real que realiza las llamadas a herramientas. Lo único que está simulado son los datos de pedidos (ver "Por qué está simulado" más abajo).

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

Por qué existe esto

Los agentes de IA ahora actúan en nombre de los usuarios: consultan el estado de pedidos, emiten reembolsos, mueven dinero, utilizando credenciales que los hacen indistinguibles del humano por el que actúan. Una cookie de sesión colapsa tres preguntas separadas en una única solicitud HTTP indistinguible: quién está actuando realmente, bajo la autoridad de quién, y si esta acción específica está dentro de esa autoridad. KYA-OS responde esas tres preguntas por separado, de modo que las acciones de bajo riesgo pueden automatizarse por completo (con una prueba firmada de quién las realizó) y las acciones de alto riesgo requieren que el agente demuestre que se le delegó esa autoridad específica, a menudo con un paso de consentimiento humano en vivo.

Los materiales propios de Vouched vuelven a dos ejemplos repetidamente: un agente de soporte/reembolsos ("procesar un reembolso de $50 automáticamente pero necesitar aprobación por encima de $5,000") y un agente de reservas de viajes ("ver el estado del vuelo pero no reservar vuelos sin aprobación"). Este repositorio construye el primero de verdad, de principio a fin.

Inicio rápido

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 ejecuta src/verify-lifecycle.ts: un script autocontenido que ejercita cada parte del ciclo de vida en un solo proceso (generación de pruebas, verificación de pruebas, una prueba deliberada de manipulación que debe fallar, el bucle completo needs_authorization -> aprobación real del servidor de consentimiento -> reintento autoaplicado -> éxito) e imprime PASS/FAIL por cada comprobación. No se necesita clave API: nunca llama a un LLM.

npm run agent ejecuta src/agent.ts: un agente real, construido con el Claude Agent SDK, conectado a src/server.ts como fuente de herramientas MCP a través de stdio. Impulsa tres indicaciones: consultar un pedido, emitir un reembolso de $30 y emitir un reembolso de $500, y se detiene en el enlace de autorización en la tercera, a propósito. Esa pausa es el punto: el agente nunca ve una prueba o una credencial, solo ve una herramienta que a veces le pide que transmita un enlace de autorización a un humano. Necesita ANTHROPIC_API_KEY configurada (o una sesión autenticada de claude CLI).

Qué hay en cada archivo

Adapta esto a tu propio servidor MCP

El patrón en kya-tools.ts se generaliza a cualquier servidor MCP:

1. Envuelve la identidad de tu servidor: createKyaOsMiddleware({ identity, session: {...}, autoSession: true }, crypto).

2. Clasifica cada herramienta. De solo lectura o de bajo riesgo: kyaos.wrapWithProof('tool_name', handler) — atribuible mediante una prueba firmada, no restringida. De alto riesgo: kyaos.wrapWithDelegation('tool_name', { scopeId, consentUrl, formatChallenge }, kyaos.wrapWithProof('tool_name', handler)) — bloqueada hasta que se presente una credencial de delegación con ese alcance.

3. Apunta consentUrl a tu propia página de autorización, o reutiliza consent-server.ts y public/consent.html tal cual.

4. Envuelve el manejador restringido por delegación en formatAsConsentLink() (ver kya-tools.ts) para que una credencial aprobada se aplique automáticamente en el reintento del llamador: nadie pega una credencial de vuelta a mano.

Esa es la forma de una guía de integración, no solo evidencia de que esta demo funciona.

Por qué está simulado, no una integración real

check_order_status e issue_refund operan sobre un pequeño conjunto de datos fijo en memoria: sin pedidos reales, sin clientes reales, sin procesador de pagos real, nada relevante para PCI/PII. Lo que se demuestra aquí es la identidad y delegación de KYA-OS, no ingeniería de comercio electrónico o pagos, y una integración real añadiría superficie de manejo de datos y seguridad sin beneficio para esa historia.

Lo que esto deliberadamente no cubre todavía

• Checkpoint (la capa de detección de tráfico de agentes de Vouched): tiene un registro gratuito real de autoservicio, pero eso es un paso de creación de cuenta personal fuera del alcance de este repositorio.

• Múltiples frameworks: los propios documentos de Vouched listan Next.js, Express, Python, HTML y API directa. Este repositorio es solo Node/TypeScript; una variante de Express es un siguiente paso natural dado que la API de @kya-os/mcp es independiente del transporte.

• IdentiClaw / KnowThat.ai: las otras dos capas del conjunto KYA de Vouched; sus documentos públicos aún son escasos.

Construido sobre

@kya-os/mcp: implementación de referencia con licencia MIT de KYA-OS para el Model Context Protocol, donada por Vouched al Grupo de Trabajo de Agentes de IA Confiables de la Decentralized Identity Foundation.