Агентные сервисы — это следующий шаг после «обычных» AI-ботов. Они не просто отвечают на вопросы, а сами инициируют действия: проверяют данные в блокчейне, формируют транзакции, запускают сценарии в смарт-контрактах. Экосистема Fetch.ai как раз про это: сеть автономных агентов, собственный блокчейн и инструменты для сборки сервисов поверх Web3.

В этом практическом руководстве по Fetch.ai мы разберем пошаговую сборку AI-агента с полноценной RAG-архитектурой и интеграцией ончейн-действий в блокчейн. Гайд подойдет как для знакомства с агентивными системами Web3, так и для создания продакшн-решений.

1. Что такое Fetch.ai и как работает агентная сеть

Fetch.ai задумывался как платформа для децентрализованной цифровой экономики на базе AI-агентов. Агент здесь — это программа, которая действует от имени пользователя или сервиса: общается с другими агентами, запрашивает данные, заключает сделки и взаимодействует со смарт-контрактами.

У проекта есть собственный блокчейн (Fetch Ledger), реестр агентов (Almanac), система имён Fetch Name Service и инфраструктура для регистрации, поиска и вызова агентов. Подробно о сети и токене FET мы уже писали в материале «Fetch.ai: сеть AI-агентов и токен FET» — здесь сосредоточимся на практической стороне.

1.1. Архитектура Fetch.ai для Web3 разработчиков

Если упростить, стек Fetch.ai для сборки агентного сервиса выглядит так:

• Блокчейн-слой — собственный L1, где фиксируются аккаунты, транзакции, записи об агентах и сервисах.
• uAgents / Agent SDK — Python-фреймворк для написания автономных агентов: с адресацией, диалоговыми протоколами и встроенной поддержкой криптографии.
• Agentverse — облачная платформа и маркетплейс для деплоя агентов без поднятия своей инфраструктуры.
• LLM-слой — в том числе собственная модель ASI-1 Mini, адаптированная для агентных сценариев и многошагового рассуждения.

Всё это дополняется оркестрационным уровнем, описанным в архитектуре Fetch.ai: там агенты объединяются в сложные многокомпонентные сценарии и взаимодействуют друг с другом через общий протокол.

2. Цель гайда: агент с RAG и ончейн-действиями

Чтобы не оставаться в теории, зафиксируем конкретный use case. Мы хотим собрать агентного помощника для Web3-проекта, который умеет:

• отвечать на вопросы по документации, whitepaper’у и FAQ с помощью RAG (retrieval-augmented generation);
• готовить и запускать простые ончейн-сценарии: формировать транзакцию, подписываемую пользователем, или вызывать метод смарт-контракта по шаблону;
• работать в фоне: следить за событиями в сети и реагировать на них (например, уведомлять о наступлении условия и предлагать действие).

Такие «agentic RAG»-системы активно обсуждаются на рынке: это не просто чатбот, а агент, который сам решает, когда доставать контекст, какие документы читать и когда переходить к действию.

3. Архитектура сервиса: RAG + uAgent + ончейн-адаптер

Разобьём будущий сервис на четыре слоя, чтобы не запутаться:

1. Хранилище знаний — векторная БД с вашей документацией (docs, wiki, FAQ, переписка саппорта). Тут можно использовать любой удобный стек: от локального Chroma до Qdrant / Weaviate.
2. LLM + RAG-обвязка — функция, которая принимает вопрос пользователя, достаёт релевантные куски из векторки и передаёт всё в модель (ASI-1 Mini, OpenAI, локальная LLM и т.п.).
3. uAgent на Fetch.ai — «мозг» сервиса: принимает сообщения, решает, когда вызывать RAG, когда проверять ончейн-состояние и какой следующий шаг сделать.
4. Ончейн-адаптер — модуль, который умеет читать события из блокчейна и формировать транзакции (через SDK нужной сети, аппаратный кошелёк или кастомный backend).

В качестве LLM для RAG можно использовать не только внешние API, но и локальные модели. Если вы хотите тестировать всё в «песочнице», удобно взять локальный LLM-стек через Ollama и поднять модель прямо на dev-станции, чтобы не зависеть от внешних лимитов.

4. Подготовка окружения разработчика

Fetch.ai активно продвигает Python-стек, так что минимальные требования выглядят довольно привычно:

• Python 3.10+;
• установленный пакетный менеджер pip или poetry;
• учётная запись в экосистеме Fetch.ai (для доступа к тестовой сети и Agentverse);
• библиотека uagents и CLI-утилиты Agentverse (если планируете деплой в облако).

Типичный стартовый набор команд (упрощённо):

python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install uagents 

Разработчикам, уже знакомым с агентными фреймворками вроде LangChain, LangGraph и др., будет полезно освежить базовые принципы в нашем обзоре «агентных конструкторов» — мы как раз сравнивали подходы Fetch.ai с другими игроками.

5. RAG-пайплайн: превращаем документацию в базу знаний

