Три слоя машинного доступа регионального портала

Когда региональный информационный портал открывается ИИ-ассистентам, одной «умной страницы» недостаточно. Модели читают разные входы: кто-то подхватывает короткий текстовый файл, кто-то ищет визитку агента в стандартном месте, кто-то подключает живой инструментный сервер. Если эти входы смешать в одну простыню, ассистент начинает цитировать вчерашнюю цену как вечную истину — или, наоборот, уверенно договаривает фразу из памяти, хотя живые данные уже ответили: в базе этого нет.

Ниже — три слоя на примере информационного портала Ведар Камчатка (Vedar Kamchatka). Это не турагентство и не туроператор: портал публикует туры местных операторов, жильё, трансферы, прокат, статус безопасности и вулканов, погоду и планирование поездки. Для туриста он бесплатен. Заявка, оставленная через портал, — это заявка, а не бронь: её подтверждает человек, оплату турист передаёт исполнителю напрямую.

# три адреса — три роли
# https://vedarai.ru/llms.txt
#     статическая справка для модели
# https://vedarai.ru/.well-known/agent-card.json
#     обнаружение агента и разговорный вход
# https://vedarai.ru/api/mcp
#     живые инструменты, Streamable HTTP, без входа

Слой 1. Статическая справка: llms.txt

Что отвечает

Файл https://vedarai.ru/llms.txt — это краткая карта сайта для модели, рассчитанная на один проход. В нём сказано, чем портал является и чем не является, куда направлять коммерческий вопрос (человеческая витрина туров — каталог), как цитировать источники и что делать, если данных нет: прямо сказать, что нужна проверка на сайте. На том же домене есть более короткий английский файл /llms-en.txt. Слово «MCP» в этих текстах означает Model Context Protocol, а не партнёрскую программу.

Чего в нём быть не должно

Цены, свободные места и занятость на конкретную дату — живые данные. Их нельзя замораживать в статическом файле: карточка оператора обновляется, а файл начнёт врать в то же утро. Справка должна указать, где живёт актуальный ответ, и на этом остановиться.

Типичная ошибка интегратора

Вклеить в системный промпт фрагмент каталога «на сегодня» и больше не ходить за живым ответом. Вторая, не менее частая: пропустить политику использования и сочинить ссылку или факт, которого на портале нет.

Слой 2. Визитка A2A и разговорный вход

Что отвечает

Агентские среды ищут машиночитаемую визитку в предсказуемом месте. У Ведар Камчатки она лежит здесь: https://vedarai.ru/.well-known/agent-card.json. Визитка называет агента, указывает документацию на страницу MCP и ещё раз фиксирует границы: нет мгновенной брони, нет оплаты через гида, нет аутентификации. Поле схем безопасности пустое — ключ придумывать не нужно. Два интерфейса: JSON-RPC на https://vedarai.ru/api/a2a и HTTP+JSON на https://vedarai.ru/api/a2a/v1. Потоковой передачи и push-уведомлений нет: задача завершается в самом ответе.

На свободный вопрос по-русски или по-английски отвечает гид портала Кузьмич — теми же данными, что и MCP-сервер. В этом режиме заявки не создаются. Точный вызов инструмента можно передать структурированной частью вида {"tool": "<имя>", "arguments": {...}}, по схемам из tools/list на /api/mcp. Кузьмича можно спросить и на человеческой странице https://vedarai.ru/kuzmich.

Чего в визитке быть не должно

Тех же замороженных цен и мест. А вот ограничения — «заявка не бронь», «оплата не через портал» — в визитке как раз должны быть. Рантайм, который читает только /.well-known/, иначе их не увидит, даже если они аккуратно написаны в подвале главной страницы.

Типичная ошибка интегратора

Считать, что свободный вопрос Кузьмичу уже оформляет заявку. Не оформляет. Вторая ошибка — изобрести API-ключ, потому что «публичный эндпоинт без ключа кажется незаконченным». Третья — отменить задачу в протоколе разговора и решить, что отменена заявка оператору: это разные действия.

Слой 3. MCP-сервер: живые инструменты

Что отвечает

Публичный сервер на https://vedarai.ru/api/mcp работает по Streamable HTTP и JSON-RPC 2.0, без входа. Через него ассистент получает живые ответы той же базы, что видит человек на сайте: туры и занятость, безопасность мест и маршрутов, погоду, жильё, трансферы, прокат, черновик плана поездки. Документация и примеры подключения — на https://vedarai.ru/mcp. Клиенту, который умеет только stdio, страница предлагает мост с транспортом http-only. Устаревший транспорт SSE сервер не принимает.

Именно здесь живут цены и места — в ответе инструмента, на момент вызова, а не в файле. Если в базе нет строки, инструмент так и говорит. Заявку сервер тоже может принять, но это по-прежнему заявка: её подтверждает человек, мгновенной брони нет, оплаты через портал нет. Черновик плана поездки анонимен и до человека не доходит.

Чего через этот слой нельзя делать

Нельзя подменять ответ инструмента памятью модели. Нельзя объявлять туристу, что он уже забронирован или что деньги прошли через Ведар Камчатку. Нельзя зашить вчерашнюю занятость в системный промпт и считать её истиной на неделю.

Типичная ошибка интегратора

Подключить клиент с транспортом по умолчанию SSE и решить, что «сервер лежит». Или провести рукопожатие, но не передать модели инструкции из ответа initialize — и получить вежливого выдумщика с рабочим коннектором.

Как слои опираются друг на друга

Справка объясняет правила и указывает на живой вход. Визитка позволяет обнаружить агента и поговорить с ним, не раскрывая внутренности. MCP отдаёт инструменты тому ассистенту, который рассуждает сам. Путать их роли вредно: справка не заменяет запрос занятости, а живой вызов не отменяет обязанность прочитать ограничения.

Короткий чеклист перед запуском