Документация Make Agent Fast

Статус SDK

Выберите стабильный REST API или оцените предварительные клиенты только из исходников без предположения о доступности в реестре.

Кратко

Путь запроса APIОграниченный ключ → версионированный ресурс → подписанный ответ

REST доступенOpenAPIПредпросмотр SDK

Версионированный REST API — поддерживаемая публичная поверхность интеграции сегодня. Исходники клиентов JavaScript, Python и фреймворков существуют в репозитории продукта, но пакеты пока не опубликованы в npm или PyPI.

Доступность#

Клиент	Статус	Как использовать
REST поверх HTTPS	Доступен	Вызывайте `https://makeagent.fast/api/v1` из любого серверного HTTP-клиента
Документ OpenAPI	Доступен	Скачайте /api/openapi.json и изучите его перед генерацией клиента
`@make-agent-fast/sdk`	Предпросмотр исходников — не в npm	Не добавляйте этот импорт в продакшен-проект, пока релиз реестра не будет связан здесь
Пакет Python `makeagentfast`	Предпросмотр исходников — не в PyPI	Используйте `requests`, `httpx` или стандартную библиотеку Python, пока релиз PyPI не будет связан здесь
Адаптеры React, Vue, Svelte	Предпросмотр исходников — не в npm	Предпочитайте задокументированный паттерн загрузчика скрипта для фреймворка
Веб-компонент	Предпросмотр исходников — не в npm	Предпочитайте стандартный загрузчик `embed.js`

JavaScript без SDK#

const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);

Держите ключ API на сервере. Браузерный бандл React, Vue или Svelte должен вызывать ваш собственный бэкенд или устанавливать публичный загрузчик встраивания; он не должен вызывать API управления с секретом.

Python без SDK#

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])

Ловите urllib.error.HTTPError в продакшене и разбирайте его тело JSON, используя стабильную оболочку ошибок.

Сгенерированные клиенты#

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

curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json

Не регенерируйте и не развёртывайте клиента автоматически с живого URL. Новое добавочное поле не должно ломать клиента, но поведение генератора и имена сгенерированных методов всё равно могут меняться.

Что должен включать публичный релиз SDK#

Перед пометкой любого предварительного клиента как доступного у него должны быть:

Публичная страница реестра и неизменяемая семантическая версия.
Инструкции по установке, обновлению и поддерживаемым средам выполнения.
Типизированные модели запросов и ответов, сгенерированные из полного контракта API.
Структурированные ошибки, сохраняющие HTTP статус и ID запроса.
Помощники пагинации, трактующие курсоры как непрозрачные.
Явная поддержка ключей идемпотентности для мутаций.
Тесты CI против текущего контракта /api/v1 и опубликованный журнал изменений.

Пока эти условия не выполнены, используйте примеры REST в Быстром старте API и Рецептах API.