Documentación de Make Agent Fast

Recetas de API

Automatiza flujos de trabajo completos de sitios, agentes, conocimiento, publicación e informes.

De un vistazo

Automatiza flujos de trabajo completos de sitios, agentes, conocimiento, publicación e informes.

Ruta de solicitudes de la APIClave con alcance → recurso versionado → respuesta firmada

CrearFundamentarPublicar

Estas recetas usan REST sin procesar, por lo que funcionan incluso antes de instalar un SDK público. Define MAF_API_KEY en el entorno del servidor y sustituye los IDs devueltos por los pasos anteriores.

Receta: crear y publicar un agente fundamentado#

Crea una clave de API con sites:write, agents:write y knowledge:write. Añade sites:read si la automatización también lista o verifica sitios.

1. Crear el sitio#

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"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

Una respuesta correcta es 201 Created, incluye el sitio en data y devuelve su ruta de recurso canónica en el encabezado Location. Guarda data.id como SITE_ID.

2. Configurar el agente y la política de incrustación#

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"]
  }'

Los orígenes permitidos son orígenes exactos: esquema, nombre de host y puerto opcional. No incluyas una ruta ni un comodín al final.

3. Añadir una fuente de conocimiento de texto#

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."
  }'

El texto pegado debe tener entre 5 y 200 000 caracteres. El mismo endpoint también puede rastrear un sitio web con { "url", "max_pages", "refresh_hours" } (max_pages hasta 40) o importar { "kind": "youtube" | "podcast" | "feed", "url" }; esas fuentes multimedia requieren Operate o Scale y devuelven 409 en Launch. La subida de archivos solo está disponible en el panel.

4. Añadir unas preguntas frecuentes estructuradas#

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. Publicar#

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}'

La respuesta debería contener {"data":{"id":"...","status":"published"}}. Abre una incrustación real y haz una pregunta cuya respuesta aparezca en la fuente. Publicar demuestra que el estado del agente cambió; no demuestra que la calidad de la fuente o el origen de la incrustación sean correctos.

Receta: paginar leads de forma segura#

Usa una clave con leads:read. Trata next_cursor como un valor opaco y codifícalo como 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);

No decodifiques, edites, ordenes ni reutilices un cursor en una colección distinta.

Receta: desactivar una incrustación durante un incidente#

Usa agents:write y conserva la misma clave de idempotencia en todos los reintentos por fallos de red:

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}'

Cuando la respuesta sea correcta, verifica que el lanzador ya no se inicializa en un host permitido. Vuelve a activarlo con una nueva clave de resolución del incidente después de corregir el problema de origen, contenido o credenciales.

Lista de verificación para producción#

Usa una clave distinta por servicio y por entorno.
Guarda los IDs de recursos y las claves de idempotencia antes de enviar una mutación.
Configura tiempos de espera de conexión y de respuesta.
Respeta Retry-After y limita el número de reintentos.
Registra el nombre de la operación, el estado HTTP y el ID de la solicitud, sin registrar secretos ni datos personales.
Prueba en un sitio que no sea de producción antes de conceder permisos de escritura en producción.