RAG (retrieval-augmented generation) — это архитектура, в которой LLM не отвечает «из головы», а сначала ищет информацию в вашем хранилище знаний, а затем уже генерирует ответ с опорой на найденные документы. Для агентных сценариев RAG стал де-факто стандартом: иначе агент быстро начинает «галлюцинировать».

5.1. Готовим данные

На первом шаге нужно собрать и привести к единому формату всё, на чём будет «думать» агент:

• официальную документацию проекта (Markdown, HTML, PDF, Notion и т.д.);
• FAQ техподдержки и статьи базы знаний;
• описания смарт-контрактов (ABI, комментарии к методам, схемы транзакций);
• регламенты и внутренние инструкции, которые можно показывать пользователю.

Дальше вы нормализуете текст: чистите от навигации, делите на фрагменты (chunks) по 500–1000 токенов и сохраняете вместе с метаданными (название документа, раздел, версия). Многие библиотеки для RAG делают это «из коробки», так что на этом этапе достаточно следовать их best practices.

5.2. Индексация во векторное хранилище

Для RAG-агента на Fetch.ai нет принципиальной разницы, где физически лежит векторное хранилище: оно может жить рядом с агентом (локальный контейнер), в отдельном микросервисе или в управляемом облаке. Важно лишь обеспечить API для:

• записи векторов с метаданными (индексация);
• поиска k ближайших векторов по запросу (similarity search);
• обновления/удаления записей при изменении документации.

С точки зрения бюджета RAG — одно из самых «прожорливых» мест: и эмбеддинги, и сами ответы модели стоят денег или ресурсов. Важно сразу заложить лимиты по длине контекста и количеству документов, которые вы подтягиваете на один запрос.

5.3. RAG-функция как отдельный сервис

Хорошая практика — вынести собственно RAG в отдельную функцию/сервис, который можно использовать и без агента. Это упрощает тестирование и даёт возможность подключать другие интерфейсы (чат-виджет на сайте, API для партнёров и т.д.). Примерно это выглядит так:

1. Агент принимает вопрос пользователя.
2. Формирует поисковый запрос к векторному хранилищу.
3. Получает список релевантных фрагментов с метаданными.
4. Передаёт вопрос и фрагменты в LLM с промптом вида «ответь, опираясь только на эти документы».
5. Возвращает пользователю ответ + ссылки на источники.

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

6. Пишем базового агента на uAgents

uAgents — это Python-фреймворк Fetch.ai для автономных агентов. Агент представляет собой программу с адресом, криптографическим ключём и набором обработчиков сообщений. Он может сам инициировать диалоги, реагировать на события, запускать фоновые задачи.

В самом простом виде «каркас» агента выглядит как-то так (упрощённый псевдокод):

from uagents import Agent, Context, Bureau, Protocol agent = Agent( name="rag_onchain_agent", seed="<secure-seed>", ) @agent.on_event("startup") async def startup(ctx: Context): ctx.logger.info("Agent is up and running!") @agent.on_message(model=UserQuery) async def handle_user_query(ctx: Context, sender: str, msg: UserQuery): # здесь мы позже вызовем RAG и/или ончейн-адаптер answer = await run_rag_pipeline(msg.question) await ctx.send(sender, AgentReply(text=answer)) bureau = Bureau() bureau.add(agent) bureau.run() 

Реальные агенты Fetch.ai используют строгие протоколы сообщений и типизацию (pydantic-модели), что облегчает композицию сложных мульти-агентных сценариев. Но для первого сервиса достаточно уметь принимать запрос, вызывать RAG и отправлять ответ.

7. Соединяем агента с RAG-функцией

Теперь добавим в агента вызов RAG-сервиса. Главное — не тянуть всю логику внутрь обработчика сообщений, а вызывать заранее подготовленную функцию/клиент. Это позволяет:

• перезапускать и масштабировать RAG независимо от Fetch-агента;
• заменять модель или векторное хранилище без переписывания агентного кода;
• переиспользовать RAG-функцию в других интерфейсах.

В типичном сценарии обработчик делает следующее:

1. логирует запрос и метаданные (ID пользователя, источник);
2. передаёт вопрос в RAG-API и ждёт ответ (с таймаутом);
3. если таймаут или ошибка — возвращает пользователю аккуратное сообщение, не раскрывая внутренних деталей;
4. иначе — отправляет ответ + цитаты/ссылки на источники.

На этом этапе ваш агент уже полезен: он умеет отвечать на вопросы по документации и может работать в Agentverse как «FAQ-помощник» для проекта.

8. Добавляем ончейн-действия: события и транзакции

Следующий шаг — научить агента работать с блокчейном. Экосистема Fetch.ai сама использует on-chain события и данные: в документации подробно показываются примеры, как агенты реагируют на события в сети и используют внешние данные (через интеграции вроде SQD, Infura и др.).

Нам нужно решить две задачи:

