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

Рецепты API

Автоматизируйте полные процессы сайта, агента, знаний, публикации и отчётности.

Кратко

Автоматизируйте полные процессы сайта, агента, знаний, публикации и отчётности.

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

СоздатьОбосноватьОпубликовать

Эти рецепты используют сырой REST, чтобы работать до установки публичного SDK. Установите MAF_API_KEY в окружении сервера и заменяйте ID, возвращённые более ранними шагами.

Рецепт: создать и опубликовать обоснованного агента#

Создайте один ключ API с sites:write, agents:write и knowledge:write. Добавьте sites:read, если автоматизация также перечисляет или проверяет сайты.

1. Создайте сайт#

curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support",
      "subheadline": "Answers grounded in our current policies.",
      "about": "Acme support answers product and account questions."
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

Успешный ответ — 201 Created, включает сайт под data и возвращает его канонический путь ресурса в заголовке Location. Сохраните data.id как SITE_ID.

2. Настройте агента и политику встраивания#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'

Разрешённые origin — точные origin: схема, имя хоста и опциональный порт. Не включайте путь или завершающий шаблон.

3. Добавьте текстовый источник знаний#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'

Публичный API сейчас принимает вставленный текст от 5 до 200 000 символов. Используйте панель для сканирования URL, загрузок, YouTube, подкастов и лент.

4. Добавьте структурированный FAQ#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'

5. Опубликуйте#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'

Ответ должен содержать {"data":{"id":"...","status":"published"}}. Откройте реальное встраивание и задайте вопрос, ответ на который есть в источнике. Публикация доказывает, что состояние агента изменилось; она не доказывает, что качество источника или origin встраивания правильные.

Рецепт: безопасная пагинация заявок#

Используйте ключ с leads:read. Относитесь к next_cursor как к непрозрачному и URL-кодируйте его.

const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);

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

Рецепт: отключить встраивание во время инцидента#

Используйте agents:write и сохраняйте тот же ключ идемпотентности на сетевых повторах:

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'

После успеха ответа проверьте, что загрузчик больше не инициализируется на разрешённом хосте. Включите его снова новым ключом разрешения инцидента после исправления проблемы origin, контента или учётных данных.

Продакшен-чек-лист#

Используйте отдельный ключ на сервис и окружение.
Сохраняйте ID ресурсов и ключи идемпотентности перед отправкой мутации.
Устанавливайте таймауты соединения и ответа.
Соблюдайте Retry-After и ограничивайте повторы.
Логируйте имя операции, HTTP статус и ID запроса без логирования секретов или персональных данных.
Тестируйте против непродакшен-сайта перед предоставлением областей записи продакшену.