Как выбрать подходящую поверхность
Не начинайте с того, чтобы отдавать агенту каждый эндпоинт FastNear. Сначала сформулируйте, какую задачу на самом деле хочет решить пользователь, а затем выберите один API или раздел справочника FastNear, который наиболее прямо отвечает на эту задачу.
Для агента важнее не вопрос «какой эндпоинт существует?», а вопрос «какой ответ поможет пользователю сделать следующий шаг?».
Что определяет маршрут
Прежде чем выбрать API, определите четыре вещи:
- Объект: аккаунт, публичный ключ, хеш транзакции, квитанция, блок, хранилище контракта или задача по настройке инфраструктуры.
- Форма ответа: сводка в продуктовой форме, история исполнения, канонический вывод протокола или инструкции для оператора.
- Свежесть: историческая, текущая или последняя / почти в реальном времени.
- Точность: достаточно индексированной сводки или требуется каноническая корректность в форме узла.
На практике:
- аккаунт плюс сводка обычно означают FastNear API
- аккаунт плюс точное каноническое состояние обычно означают Справочник RPC
- транзакция или квитанция обычно означают Транзакции API
- история только переводов обычно означает API переводов
- самые свежие блоки обычно означают NEAR Data API
- история ключей контракта обычно означает KV FastData API
- подъём узла обычно означает Снапшоты
Начните с намерения пользователя
- Если пользователю нужен ответ в стиле кошелька или обозревателя, предпочитайте индексированные API.
- Если пользователю нужно каноническое поведение протокола или точное состояние в форме узла, используйте сырой Справочник RPC.
- Если пользователю нужна история, квитанции или последовательности событий, используйте API, ориентированные на историю, прежде чем возвращаться к RPC.
- Если пользователю нужны самые свежие данные семейства блоков, используйте NEAR Data API для свежести, ориентированной на опрос.
- Если пользователю нужны инструкции по подъёму инфраструктуры, направляйте его к Снапшотам, а не к прикладным поверхностям запросов.
Порядок принятия решений
Используйте этот порядок перед выбором поверхности:
- Пользователь пытается поднять инфраструктуру, а не запрашивать данные цепочки? Если да — используйте Снапшоты.
- Пользователь просит сводку в продуктовой форме: балансы, NFT, стейкинг или активы аккаунта? Если да — начните с FastNear API.
- Пользователь спрашивает, что происходило со временем: транзакции, квитанции, переводы или история активности? Если да — начните с Транзакции API или с API переводов для вопросов только о переводах.
- Пользователю нужны самые свежие блоки или чтения семейства блоков с низкой задержкой? Если да — используйте NEAR Data API.
- Корректность зависит от канонического поведения узла, полей протокола или точного состояния в цепочке? Если да — используйте Справочник RPC.
- Пользователь спрашивает об истории индексированного хранилища «ключ–значение» или о последнем индексированном состоянии контракта? Если да — используйте KV FastData API.
Если подходит несколько поверхностей, выбирайте ту, которая даёт наиболее прямой полезный ответ с минимумом реконструкции со стороны агента.
Перед первым вызовом
Попробуйте определить эти входные данные до отправки запроса:
- сеть: mainnet или testnet
- первичный идентификатор: идентификатор аккаунта, публичный ключ, хеш транзакции, ID квитанции, высота / хеш блока, идентификатор контракта плюс ключ хранилища
- ожидаемый вывод: сводка, история, канонические поля или шаги оператора
- требование к свежести: последнее, финализированное, историческое или «что актуально сейчас»
Если чего-то не хватает:
- делайте небольшое предположение, когда вероятный стартовый API от этого не меняется
- задавайте уточняющий вопрос только тогда, когда неверный выбор существенно изменит результат
Направление типовых запросов пользователя
| Если пользователь говорит... | Вероятно, ему нужно... | Начните с | Переключайтесь, только если... |
|---|---|---|---|
| «Каково точное состояние аккаунта в цепочке?» | Каноническое состояние на уровне протокола | Справочник RPC | Также нужна сводка более высокого уровня для людей. |
| «Что принадлежит этому аккаунту?» | Балансы, NFT, стейкинг и активы в продуктовой форме | FastNear API | Нужны точные поля узла, которых нет в индексированном представлении. |
| «Какая активность затронула этот аккаунт?» | Индексированная история транзакций и квитанций | Транзакции API | Пользователю нужны только события переводов или требуется канонический протокольный уровень детализации. |
| «Покажи только переводы.» | История переводов по аккаунту | API переводов | Пользователю на самом деле нужен более широкий контекст исполнения транзакции. |
| «Что изменилось в последних блоках?» | Свежие оптимистичные или финализированные чтения семейства блоков | NEAR Data API | Нужны канонические детали RPC по конкретному блоку или чтению состояния. |
| «Какая история хранилища у этого контракта?» | Индексированная история состояния «ключ–значение» | KV FastData API | Нужно текущее каноническое состояние в цепочке, а не индексированная история. |
| «Почему эта транзакция упала?» | Сначала хронология исполнения, затем канонические детали | Транзакции API | Нужно подтверждение финального статуса протокола на уровне RPC или поведение при отправке транзакции. |
| «Как мне отправить транзакцию или посмотреть поле протокола?» | Каноническое поведение узла | Справочник RPC | Позже понадобится сводка по итоговому состоянию аккаунта или активности для человека. |
| «Как поднять узел или архивную установку?» | Инфраструктурный сценарий, а не данные приложения | Снапшоты | Пользователь затем начинает задавать прикладные вопросы о цепочке. |
Когда подсказкой служит идентификатор
Если формулировка пользователя размытая, но идентификатор ясен — пусть идентификатор задаст первый шаг:
| Если есть... | Первый шаг по умолчанию | Почему |
|---|---|---|
account_id | Начните с FastNear API для сводок или со Справочника RPC, если пользователь явно просит точное состояние | Вопросы по аккаунту обычно означают сначала балансы и активы, если пользователь не попросил канонический уровень. |
| публичный ключ | Начните с FastNear API для разрешения ключа в аккаунт | Обычно это задача обнаружения аккаунта, а не первой задачи на уровне RPC. |
| хеш транзакции | Начните с Транзакции API | Большинству пользователей нужен контекст исполнения и читаемая история, а не сырые поля протокола. |
| ID квитанции | Начните с Транзакции API | Трассировка квитанций уже индексирована там. |
| высота или хеш блока | Начните с NEAR Data API для мониторинга, ориентированного на свежесть, либо со Справочника RPC для точных канонических данных блока | Нужна либо свежесть, либо каноничность. |
| идентификатор контракта плюс ключ хранилища | Начните с KV FastData API для индексированной истории ключа или со Справочника RPC для точного текущего состояния в цепочке | Вопрос о хранилище обычно определяет, что важнее: индексированная история или каноническое состояние. |
| задача по подъёму узла или архива | Начните со Снапшотов | Это операторский сценарий, а не доступ к данным приложения. |
Для чего лучше всего подходит каждая поверхность
Справочник RPC
Используйте Справочник RPC, когда пользователю нужны точные данные или поведение на уровне протокола:
- точное состояние аккаунта, ключи доступа, валидаторы, чанки, блоки, метаданные протокола
- view-вызовы контрактов и отправка транзакций
- ответы, где имена и семантика полей должны быть максимально близки к узлам NEAR
Не стартуйте с RPC, когда пользователю на самом деле нужна аккуратная сводка по активам или истории. Это заставит агента пересобирать продуктовый ответ из данных более низкого уровня.
FastNear API
Используйте FastNear API, когда пользователю нужен ответ, уже похожий на данные приложения:
- балансы
- NFT
- позиции стейкинга
- поиск по публичному ключу
- объединённые снимки аккаунта
Обычно это первый шаг для запросов кошелька, портфеля, обозревателя и обзора аккаунта.
Транзакции API
Используйте Транзакции API, когда пользователю нужна история исполнения:
- активность аккаунта
- поиск транзакции
- трассировка квитанций
- история транзакций по блокам
Это поверхность истории по умолчанию, когда пользователь спрашивает «что произошло?», а не «что есть прямо сейчас?».
API переводов
Используйте API переводов, когда вопрос пользователя именно о событиях переводов, а не о полном контексте исполнения:
- входящие и исходящие переводы
- пагинация, ориентированная на переводы
- представления активности аккаунта только по переводам
Если пользователь начинает спрашивать про квитанции, действия кроме переводов или полное поведение транзакций — переходите в Транзакции API.
NEAR Data API
Используйте NEAR Data API, когда свежесть важнее сводки в продуктовой форме:
- оптимистичные или недавно финализированные блоки
- чтения последних блоков семейства
- явные сценарии с опросом
Не представляйте это как сервис на основе WebSocket или webhook. Это поверхность чтения, ориентированная на опрос.
KV FastData API
Используйте KV FastData API, когда вопрос об истории индексированного хранилища контракта или о последнем индексированном состоянии «ключ–значение»:
- анализ хранилища
- история ключей
- поиск состояния контракта, где уместна индексированная абстракция «ключ–значение»
Снапшоты
Используйте Снапшоты, когда сценарий связан с подъёмом инфраструктуры оператором:
- подъём mainnet или testnet
- инициализация RPC- или архивного узла
- операторские руководства
Это не путь прикладных запросов.
Ближайшие шаги после выбора
Как только выбрана стартовая поверхность, следующий шаг тоже должен быть предсказуемым:
| Выбранный API | Первое, что нужно сделать | Как выглядит успех | Расширяйтесь только если... |
|---|---|---|---|
| FastNear API | Выберите эндпоинт, соответствующий идентификатору или запросу на сводку | Можно сразу ответить на вопросы по балансам, активам, стейкингу или сводке аккаунта | Нужны точные канонические поля узла или подтверждение на уровне протокола |
| Справочник RPC | Выберите конкретный RPC-метод, соответствующий объекту и требуемому набору канонических полей | Можно вернуть поля на уровне протокола или выполнить точное действие по состоянию / отправке | Также нужна сводка более высокого уровня или индексированная история |
| Транзакции API | Начните с эндпоинта по хешу транзакции, квитанции, истории аккаунта или истории блока, подходящего под вопрос | Можно объяснить, что произошло и в каком порядке | Нужна точная семантика финальности или отправки на уровне RPC |
| API переводов | Запросите историю переводов для аккаунта или в нужном объёме актива | Можно отвечать на вопросы только о переводах без лишних деталей исполнения | Вопрос расширяется до квитанций, действий или полного контекста транзакции |
| NEAR Data API | Запросите последние оптимистичные или финализированные данные семейства блоков по требованию к свежести | Можно отвечать «что изменилось недавно?» или «каково последнее состояние семейства блоков?» | Нужно точное каноническое продолжение по блоку или состоянию |
| KV FastData API | Запросите последнее индексированное состояние «ключ–значение» или историю ключа | Можно отвечать на вопросы инспекции хранилища контракта в индексированном виде | Нужно точное текущее состояние в цепочке, а не индексированные представления хранилища |
| Снапшоты | Выберите нужную сеть и тип узла, затем следуйте руководству по подъёму | Можно дать операторские шаги, предусловия и ориентиры для подъёма | Пользователь переключается с настройки инфраструктуры на прикладные вопросы о цепочке |
Условия остановки перед расширением
Не расширяйтесь на второй API только потому, что он существует. Оставайтесь на первом API, когда:
- ответ уже соответствует ожидаемой пользователем форме
- текущий API уже отдаёт поля, которые просил пользователь
- пользователь просил историю и индексированная история уже получена
- пользователь просил сводку и сводка уже получена
Расширяйтесь, когда:
- пользователь явно просит каноническое подтверждение
- текущему API не хватает поля, свежести или детализации исполнения
- вопрос расширился с истории только переводов до общего поведения транзакций
- вопрос расширился со сводки до инспекции на уровне протокола
Комбинируйте поверхности, только когда это помогает пользователю
Хорошие шаблоны с несколькими поверхностями:
- Начните с FastNear API, затем опуститесь в Справочник RPC, если пользователь просит каноническое подтверждение.
- Начните с Транзакции API, затем используйте Справочник RPC, когда нужны финальные детали протокола по конкретной транзакции или квитанции.
- Начните с NEAR Data API для самых свежих блоков, затем используйте Справочник RPC для точной инспекции конкретного блока или запроса состояния.
- Начните с API переводов для вопросов только о переводах, затем расширяйтесь в Транзакции API, если пользователь просит больше контекста исполнения.
Плохой шаблон с несколькими поверхностями:
- Тянуть данные из нескольких поверхностей до того, как понятно, что именно нужно пользователю. Обычно это даёт более шумный ответ, а не более полезный.
Что агенту стоит вывести из типовых формулировок
- «Что есть у этого кошелька?» обычно означает балансы, NFT, стейкинг и, возможно, разрешение по публичному ключу. Начните с FastNear API.
- «Почему эта транзакция упала?» обычно означает, что пользователю сначала нужна читаемая история исполнения, а не сырой вывод протокола. Начните с Транзакции API.
- «Это точное состояние цепочки?» обычно означает, что каноническая корректность важнее удобства. Начните со Справочника RPC.
- «Что только что произошло в последнем блоке?» обычно означает, что главное требование — свежесть. Начните с NEAR Data API.
- «Как быстро поднять узел?» — это операторский сценарий. Начните со Снапшотов.
Частые ошибки маршрутизации
- Не начинайте с RPC только потому, что он канонический. Каноничность не равна полезности для каждой задачи пользователя.
- Не используйте снапшоты для прикладных чтений.
- Не описывайте NEAR Data API как поверхность потоковой передачи.
- Не расширяйтесь с истории переводов до полной истории транзакций, если вопрос пользователя сам не стал шире.
- Не уходите с индексированного API только потому, что существует сырой RPC. Переходите, только когда индексированного ответа недостаточно.
Если намерение пользователя неоднозначно
Когда пользователь формулирует размыто, делайте наименьшее полезное предположение о маршруте:
- «Проверь этот аккаунт» обычно стоит начинать с FastNear API — большинству пользователей нужна читаемая сводка по аккаунту.
- «Проверь эту транзакцию» обычно стоит начинать с Транзакции API — большинству пользователей нужен контекст исполнения, а не только поля протокола.
- «Проверь этот блок» можно начинать с NEAR Data API для мониторинга, ориентированного на свежесть, либо со Справочника RPC, когда пользователя явно интересует канонический вывод узла.
Если делаете предположение — кратко укажите его в ответе и идите дальше. Просите уточнения только тогда, когда выбор неверной поверхности существенно изменит результат.
Что агенту делать после первого результата
После возврата первого ответа:
- Проверьте, можно ли теперь ответить на вопрос пользователя напрямую.
- Если да — отвечайте в ожидаемой пользователем форме, а не собирайте дополнительные данные.
- Если нет — точно назовите недостающую часть. Примеры: каноническое подтверждение, более широкая история, более свежие данные семейства блоков, точное поле протокола или специфический контекст инфраструктуры.
- Только тогда переключайте API.
Цель — не доказать, что существует несколько API FastNear. Цель — ответить на следующий реальный вопрос пользователя за минимальное число необходимых шагов.
Связанные руководства
- Агенты на FastNear — полная карта поверхностей, базовые URL и подсказки по поглощению промптов.
- Аутентификация для агентов — работа с учётными данными и операционный режим.
- Плейбуки для агентов — примеры многошаговых сценариев.