Плейбуки для агентов

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

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

Как использовать эти плейбуки

1. Сопоставьте запрос пользователя с ближайшим плейбуком ниже.
2. Соберите минимальные входы.
3. Сделайте первый запрос к рекомендуемому стартовому API.
4. Остановитесь, как только можете ответить в форме, которая реально нужна пользователю.
5. Расширяйтесь только под конкретное недостающее поле, требование к свежести или к каноничности.

Быстрая карта

Если пользователю нужно...	Начните с...	Расширяйтесь, только если...
балансы, активы, стейкинг или сводка аккаунта в стиле кошелька	FastNear API	требуются точные канонические поля узла
история транзакций, квитанций или исполнения по аккаунту	Транзакции API	требуется точный статус или семантика отправки на уровне RPC
история только переводов	API переводов	вопрос выходит за рамки переводов
последние оптимистичные или финализированные блоки	NEAR Data API	требуется точное каноническое продолжение по блоку или состоянию
индексированное состояние ключей контракта или история ключей	KV FastData API	требуется точное текущее состояние в цепочке
подъём узла или настройка оператором	Снапшоты	задача уходит обратно к прикладным данным цепочки

Если до сих пор непонятно, какой плейбук подходит — сначала используйте Как выбрать подходящую поверхность.

Сводка и активы аккаунта

Используйте, когда пользователь говорит «проверь этот аккаунт», «что хранит этот кошелёк», «какие NFT у этого аккаунта» или «какому аккаунту принадлежит этот ключ?».

Минимальные входы

• сеть
• account_id или публичный ключ
• хочет пользователь широкую сводку или один конкретный класс активов

Начните здесь

• Полный снимок аккаунта V1 для широкой сводки аккаунта
• Поиск по публичному ключу V1, если стартовый идентификатор — публичный ключ
• Индекс FastNear API, когда сначала нужно выбрать более узкий эндпоинт

Последовательность по умолчанию

1. Если стартовый идентификатор — публичный ключ, разрешите его в один или несколько account_id через Поиск по публичному ключу V1.
2. Возьмите самое широкое полезное представление аккаунта через Полный снимок аккаунта V1.
3. Если пользователь просит только одно семейство активов или нужна более узкая детализация — переходите к целевым эндпоинтам: балансы FT-токенов, активы NFT или позиции стейкинга.
4. Остановитесь, как только можете напрямую ответить на вопрос об активах.

Расширяйтесь, только если

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

Тогда расширяйтесь на Состояние аккаунта или другие страницы Справочника RPC.

Полезный ответ должен содержать

• определённую идентичность аккаунта
• балансы или активы, о которых спросил пользователь
• короткую пометку, что это индексированные сводные данные, а не сырое состояние RPC

Расследование транзакции или квитанции

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

Минимальные входы

• сеть
• хеш транзакции, ID квитанции или account_id
• нужна инспекция одного элемента или диапазон истории

Начните здесь

• Поиск транзакций для хеша транзакции
• Поиск квитанций для ID квитанции
• История аккаунта для активности по аккаунту

Последовательность по умолчанию

1. Выберите стартовый эндпоинт по уже известному идентификатору.
2. Запросите индексированную запись исполнения и восстановите историю в читаемом порядке.
3. Выделите статус, затронутые аккаунты, ключевые квитанции и контекст блока, если он существенен.
4. Остановитесь, если можете объяснить, что произошло, без канонического подтверждения через RPC.

Расширяйтесь, только если

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

Тогда расширяйтесь на Статус транзакции или другой подходящий метод Справочника RPC.

Полезный ответ должен содержать

• успех, неудачу или ожидание транзакции или квитанции
• сначала главный вывод исполнения, потом сырые поля
• путь продолжения — только если он добавляет ценность, например «используйте RPC для канонического подтверждения»

История только переводов

Используйте, когда пользователя интересует движение активов и не нужен более широкий контекст квитанций или действий.

Минимальные входы

• сеть
• account_id
• опциональные фильтры: токен, направление или временной интервал

Начните здесь

• Запрос переводов
• Индекс API переводов

Последовательность по умолчанию

1. Запросите историю переводов для нужного аккаунта и фильтров.
2. Используйте пагинацию только до такой глубины, которая реально нужна для ответа.
3. Сосредоточьте ответ на переводах и не пересобирайте полную историю транзакции.
4. Остановитесь, если пользователь спросил только кто, когда и какой актив отправил.

