Documentación de Make Agent Fast

Estado del SDK

Elige la API REST estable o evalúa clientes en versión preliminar disponibles solo como código fuente, sin dar por hecho que estén publicados en un registro.

De un vistazo

Elige la API REST estable o evalúa clientes en versión preliminar disponibles solo como código fuente, sin dar por hecho que estén publicados en un registro.

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

REST disponibleOpenAPISDK en versión preliminar

La API REST versionada es hoy la única superficie de integración pública compatible de forma oficial. El código fuente de los clientes de JavaScript, Python y de frameworks existe en el repositorio del producto, pero los paquetes no están publicados actualmente en npm ni en PyPI.

Disponibilidad#

Cliente	Estado	Cómo usarlo
REST sobre HTTPS	Disponible	Llama a `https://makeagent.fast/api/v1` desde cualquier cliente HTTP del lado del servidor
Documento OpenAPI	Disponible	Descarga /api/openapi.json e inspecciónalo antes de generar un cliente
`@make-agent-fast/sdk`	Versión preliminar en código fuente: no está en npm	No añadas esta importación a un proyecto de producción hasta que aquí se enlace una versión publicada en un registro
Paquete de Python `makeagentfast`	Versión preliminar en código fuente: no está en PyPI	Usa `requests`, `httpx` o la biblioteca estándar de Python hasta que aquí se enlace una versión publicada en PyPI
Adaptadores de React, Vue y Svelte	Versión preliminar en código fuente: no están en npm	Es preferible usar el patrón documentado de carga mediante script para tu framework
Componente web	Versión preliminar en código fuente: no está en npm	Es preferible usar el cargador estándar `embed.js`

JavaScript sin 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);

Mantén la clave de API en el servidor. Un bundle de navegador de React, Vue o Svelte debe llamar a tu propio backend o instalar el cargador público de inserción (embed); no debe llamar a la API de administración con un secreto.

Python sin 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"])

En producción, captura urllib.error.HTTPError y analiza su cuerpo JSON usando el formato de error estable.

Clientes generados#

La generación a partir de OpenAPI solo resulta útil cuando el documento contiene las operaciones y los esquemas de los que depende tu aplicación. Fija la especificación descargada, genera el cliente en un directorio revisable e inspecciona cada diferencia antes de actualizar.

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

No regeneres ni despliegues automáticamente un cliente a partir de la URL en vivo. Un nuevo campo añadido no debería romper un cliente, pero el comportamiento del generador y los nombres de los métodos generados aún pueden cambiar.

Qué debe incluir una versión pública del SDK#

Antes de marcar como disponible cualquier cliente en versión preliminar, debe contar con lo siguiente:

Una página pública en un registro y una versión semántica inmutable.
Instrucciones de instalación, actualización y entornos de ejecución compatibles.
Modelos tipados de solicitud y respuesta generados a partir del contrato completo de la API.
Errores estructurados que conserven el estado HTTP y el ID de la solicitud.
Utilidades de paginación que traten los cursores como opacos.
Compatibilidad explícita con claves de idempotencia en las operaciones que modifican datos.
Pruebas de CI contra el contrato actual de /api/v1 y un registro de cambios publicado.

Hasta que se cumplan estas condiciones, usa los ejemplos de REST de la guía de inicio rápido de la API y las recetas de la API.