Пошаговое руководство по курсу

Для кого: разработчики, строящие на AIMarket Protocol v2 — федеративный поиск, эскроу, платёжные каналы, подписанные квитанции и платные capability агентов. Язык лаб: COURSE_LANG=en|ru|es|fr|zh · строки UI в i18n/ · этот гайд на русском. English · Español · Français · 中文

Сверка с текущей экосистемой

В лабораторных используется эскроу-канал Hub-lite. Для рабочего Hub проверьте текущую платёжную политику: бесплатную пробу, кредит и доступные способы оплаты. На странице Start описаны кредит и пополнение. В упражнении x402 без оплаты откройте список наблюдаемых продавцов и сравните дату, сумму, актив, сеть и payTo с ответом на curl -sSI https://tienda.textokit.store/api/x402-ping. Список хранит прошлые котировки. Для прямого вызова действуют условия продавца.

Зачем этот курс

Большинство туториалов про «агентов» останавливаются на вызове одной модели. Этот курс — про слой выше: как агент находит чужую capability, платит за неё без транзакции в блокчейне на каждый вызов, доверяет результату через подписанную квитанцию и как провайдер публикует платный API, который покупают другие агенты. Это и есть экономика AIMarket Protocol v2 — поиск, эскроу, каналы, репутация, монетизация — и вы собираете её рабочий срез от начала до конца.

Каждая лаба работает с встроенным hub-lite (FastAPI-хаб в том же процессе), поэтому экономический поток — это реальный HTTP, а не мок, но без реальных денег и без git-клонов вплоть до capstone. Каждая лаба печатает лог событий Trace, чтобы цепочка поиск → оплата → вызов → квитанция была видна, а не была магией.

Содержание

Выбор трека
Установка (10 минут)
M1 — Обзор Protocol v2
M2 — SDK и интеграция с Hub
M3 — Эскроу и платёжные каналы
M4 — Репутация и доверие
M5 — Публикация capability
M6 — Capstone: платный цикл агента (продвинутый)
Упражнения и сертификат
Наблюдаемость в каждой лабе
Мост: от курса к боевому хабу
Чеклист самопроверки
Типичные проблемы

Выбор трека

Трек	Модули	Время	Зависимости	Hub
Hub-lite	M1 → M5	~2 ч	`[hub-lite,dev]`	Встроенный hub-lite (в процессе)
Продвинутый	Hub-lite + M6	+1 ч	`[sandbox,dev]`	Полный AIMarket Hub + SDK `aimarket-agent`
Боевой	После M5 или M6	+30 мин	Ваши ключи	Реальный федеративный хаб

Лабам M1–M5 нужен только [hub-lite] (~5 МБ, чистые pip-колёса). Capstone M6 добавляет extra [sandbox] (~50 МБ, git-клон SDK aimarket-agent и aimarket-hub). После каждой лабы смотрите блок Trace.

Установка (10 минут)

Шаг 1 — Клон и установка

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/agent-economy-course
pip install -e ".[hub-lite,dev]"

Для capstone (M6) добавьте extra sandbox:

pip install -e ".[sandbox,dev]"

Нужен Python 3.11+. При разработке внутри монорепы aicom sandbox сам находит соседние пакеты aimarket-agent/ и aimarket-hub/ — git-клон локально не требуется.

Шаг 2 — Тесты

pytest -q

В монорепе запускайте из каталога курса с заданным PYTHONPATH:

cd courses/agent-economy-course
PYTHONPATH=. python3 -m pytest -q

Ожидается: проходят тесты protocol, hub-lite, trust, упражнений и паритета i18n. Тесты economy/capstone выполняются только если импортируется SDK aimarket-agent, иначе чисто пропускаются.

Шаг 3 — Язык интерфейса лаб (опционально)

export COURSE_LANG=ru   # или es, по умолчанию en
python labs/lab01_protocol_overview.py

COURSE_LANG переключает все печатаемые строки лаб (заголовки, подписи полей, подсказки) по каталогам i18n/{en,ru,es,fr,zh}.json. Код, ID capability и команды остаются неизменными.

Шаг 4 — Google Colab

Откройте сайт курса → Open in Colab на любой лабе.
Выполните setup-ячейку (clone + pip).
При необходимости в setup-ячейке: os.environ["COURSE_LANG"] = "ru".
Запустите ячейку лабы.

M1 — Обзор Protocol v2

Концепция: возможности, квитанции и федеративный поиск начинаются с /.well-known/ai-market.json. Лаба: labs/lab01_protocol_overview.py · ~15 мин

Шаги

Прочитайте docstring в начале файла лабы.
python labs/lab01_protocol_overview.py
Что делает лаба:
- Поднимает встроенный hub-lite в процессе (~2 с).
- Запрашивает /.well-known/ai-market.json и валидирует через validate_well_known.
- Запрашивает manifest и валидирует через validate_manifest.
- Печатает имя примера инструмента и price_per_call_usd.
Откройте courselib/protocol.py — структурная валидация по формам aimarket-protocol/schemas/.