1. отслеживать интересующие события (например, изменение состояния смарт-контракта или приход средств на адрес);
2. по запросу пользователя формировать транзакции и передавать их в кошелёк/бекенд для подписи.

8.1. Подписка на on-chain события

Проще всего вынести подписку на события в отдельный сервис, который будет:

• подключаться к RPC нужной сети;
• слушать события смарт-контракта (через eth_getLogs или gRPC-подписки);
• при наступлении условия отправлять сообщение в агента Fetch.ai.

Агент в таком случае получает уже «чистое» сообщение: например, PositionRiskIncreased или ThresholdReached. Это удобнее, чем разбираться с сырыми логами внутри него.

8.2. Формирование транзакций

Ключевой принцип безопасности: агент не должен бесконтрольно распоряжаться средствами пользователя. На практике удобно разделить роли:

• агент готовит данные для транзакции (адрес, метод, параметры, максимум газа);
• кошелёк пользователя (или бекенд-подписант) показывает транзакцию, и человек окончательно подтверждает действие;
• агент лишь отслеживает результат и, при необходимости, делает follow-up (например, сообщает об успехе или ошибке).

Такой паттерн хорошо стыкуется с другими агентными фреймворками для Web3, где LLM-агент генерирует рекомендации, но финальное действие всё равно остаётся за пользователем или специализированным модулем с жёсткими лимитами.

9. Деплой в Agentverse: выводим агента в прод

Когда базовый функционал работает локально, пора думать о проде. Тут в ход идёт Agentverse — облачная платформа Fetch.ai для деплоя и маркетинга агентов. Она позволяет:

• запускать агента в управляемом окружении без поднятия собственного сервера;
• регистрировать его в общем каталоге (Almanac), чтобы другие агенты и пользователи могли его найти;
• собирать статистику обращений, конверсий и отзывов — по сути, «SEO для агентов».

Путь в общих чертах такой:

1. Вы готовите Docker-образ или конфиг агента по требованиям Agentverse.
2. Загружаете проект через веб-интерфейс или CLI.
3. Заполняете метаданные: название, описание, категории, ожидаемые сценарии использования.
4. Регистрируете агента в каталоге, после чего он становится доступен для вызовов извне.

Agentverse постепенно превращается в «маркетплейс агентных сервисов» — логично стремиться, чтобы ваш RAG + ончейн-агент был там не просто запущен, но и хорошо оформлен: с понятным описанием, сценариями, демо-скринами и примерами запросов.

10. Бюджет и наблюдаемость: контролируем затраты

У агентных сервисов два основных источника затрат:

• AI-компонента — вызовы LLM, построение эмбеддингов, хранение вектора;
• блокчейн-часть — gas за транзакции, хранение данных, работа индексеров.

Чтобы бюджет не «улетал» незаметно, стоит сразу заложить:

• ограничения на длину запросов и количество документов в контексте;
• rate-limit на количество запросов в единицу времени (per user / per agent);
• жёсткие лимиты на стоимость транзакций и типы ончейн-действий;
• метрики и алертинг по расходу токенов/кредитов на LLM и по gas-затратам.

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

11. Типичные ошибки при запуске агентных сервисов на Fetch.ai

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

11.1. Одноточечный монолит вместо модульной архитектуры

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

11.2. Отсутствие guardrails для LLM

Если агент напрямую транслирует ответы модели без фильтров и проверок, вы очень быстро столкнётесь с галлюцинациями, некорректными инструкциями и странными рекомендациями. Минимальный набор guardrails: ограничение источников (только ваши документы), проверка уверенности, запрет на определённые типы действий и словарей.

11.3. Слишком много ончейн-магии

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

11.4. Игнорирование UX и обратной связи

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

12. Чек-лист перед первым прод-релизом

Сведём ключевые шаги в удобный чек-лист.

• RAG-пайплайн собран и протестирован на реальных вопросах из саппорта/сообщества.
• Векторное хранилище стабильно выдерживает нагрузку и имеет бэкапы.
• uAgent обрабатывает все основные сценарии: вопросы, события, запросы на действия.
• Ончейн-адаптер отделён от агента, есть понятный процесс подписи и отправки транзакций.
• Везде, где это критично, используются guardrails и ограничения (лимиты, фильтры, whitelists).
• Подключён мониторинг расхода на LLM и gas, настроены алерты по аномалиям.
• Агент развернут в Agentverse и корректно отображается в каталоге.
• Есть документация для команды и для пользователей: что умеет агент, чего делать не будет и какие есть ограничения.

FAQ: 5 вопросов про Fetch.ai, RAG и ончейн-агентов

Полезные материалы по теме

• Оптимизация стоимости LLM и ML-нагрузок — пригодится при расчёте бюджета агентного сервиса.
• Ritual: AI-сопроцессор для смарт-контрактов — дополняет стек Fetch.ai, если вам нужны ИИ-вычисления прямо в ончейн-логике.