Расширяйтесь, только если

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

Тогда расширяйтесь на Историю аккаунта или другую страницу Транзакций API.

Полезный ответ должен содержать

• значимые входящие или исходящие события переводов
• предположения о фильтрах, которые были сделаны
• пометку, что это история переводов, а не полная история исполнения

Мониторинг свежих блоков

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

Минимальные входы

• сеть
• требование к свежести: оптимистичная или финализированная
• опционально — высота или хеш блока, если пользователь привязывается к конкретному блоку

Начните здесь

• Редирект на последний финализированный блок для последнего финализированного блока
• Оптимистичный блок по высоте, когда сценарий явно оптимистичный
• Заголовки блоков, когда достаточно опроса на уровне заголовков
• Индекс NEAR Data API, когда нужно выбрать между ними

Последовательность по умолчанию

1. Определите, нужна ли пользователю оптимистичная свежесть или финализированная стабильность.
2. Используйте помощника по последнему блоку или маршрут семейства блоков, соответствующий требованию к свежести.
3. Опрашивайте явно и в ответе чётко указывайте, какой режим свежести использован.
4. Остановитесь, если пользователю достаточно свежих данных семейства блоков и каноническое продолжение через RPC не требуется.

Расширяйтесь, только если

• пользователь просит точный канонический вывод блока
• пользователь хочет проверить состояние или поля протокола за пределами данных семейства блоков
• пользователю нужна точная семантика RPC для конкретного продолжения по блоку

Тогда расширяйтесь на Справочник RPC, обычно начиная с Блока по высоте или Блока по ID.

Полезный ответ должен содержать

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

Инспекция хранилища контракта

Используйте, когда пользователю нужна индексированная история ключей контракта, последнее индексированное состояние ключей или анализ хранилища контракта по ключу.

Минимальные входы

• сеть
• идентификатор контракта
• точный ключ, префикс ключа или область аккаунта / predecessor_id
• хочет пользователь последнее индексированное состояние или исторические изменения ключа

Начните здесь

• Последнее по точному ключу для одного точного ключа
• Индекс KV FastData API, когда вопрос шире одного ключа

Последовательность по умолчанию

1. Определите, хочет пользователь один ключ, семейство ключей или историю хранилища в разрезе аккаунта.
2. Запросите минимальное индексированное представление «ключ–значение», соответствующее этой области.
3. Если нужна история, а не последнее значение — оставайтесь внутри KV FastData API и переключайтесь на подходящий исторический эндпоинт.
4. Остановитесь, если индексированные данные «ключ–значение» уже отвечают на вопрос.

Расширяйтесь, только если

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

Тогда расширяйтесь на Просмотр состояния контракта в Справочнике RPC.

Полезный ответ должен содержать

• контракт и область ключа, которая была проинспектирована
• пометку, это последнее индексированное состояние или история ключа
• пометку, если каноническое состояние RPC отличается по свежести или семантике

Подъём узла и настройка оператором

Используйте, когда пользователь пытается поднять инфраструктуру, а не запросить данные цепочки.

Минимальные входы

• сеть
• тип узла, например RPC или архивный
• цель: скорость подъёма, восстановление синхронизации или операционный сценарий

Начните здесь

• Снапшоты

Последовательность по умолчанию

1. Сразу направляйте к подходящему снапшоту или операторскому руководству.
2. Сосредоточьте ответ на предусловиях, пути подъёма и следующих операционных шагах.
3. Не подтягивайте прикладные API, пока пользователь сам не сменит задачу.

Расширяйтесь, только если

• пользователь перестаёт спрашивать про инфраструктуру и начинает спрашивать про сами данные цепочки

Тогда возвращайтесь к Как выбрать подходящую поверхность и выбирайте нужный API данных.

Полезный ответ должен содержать

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

Общие правила для всех плейбуков

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

Если ни один плейбук не подходит чисто

Если запрос по-прежнему неоднозначен после этой страницы:

• используйте Как выбрать подходящую поверхность, чтобы выбрать первый API
• используйте Аутентификацию для агентов, если блокер — работа с учётными данными
• возвращайтесь к Агентам на FastNear за правилами рабочего цикла по умолчанию и формы ответа