Перейти к основному содержимому
РУКОВОДСТВО

Как дать ИИ-агентам структурированный путь через ваше приложение

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

Toshendra Sharma

Автор Toshendra SharmaОснователь и CEO, AgentCredia · Updated November 13, 2026

Средний · 10 мин чтения

Зачем ИИ-агентам нужен другой путь через ваше приложение?

Растущая доля запросов к вашему приложению поступает от ИИ-агентов: ассистентов, которые получают документацию для пользователя, исследовательских инструментов, читающих страницы продукта, автономных рабочих процессов, вызывающих ваш API. Большинство из них работает через интерфейсы, созданные для людей. Они загружают полные HTML-страницы, разбирают макеты, следуют навигации, рассчитанной на мышь, и повторяют попытку, когда страница с большим количеством скриптов не отрисовывается так, как они ожидают.

Это неэффективно для всех. Агенты получают шумный контент и ошибаются. Ваши серверы тратят ресурсы на рендер страниц, которые никто не смотрит. А трафик трудно интерпретировать, потому что он выглядит как браузер, который ведет себя странно. Если вы пока не уверены, какова доля такого трафика, начните с как определить, поступает ли трафик сайта от ИИ-агентов.

Лучший подход - дать агентам структурированный путь: контент и действия в форматах, созданных для программ, доступных в стандартных местах, с лимитами, которые вознаграждают клиентов, корректно идентифицирующих себя. Это руководство показывает, как сделать это, не создавая второе приложение.

Шаг 1: Решите, что агенты должны уметь делать

Начинайте с намерения, а не с технологии. Посмотрите на маршруты, где вы уже видите трафик агентов, и сгруппируйте их:

  • Чтение контента: документация, сведения о продукте, страницы с ценами, статьи помощи, публичные профили.
  • Запрос данных: поиск, просмотр каталога, доступность, статус.
  • Выполнение действий: создать, обновить или удалить что-то от имени пользователя.

Чтение и запросы данных - хорошие кандидаты на структурированный путь, открытый любому корректно работающему клиенту. Действия требуют аутентификации и авторизации независимо от того, как клиент себя идентифицирует, и это рассматривается в руководстве по защите чувствительных действий.

Шаг 2: Предложите форматы, удобные для машин

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

  • Markdown для текстового контента, такого как документация и статьи, обслуживаемый с типом медиа text/markdown, зарегистрированным в RFC 7763. Он сохраняет заголовки, списки, ссылки и блоки кода, и он компактен.
  • JSON для структурированных записей, таких как продукты, тарифы или статус.

Используйте content negotiation, чтобы URL оставался тем же, а клиент запрашивал нужный формат:

TS
import express from "express";

const app = express();

app.get("/docs/:slug", async (req, res) => {
  const doc = await loadDoc(req.params.slug);
  if (!doc) return res.status(404).end();

  res.vary("Accept");
  const preferred = req.accepts(["text/html", "text/markdown", "application/json"]);

  if (preferred === "text/markdown") {
    return res.type("text/markdown; charset=utf-8").send(doc.markdown);
  }
  if (preferred === "application/json") {
    return res.json({ title: doc.title, updatedAt: doc.updatedAt, body: doc.markdown });
  }
  return res.render("doc", { doc });
});

Отправляйте заголовок Vary: Accept (RFC 9110 on Vary) чтобы кеши хранили каждое представление отдельно. Многие команды также открывают явный альтернативный URL, например добавляя .md к пути документации, потому что некоторым клиентам так проще, чем negotiation. Связывайте его с HTML-страницы через <link rel="alternate" type="text/markdown" href="...">, чтобы его можно было обнаружить. Такие типизированные ссылки следуют модели Web Linking.

Шаг 3: Как агенты находят ваш структурированный путь?