Самопроверка

[ ] Называете точку входа поиска (/.well-known/ai-market.json)
[ ] Понимаете, что проверяют validate_well_known и validate_manifest

Упражнение (M1): добавьте проверку поля в validate_well_known — python labs/run_exercises.py --module m1

M2 — SDK и интеграция с Hub

Концепция: регистрация, поиск и вызов платной capability через реальный хаб; получение подписанной квитанции. Лаба: labs/lab02_hub_discover.py · ~20 мин · нужен M1

Шаги

python labs/lab02_hub_discover.py

Проследите поток:

discover("translate") → invoke(prod-translate, translate.multi@v2) → receipt

Читайте поля: success, price, served by и nonce квитанции. Это повторяет боевой федеративный вызов без клонирования aimarket-hub.
Убедитесь, что события discover и invoke есть в блоке trace.

Самопроверка

[ ] Поиск возвращает метаданные capability (product_id/capability_id, цену)
[ ] Вызов возвращает структурированный результат и квитанцию с nonce

Упражнение (M2): найдите summarize и вызовите его — python labs/run_exercises.py --module m2

M3 — Эскроу и платёжные каналы

Концепция: удержание средств до доставки; поток микроплатежей без on-chain транзакции на каждый вызов. Лаба: labs/lab03_escrow_channel.py · ~20 мин · нужен M2

Шаги

python labs/lab03_escrow_channel.py
Жизненный цикл:
- Открыть предоплаченный канал с budget_usd=0.25.
- Вызвать через него summarize@v1.
- Закрыть канал и посмотреть spent против refund.
Две идеи:
- Платёжный канал — пакет микроплатежей без on-chain транзакции на каждый вызов.
- Эскроу — средства держатся до доставки; неиспользованный бюджет возвращается при закрытии.

Hub-lite отдаёт /ai-market/v2/channel/open и /close для демонстрации паттерна. Полный цикл SDK в M6 использует реальный стек эскроу хаба.

Самопроверка

[ ] Называете цикл: открыть → вызвать → закрыть → возврат
[ ] Канал амортизирует множество вызовов на один бюджет против 402 на каждый вызов

Упражнение (M3): откройте канал с бюджетом $1.00 и закройте его — python labs/run_exercises.py --module m3

M4 — Репутация и доверие

Концепция: подписанные квитанции делают платные вызовы проверяемыми и питают граф репутации в стиле LUMEN. Лаба: labs/lab04_reputation_trust.py · ~25 мин · нужен M2

Шаги

python labs/lab04_reputation_trust.py
Две проверки:
- Настоящая квитанция проходит как True и повышает оценку доверия продукта.
- Копия после tamper_receipt(..., price_usd=0.0) проходит как False и понижает её.
Строительные блоки:
- courselib.trust.sign_receipt / verify_receipt — учебные квитанции HMAC-SHA256 (stdlib, та же идея, что в проде).
- TrustGraph — изменения оценки в стиле LUMEN в памяти.
- Hub /ai-market/v2/trust/record — демо федеративного хука доверия.

Самопроверка

[ ] Объясняете, почему подделанная цена не проходит проверку
[ ] Видите, как проверенные и подделанные вызовы двигают оценку доверия в разные стороны

Упражнение (M4): подпишите свою квитанцию своим секретом и проверьте её — python labs/run_exercises.py --module m4

M5 — Публикация capability

Концепция: выпуск metered API, который покупают другие агенты — сторона провайдера. Лаба: labs/lab05_publish_capability.py · ~20 мин · нужен M2

Шаги

python labs/lab05_publish_capability.py
Workflow провайдера:
- register_capability("prod-course", "sentiment.metered@v1", 0.007, ...).
- Перезапросить manifest и увидеть рост числа инструментов (before → after).
- discover("sentiment") находит новую capability.
- invoke от лица потребителя — читайте цену и nonce квитанции.
Убедитесь в событиях register, manifest, discover, invoke в trace.

Самопроверка

[ ] Регистрируете capability с ценой и описанием
[ ] Доказываете, что после регистрации она находится и вызывается

Упражнение (M5): зарегистрируйте свою capability и вызовите её — python labs/run_exercises.py --module m5

M6 — Capstone: платный цикл агента (продвинутый)

Концепция: полный автономный цикл hire() через реальный SDK aimarket-agent. Лаба: labs/lab06_paid_capability_capstone.py · ~45 мин · нужен [sandbox] (~50 МБ, один раз)

Шаги

Установите extra sandbox один раз (в Colab переиспользуйте сессию, если ранние лабы уже его поставили):
```
pip install -e ".[sandbox,dev]"
```
python labs/lab06_paid_capability_capstone.py
Полный цикл:
```
discover → open channel → invoke → signed receipt → settle → bill of materials
```
Лаба поднимает локальный AIMarket Hub и заглушку Factory в фоновых потоках, затем вызывает econ.hire("translate text to multiple languages") с бюджетом $3.00. Реальных денег нет.
Читайте bill of materials: задача, успех, ID канала, потрачено, версия протокола, capability по шагам и живые листинги ACEX.

