Проверенный агент поддержки

Настоящий ИИ-агент, созданный с помощью Claude Agent SDK, единственный путь которого к бэкенду проходит через MCP-сервер, защищённый с помощью KYA-OS (открытый стандарт агентной идентичности и делегирования, переданный в Decentralized Identity Foundation компанией Vouched).

Сценарий повторяет собственный recurring-пример Vouched: агент поддержки, который может автоматически обработать возврат $50, но для одобрения более крупных сумм ему нужен человек. Здесь всё настоящее — настоящая криптографическая идентичность с подписью Ed25519, настоящее делегированное удостоверение W3C, настоящий HTTP-сервер согласия, выдающий его, и настоящий агент, совершающий вызовы инструментов. Единственное, что имитируется, — это данные о заказах (см. «Почему имитация» ниже).

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

Зачем это существует

ИИ-агенты теперь действуют от имени пользователей — проверяют статус заказа, оформляют возвраты, переводят деньги — используя учётные данные, которые делают их неотличимыми от человека, от имени которого они действуют. Сессионный cookie сводит три отдельных вопроса в один неразличимый 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-сервера -> автоматически применённый повтор -> успех) и выводит PASS/FAIL для каждой проверки. API-ключ не нужен — он никогда не вызывает LLM.

npm run agent запускает src/agent.ts: настоящий агент, созданный с помощью Claude Agent SDK, подключённый к src/server.ts как источник MCP-инструментов через stdio. Он выполняет три запроса — проверку заказа, оформление возврата $30 и оформление возврата $500 — и намеренно останавливается на ссылке авторизации на третьем. Эта пауза и есть суть: агент никогда не видит доказательство или удостоверение, он просто видит инструмент, который иногда просит его передать ссылку авторизации человеку. Требуется установленный ANTHROPIC_API_KEY (или аутентифицированная сессия CLI claude).

Что в каждом файле

Адаптация под ваш собственный MCP-сервер

Паттерн из kya-tools.ts обобщается на любой MCP-сервер:

1. Оберните идентичность вашего сервера: 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, а не электронная коммерция или платёжная инженерия, и реальная интеграция добавила бы поверхность обработки данных и безопасности без какой-либо пользы для этой истории.

Что здесь намеренно пока не охвачено

• Checkpoint (слой обнаружения агентского трафика от Vouched) — у него есть настоящая бесплатная самостоятельная регистрация, но это личное создание учётной записи, выходящее за рамки этого репозитория.

• Несколько фреймворков — в собственной документации Vouched перечислены Next.js, Express, Python, HTML и прямой API. Этот репозиторий только на Node/TypeScript; вариант на Express — естественный следующий шаг, учитывая, что API @kya-os/mcp не зависит от транспорта.

• IdentiClaw / KnowThat.ai — два других слоя набора KYA от Vouched; их публичная документация пока скудна.

На чём основано

@kya-os/mcp — эталонная реализация KYA-OS для Model Context Protocol под лицензией MIT, переданная Vouched в рабочую группу Trusted AI Agents при Decentralized Identity Foundation.