Агенты не могут использовать то, что не могут найти. Публикуйте точки входа в местах, где автоматизированные клиенты уже ищут:

  1. /llms.txt в корне сайта: короткое Markdown-резюме того, что предлагает ваш сайт, со ссылками на самые полезные страницы и их структурированные версии, в соответствии с предложением llms.txt.
  2. Описание API, например документ OpenAPI, связанный из вашей документации для разработчиков и из /llms.txt.
  3. Альтернативные ссылки в HTML-страницах, ведущие к версиям Markdown или JSON.
  4. Карта сайта со списком канонических URL вашего контента, в формате, определенном протоколом Sitemaps.

Минимальный llms.txt:

MARKDOWN
# Example App

> Example App helps teams plan projects. This file lists the best entry points for automated clients.

## Docs
- [Getting started](https://example.com/docs/getting-started.md): setup in five steps
- [API reference](https://example.com/openapi.json): OpenAPI description of the public API

## Policies
- [Automated access](https://example.com/docs/automated-access.md): limits and how to sign requests

Сделайте страницу, которая объясняет ваши правила для автоматизированных клиентов: какие маршруты открыты, какие лимиты применяются и как клиент может идентифицировать себя с помощью подписанных запросов, чтобы получить лучшее обслуживание. Понятные правила превращают догадки в сотрудничество.

Шаг 4: Маршрутизируйте по классу актора, а не по строке user agent

Когда у вас есть структурированные ответы, решите, кому они достаются по умолчанию. Используйте класс актора и его основание, а не разбор строк user agent по месту. Операторы ИИ действительно публикуют свои user agent, как это делают OpenAI и Anthropic для своих crawlers и fetchers, но совпадение по строке все еще остается только заявлением.

TS
type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";

function preferStructured(actor: ActorClass, basis: Basis, accept: string): boolean {
  if (accept.includes("text/markdown") || accept.includes("application/json")) return true;
  return actor === "agent" && (basis === "verified" || basis === "declared");
}

Два принципа помогают сохранить безопасность:

  • Явные запросы всегда имеют приоритет. Если клиент запрашивает Markdown или JSON, отдавайте его, независимо от класса.
  • Настройки по умолчанию ничего не отнимают. Посетитель класса Human или Unknown всегда получает полную страницу. Выбор структурированного формата по умолчанию для агентов меняет формат, а не то, что им разрешено видеть.

Шаг 5: Какие rate limits следует давать ИИ-агентам?

Rate limits - это область, где контекст актора приносит наибольшую практическую пользу. Вместо одного лимита для всех задайте для каждой комбинации класса и основания разумный бюджет:

Actor and basis Read routes Notes
Agent, verified Higher limit Operator is identifiable and accountable
Agent, declared or inferred Standard limit Claims are not checkable
Unknown Standard limit Never punitive by default
Human or Human + AI Standard limit Interactive use rarely approaches limits

Привязывайте лимит к самому стабильному доступному идентификатору. Для verified agents это origin оператора и идентификатор ключа. Для остальных используйте credential или ключ на уровне сети.

TS
function limitKey(actor: { actor: ActorClass; basis: Basis; operator?: string }, ip: string, apiKey?: string) {
  if (actor.actor === "agent" && actor.basis === "verified" && actor.operator) return `op:${actor.operator}`;
  if (apiKey) return `key:${apiKey}`;
  return `ip:${ip}`;
}

function limitFor(actor: { actor: ActorClass; basis: Basis }): number {
  if (actor.actor === "agent" && actor.basis === "verified") return 600;
  return 120;
}

Числа здесь - заполнители. Задайте свои на основе наблюдаемого базового уровня. Когда клиент превышает лимит, возвращайте 429 Too Many Requests с заголовком Retry-After и ссылкой на вашу страницу автоматизированного доступа. Хорошо построенные агенты снижают нагрузку и читают ее.

Шаг 6: Оставляйте действия за авторизацией

Структурированный путь для чтения - это не путь в обход вашей модели безопасности. Любое действие, изменяющее данные, по-прежнему требует:

  1. аутентификации с credential, выданным вашим приложением,
  2. авторизации для этого конкретного действия, и
  3. любых дополнительных проверок, которые требует уровень риска маршрута.

Проверенная подпись показывает, какой клиент вызывает запрос. Она не показывает, что клиент может действовать от имени конкретного пользователя. Держите эти вопросы отдельно. Наш материал что доказывают подписанные запросы ИИ-агентов объясняет разницу.

Шаг 7: Измерьте эффект

Сначала запускайте структурированный путь в режиме наблюдения, затем сравните:

  • долю запросов агентов, которые используют структурированные форматы,
  • стоимость серверов и задержку для трафика агентов до и после,
  • частоту ошибок и повторных попыток у клиентских агентов,
  • сколько автоматизированных клиентов переходят из declared в verified после публикации ваших рекомендаций по подписи.

Эти числа показывают, выполняет ли структурированный путь свою задачу и где его расширять дальше.

Шаг 8: Версионируйте и документируйте структурированный путь

Относитесь к структурированному пути как к публичному интерфейсу, потому что агенты будут строить работу на нем. Несколько привычек делают его надежным:

  1. Сохраняйте URL стабильными. Если агент узнал, что существует /docs/getting-started.md, он должен продолжать работать. Когда контент переезжает, возвращайте 301 на новое место, а не 404.
  2. Указывайте время обновления. Помещайте поле updatedAt в JSON-ответы и заголовок Last-Modified в Markdown, чтобы агенты могли разумно кешировать и обновлять данные только при изменениях.
  3. Поддерживайте conditional requests. Отвечайте на If-None-Match и If-Modified-Since с помощью 304 Not Modified. Агенты, которые опрашивают ваш контент, обходятся намного дешевле, когда могут перепроверять его, а не скачивать все заново.
  4. Версионируйте несовместимые изменения. Если форма JSON должна измениться, добавьте новый путь версии или media type и сохраните старый на опубликованный период.
  5. Публикуйте changelog для страницы автоматизированного доступа. Операторы корректно работающих агентов читают его, и он дает вам место для объявления новых структурированных маршрутов.
TS
app.get("/api/plans", async (req, res) => {
  const plans = await loadPlans();
  const etag = `"${plans.version}"`;
  res.set("ETag", etag);
  res.set("Cache-Control", "public, max-age=300");
  if (req.get("if-none-match") === etag) return res.status(304).end();
  return res.json({ updatedAt: plans.updatedAt, plans: plans.items });
});

Эти практики полезны и для вашего собственного frontend и партнерских интеграций. Структурированный путь, который стабилен, кешируется и документирован, быстро становится самым простым способом для любой программы работать с вашим приложением.

Распространенные ошибки

  • Отдавать агентам и людям разные факты. Структурированная версия должна содержать ту же информацию, что и страница. Расхождение в содержании сбивает с толку пользователей, которые спрашивают ассистента о вашем продукте.
  • Скрывать структурированный путь. Если на него нет ссылки из /llms.txt, вашей API documentation или самих страниц, агенты продолжат скрапить HTML.
  • Вознаграждать заявления. Более высокие лимиты положены verified clients. Скопированная строка user agent не должна давать больший бюджет.
  • Забывать про кеши. Без Vary: Accept кеш может отдать браузеру Markdown.

Где здесь место Proof of Actor

Proof of Actor дает вам класс актора и основание, которые нужны, чтобы направлять агентов на структурированный контент и устанавливать справедливые лимиты. Он определяет signed, declared и inferred agents, помогает понять, как они используют ваши маршруты, и оставляет решение о маршрутизации в вашем коде.

Чтобы спроектировать структурированный путь для вашего приложения вместе с нашей командой, подайте заявку на ранний доступ. Для сценариев API и MCP отдельно см. APIs и MCP Servers, а также прочитайте кто вызывает ваш MCP server? о том, как контекст актора применяется к вызовам инструментов Model Context Protocol.

Источники

Постройте это вместе с нами.

Присоединяйтесь к founding developer program Proof of Actor.

Получить ранний доступЦентр разработчиков

Предпочитаете сначала поговорить? Свяжитесь с основателями