Если SDK aimarket-agent не установлен, лаба определит это через sdk_available() и чисто пропустится с подсказкой — без падения. Лабы 1–5 и все упражнения работают без него.

Самопроверка

[ ] Называете полный цикл: discover → channel → invoke → receipt → settle
[ ] Понимаете, что capstone — единственная лаба, требующая [sandbox]

Упражнение (M6): запустите полный цикл hire() в песочнице или проверку платного вызова через hub-lite — python labs/run_exercises.py --module m6

Упражнения и сертификат

Каждый модуль 1:1 соответствует самодостаточной DIY-проверке (m1…m6). Запуск одной:

python labs/run_exercises.py --module m3

Запуск всех:

python labs/run_exercises.py

Печатает ✓ или ✗ по каждому модулю. Когда проходят все шесть — сгенерируйте сертификат:

python labs/run_exercises.py --certificate "Иван Петров" --lang ru   # или en / es

Создаётся certificate.html — откройте в браузере и Print → Save as PDF для PDF-копии. ID сертификата — это дайджест SHA-256 от имени + даты выдачи, а подписи и бейджи модулей локализованы для en/ru/es.

Наблюдаемость в каждой лабе

Каждая лаба строит courselib.orchestration.Trace и печатает его в конце. Виды событий:

well_known, manifest, discover, invoke
channel_open, channel_close
verify, register
hire, step, capital (только capstone)

Читайте блок trace, чтобы проследить экономическую историю — поиск → оплата → вызов → квитанция → расчёт — а не только финальный результат. Это «лог юнит-тестов» лабы: один неудачный вызов — одно событие trace, на которое можно указать.

Боевой путь — фабрика подключает OpenTelemetry + LangSmith, см. observability-langsmith.md (для курса не нужно).

Мост: от курса к боевому хабу

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

Задайте COURSE_HUB_URL=https://modelmarket.dev (или свой хаб).
Используйте courselib.economy.connect() вместо embedded_sandbox().
Те же методы SDK переносятся: discover, invoke, hire.
На боевом хабе платные вызовы нужно оплачивать. Возьмите ключ на modelmarket.dev/start, пополните его в USDC (от $0.01) и задайте COURSE_API_KEY=aimk_…: connect() передаёт его как X-API-Key, и каждый вызов оплачивается с предоплаченного баланса. Без ключа платный вызов отвечает payment_required и перечисляет способы оплаты.

Получите живой well-known и сравните с валидатором из M1:

curl https://modelmarket.dev/.well-known/ai-market.json

Прогоните через courselib.protocol.validate_well_known — те же структурные проверки из модуля M1 применимы к реальному хабу.

Чеклист самопроверки

[ ] pytest -q проходит локально
[ ] Запущены lab01–lab05 на треке [hub-lite]
[ ] Запущена lab06 с [sandbox] (или виден чистый пропуск, пока зависимости не стоят)
[ ] Все шесть упражнений проходят: python labs/run_exercises.py
[ ] Хотя бы одна лаба запущена с COURSE_LANG=ru или es
[ ] Прочитан блок trace, объясняете discover → invoke → receipt
[ ] Сгенерирован сертификат: --certificate "Имя"

Типичные проблемы

Проблема	Решение
`ModuleNotFoundError: fastapi` (или `uvicorn`/`httpx`)	Поставьте extras hub-lite: `pip install -e ".[hub-lite,dev]"`
`ModuleNotFoundError: aimarket_agent`	Lab 6 и тесты economy требуют стек sandbox: `pip install -e ".[sandbox,dev]"`. В монорепе убедитесь, что `aimarket-agent/` и `aimarket-hub/` есть как соседние каталоги.
Capstone печатает «Capstone пропущен»	Ожидаемо без SDK — поставьте `[sandbox]` и перезапустите. Не ошибка.
Таймаут hub-lite на первом запуске	Холодный старт ~2–5 с; перезапустите. CI ждёт `/.well-known/ai-market.json`.
Листинги capital дают 500 в sandbox	`AIFACTORY_DATA_ROOT` должен указывать внутрь временного каталога sandbox — `embedded_sandbox()` ставит это автоматически.
`ModuleNotFoundError: courselib`	Запуск из корня репозитория; лабы добавляют родительский каталог в `sys.path`.
Ключ виден как `modules.m1.title`	Нет перевода — проверьте паритет ключей `i18n/en.json` (контролирует `tests/test_i18n.py`).
В Colab старый код	Перезапустите setup-ячейку; пиньте ветку `main`.

Проблемы Factory: FAQ.ru.md

Обновление сайта и ноутбуков

После правок лаб или каталогов i18n:

python3 scripts/build_course_assets.py

Гайды в docs/ правятся вручную — сначала EN, затем зеркала RU/ES.

Дальше: изучите спецификацию AIMarket Protocol и подключите свою metered capability к реальному хабу.