Des agents dans votre application, en quelques lignes

Décrivez une tâche, l'architecte conçoit l'agent, vous le lancez et branchez ses résultats dans votre produit. Même architecte, mêmes prix et même dashboard que sur le site, depuis une API REST, un serveur MCP ou un terminal.

Une clé fa_live_…, créée en un clic dans le dashboard.
Une carte enregistrée une fois, valable pour tous vos agents.
Des livrables en markdown et des fichiers téléchargeables, ou un rappel signé à la fin de chaque run.

Créer une clé Connecter votre IA Spécification OpenAPI

Vue d'ensemble

Future Agent conçoit des agents sur mesure à partir d'une phrase : une revue de presse chaque matin, des relances de devis, un rapport PDF et Excel envoyé par e-mail, un site web. L'API publique donne accès à ce même parcours depuis votre code.

Accès	Adresse	Pour qui
API REST v1	`https://futureagent.app/api/v1`	Votre application, vos scripts, vos automatisations.
Serveur MCP	`https://futureagent.app/api/mcp`	Votre IA de développement : Claude Code, Cursor, Codex, VS Code.
CLI	`future-agent`	Votre terminal et vos scripts shell.
Spécification OpenAPI 3.1	/api/v1/openapi.json	Générer un client, importer dans Postman ou Insomnia.

Tout agent créé par l'API apparaît dans le dashboard du compte avec un badge API, MCP ou CLI. Vous pouvez le reprendre à la main à tout moment. Les réponses sont en JSON, les dates en ISO 8601 (UTC), les montants en centimes TTC, toujours en euros.

Aucun supplément n'est facturé pour l'API : un agent lancé depuis votre code coûte le même prix que depuis le site, et son prix est toujours calculé par le serveur.

Démarrage rapide

Quatre appels séparent votre brief du premier livrable.

Créez une clé
Ouvrez Dashboard › Développeurs, créez une clé et copiez-la : elle n'est affichée qu'une fois. Gardez-la dans une variable d'environnement de votre serveur.

Décrivez l'agent

L'architecte conçoit l'agent sans poser de questions bloquantes : il retient des valeurs prudentes, les liste dans proposal.assumptions et renvoie le prix calculé.

Concevoir un agent

export FUTURE_AGENT_API_KEY=fa_live_…

curl -s https://futureagent.app/api/v1/agents \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brief":"Chaque lundi, un résumé PDF des avis Google de mon restaurant"}'

Réponse 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Voici l'agent proposé. Lancez-le pour qu'il démarre lundi prochain.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Veille des avis Google",
    "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
    "objective": "Suivre la réputation en ligne du restaurant sans y passer de temps.",
    "kind": "automation",
    "language": "fr",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Tous les lundis à 8 h"
    },
    "steps": [
      {
        "title": "Lire les nouveaux avis",
        "description": "Récupère les avis publiés depuis la dernière exécution."
      },
      {
        "title": "Rédiger le rapport",
        "description": "Note moyenne, thèmes qui reviennent, avis à traiter en priorité."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "Rapport PDF de 2 pages"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Envoyer le rapport par e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Ne jamais répondre publiquement à un avis."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Semaine du 5 octobre\n\nNote moyenne : 4,6 (12 nouveaux avis)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "29 €/mois",
      "rationale": "Recherche web hebdomadaire et rapport PDF."
    },
    "assumptions": [
      "Livraison par e-mail à [email protected], le lundi à 8 h (heure de Paris)."
    ],
    "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Envoyer le rapport par e-mail.",
      "connected": true
    }
  ]
}

3
Lancez-le
Montrez le prix à l'utilisateur, puis passez le montant confirmé dans expectedMonthlyCents. Avec une carte enregistrée, l'agent démarre aussitôt, avec 7 jours d'essai. Sans carte, la réponse contient checkoutUrl, une page de paiement à ouvrir une fois.
Lancer l'agent
```
curl -s -X POST https://futureagent.app/api/v1/agents/agt_8f2k1x/launch \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedMonthlyCents": 2900}'
```

Exécutez-le et lisez le résultat

Exécuter maintenant

curl -s -X POST https://futureagent.app/api/v1/agents/agt_8f2k1x/runs \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inputs": {"city": "Lyon"}}'

Lire le run

curl -s https://futureagent.app/api/v1/runs/run_3m9q7d -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "id": "run_3m9q7d",
  "agentId": "agt_8f2k1x",
  "status": "succeeded",
  "trigger": "manual",
  "createdAt": "2026-10-05T06:00:00.000Z",
  "startedAt": "2026-10-05T06:00:00.000Z",
  "finishedAt": "2026-10-05T06:02:41.000Z",
  "durationMs": 161000,
  "summary": "12 nouveaux avis, note moyenne 4,6.",
  "output": "## Semaine du 5 octobre\n\nNote moyenne : 4,6…",
  "files": [
    {
      "id": "art_7c4n2b",
      "name": "avis-google-semaine-41.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "createdAt": "2026-10-05T06:02:40.000Z",
      "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
    }
  ],
  "error": null,
  "inputRequest": null
}

Authentification

Chaque requête porte l'en-tête Authorization: Bearer fa_live_…. Une clé appartient à un compte (pas à un visiteur anonyme) et ne donne jamais plus que ce compte : ses limites, le budget de chaque agent et ses garde-fous s'appliquent.

Portées d'une clé
Portée	Ce qu'elle permet
`agents:read`	Lire les agents, leur état et leurs propositions.
`agents:write`	Concevoir des agents, répondre à l'architecte, écrire à un agent, partir d'un modèle.
`agents:launch`	Lancer un agent, donc démarrer son abonnement avec la carte enregistrée.
`runs:read`	Lire les runs, les livrables et les fichiers.
`runs:write`	Exécuter un agent et répondre à ses demandes en cours de run.
`templates:read`	Parcourir la bibliothèque de modèles.
`webhooks:write`	Configurer les rappels.
`account:read`	Lire le compte, la carte enregistrée et les quotas restants.

Par défaut, une clé a toutes les portées. Décochez agents:launch pour une clé qui conçoit et exécute sans jamais pouvoir démarrer d'abonnement.
Le secret n'est affiché qu'à la création. Le dashboard ne montre ensuite que son préfixe (fa_live_a1b2c3d4) et sa dernière utilisation.
Révoquez une clé depuis le dashboard : elle cesse de valoir immédiatement (erreur unauthorized).
Langue des messages : en-tête Accept-Language (fr ou en) ou champ locale. Par défaut, la langue du compte.
Identifiants opaques préfixés : agt_… (agent), run_… (run), art_… (fichier), whk_… (webhook).

L'API accepte les appels depuis un navigateur (CORS ouvert), mais une clé dans une page web est une clé publiée. Appelez l'API depuis votre serveur.

Cycle de vie d'un agent

Concevoir, compléter, lancer, exécuter, récupérer. Chaque étape a son appel, et chaque réponse dit quoi faire ensuite.

1. Concevoir : mode direct ou conversation

POST /agents { brief } lance l'architecte en mode direct (par défaut) : il conçoit sans attendre de réponse, avec des choix prudents (aucun envoi à un tiers sans destinataire connu, livraison dans le dashboard), et ne renvoie que les questions qui n'ont pas de valeur sûre. Passez ce que vous savez déjà dans answers et les apps à utiliser dans connectors.

Le mode conversation poursuit la même conception : chatId reçu, réponses dans answers, ou message libre dans message.

Répondre à l'architecte

curl -s https://futureagent.app/api/v1/agents \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"conversation","chatId":"chat_5t1w0z","answers":{"restaurant":"Le Comptoir"},"message":"Plutôt le vendredi à 17 h, et en Excel."}'

Champ status d'une conception
status	Signification	Étape suivante
`needs_answers`	Des questions restent ouvertes (`questions`).	Répondre en mode conversation.
`needs_connections`	Une app doit être connectée (`connectors[].connectUrl`).	Faire ouvrir le lien, puis relire la proposition.
`proposed`	La proposition est prête, l'agent existe (`agentId`).	Montrer le prix, puis lancer.
`preview_ready`	Site web : l'aperçu est construit (`previewUrl`).	Le montrer, puis lancer.

2. Connecter les apps

Quand l'agent a besoin de Gmail, Google Sheets, Slack ou d'une autre app, chaque connecteur non relié porte un connectUrl : un lien signé à ouvrir dans un navigateur, connexion en un clic. Ensuite, GET /agents/:id/proposal relit l'état sans nouvel appel à l'architecte.

3. Proposition et prix

La proposition décrit l'agent : nom, planning lisible (schedule.humanReadable), étapes, livrables, règles, connecteurs, formulaire d'entrée par run (perRunInputs) et un exemple de livrable. Le prix (price.monthlyCents, price.formatted) est calculé par le serveur selon la difficulté et la fréquence ; vous ne le saisissez jamais.

4. Lancer : la carte, une seule fois

POST /agents/:id/launch démarre l'agent selon l'offre réelle du compte : inclus au forfait, offre de bienvenue, premier agent offert, ou essai de 7 jours puis prélèvement sur la carte déjà enregistrée, sans nouvelle page de paiement. Une carte ajoutée une fois (Dashboard › Facturation ou Développeurs) sert à tous les agents, qu'ils viennent du site, de WhatsApp, de l'API, du MCP ou du CLI.

Réponse : agent actif

{
  "status": "active",
  "agentId": "agt_8f2k1x",
  "mode": "trial",
  "trialEndsAt": "2026-10-12T09:12:00.000Z",
  "firstRunId": null,
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "29 €/mois",
    "rationale": "Recherche web hebdomadaire et rapport PDF."
  }
}

Réponse : aucune carte enregistrée

{
  "status": "checkout_required",
  "agentId": "agt_8f2k1x",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_…",
  "firstChargeAt": "2026-10-12T09:12:00.000Z",
  "amountCents": 2900
}

Passez toujours expectedMonthlyCents, le prix que l'utilisateur a vu. S'il ne correspond plus au prix réel, rien n'est lancé ni prélevé : vous recevez conflict avec le nouveau montant.

Réponse 409

{
  "error": {
    "code": "conflict",
    "message": "Le prix a changé : 39 €/mois. Montrez ce prix à l'utilisateur, puis relancez avec « expectedMonthlyCents » à jour.",
    "docs": "https://futureagent.app/dashboard/developpeurs#erreur-conflict",
    "details": {
      "monthlyCents": 3900,
      "expectedMonthlyCents": 2900
    }
  }
}

Concevoir ne modifie jamais un agent déjà lancé. Une nouvelle version proposée par l'architecte ne s'applique qu'au prochain appel de lancement (updated: true).

5. Exécuter avec des entrées

Un agent lancé tourne sur son planning. POST /agents/:id/runs l'exécute tout de suite : inputs remplit son formulaire perRunInputs (les champs fichier prennent des identifiants art_…), instructions ajoute une consigne ponctuelle, test: true fait un essai qui ne déclenche jamais les agents reliés. La réponse 202 donne runId. Si un run tourne déjà, son identifiant revient avec alreadyRunning: true.

6. Lire le résultat et les fichiers

GET /runs/:id renvoie le statut (queued, running, succeeded, failed, skipped, needs_input), le résumé, le livrable complet en markdown (output) et les fichiers avec un downloadUrl signé, valable 7 jours et téléchargeable sans clé. Ajoutez ?log=1 pour le journal lisible des étapes.

En needs_input, l'agent attend une information ou une connexion (inputRequest.fields, inputRequest.connection). Répondez avec POST /runs/:id/answer : un run de reprise démarre, son identifiant est resumedRunId.

Répondre à un agent en cours de run

curl -s -X POST https://futureagent.app/api/v1/runs/run_3m9q7d/answer \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"recipient": "[email protected]"}}'

// Côté serveur uniquement : la clé ne doit jamais partir vers le navigateur.
const API = "https://futureagent.app/api/v1";

export async function fa<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.FUTURE_AGENT_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error.message), body.error);
  return body as T;
}

// Exécuter un agent et attendre son livrable.
export async function runAndWait(agentId: string, inputs: Record<string, string> = {}) {
  const { runId } = await fa<{ runId: string }>(`/agents/${agentId}/runs`, {
    method: "POST",
    headers: { "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({ inputs }),
  });
  let delay = 3000;
  for (;;) {
    const run = await fa<{ status: string; output: string | null; files: { name: string; downloadUrl: string }[] }>(`/runs/${runId}`);
    if (!["queued", "running"].includes(run.status)) return run;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 30_000);
  }
}

Webhooks signés

Plutôt que d'interroger l'API, recevez un POST signé à la fin de chaque run.

PUT /webhook { url } enregistre l'adresse de votre application pour tout le compte, ou pour un seul agent avec agentId. Le secret de signature whsec_… n'est renvoyé qu'à la création ou avec rotateSecret: true : enregistrez-le tout de suite. url: null supprime le rappel.

Enregistrer un webhook

curl -s -X PUT https://futureagent.app/api/v1/webhook \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/hooks/future-agent", "events": ["run.finished", "run.needs_input"]}'

Événements
Événement	Quand
`run.finished`	Un run se termine (réussi, échoué ou ignoré). Le corps contient le run complet.
`run.needs_input`	Un run attend une réponse ou une connexion.
`agent.activated`	Un agent vient d'être lancé (par exemple après le paiement).
`agent.paused`	Un agent est mis en pause.

En-têtes : Future-Agent-Signature: t=<unix>,v1=<hex> (copie dans X-FutureAgent-Signature), Future-Agent-Event, Future-Agent-Delivery.
v1 = HMAC-SHA256 du texte <t>.<corps brut> avec votre secret. Pendant une rotation, plusieurs v1= peuvent figurer : acceptez-en un valide.
Refusez un horodatage à plus de 300 secondes de votre horloge : c'est un rejeu.
Répondez en 2xx en moins de 10 secondes, puis traitez. Trois tentatives au plus : tout de suite, après 30 secondes, après 5 minutes.
Future-Agent-Delivery est identique d'une tentative à l'autre : ignorez un identifiant déjà traité.
Adresse https publique uniquement (http seulement vers localhost en développement), aucune adresse privée, aucune redirection suivie. Après 20 échecs consécutifs, le rappel est désactivé. 50 webhooks au plus par compte.

Corps d'une livraison run.finished

{
  "id": "evt_9w3e5r",
  "event": "run.finished",
  "createdAt": "2026-10-05T06:02:42.000Z",
  "agentId": "agt_8f2k1x",
  "run": {
    "id": "run_3m9q7d",
    "agentId": "agt_8f2k1x",
    "status": "succeeded",
    "trigger": "manual",
    "createdAt": "2026-10-05T06:00:00.000Z",
    "startedAt": "2026-10-05T06:00:00.000Z",
    "finishedAt": "2026-10-05T06:02:41.000Z",
    "durationMs": 161000,
    "summary": "12 nouveaux avis, note moyenne 4,6.",
    "output": "## Semaine du 5 octobre\n\nNote moyenne : 4,6…",
    "files": [
      {
        "id": "art_7c4n2b",
        "name": "avis-google-semaine-41.pdf",
        "mimeType": "application/pdf",
        "size": 184320,
        "createdAt": "2026-10-05T06:02:40.000Z",
        "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
      }
    ],
    "error": null,
    "inputRequest": null
  }
}

// app/api/future-agent/webhook/route.ts (Next.js, Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, body: string, header: string | null, toleranceSeconds = 300) {
  if (!header) return false;
  const parts = header.split(",").map((p) => p.trim());
  const t = Number(parts.find((p) => p.startsWith("t="))?.slice(2));
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${body}`).digest("hex"));
  return parts.filter((p) => p.startsWith("v1=")).some((p) => {
    const got = Buffer.from(p.slice(3));
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

export async function POST(request: Request) {
  const body = await request.text(); // corps brut : vérifier AVANT JSON.parse
  if (!verify(process.env.FUTURE_AGENT_WEBHOOK_SECRET!, body, request.headers.get("future-agent-signature"))) {
    return new Response("invalid signature", { status: 400 });
  }
  const event = JSON.parse(body);
  // Future-Agent-Delivery est identique d'une tentative à l'autre : ignorez un id déjà traité.
  if (event.event === "run.finished" && event.run?.status === "succeeded") {
    // event.run.output (markdown), event.run.files[].downloadUrl (liens signés)
  }
  return new Response(null, { status: 204 });
}

Sans webhook, interrogez GET /runs/:id toutes les 3 à 5 secondes avec un intervalle croissant, comme dans le client minimal ci-dessus. Depuis le MCP, run_agent peut attendre la fin du run jusqu'à 55 secondes (waitSeconds).

Référence de l'API

Base : https://futureagent.app/api/v1. Toutes les réponses sont en JSON avec Cache-Control: no-store. Cette référence est générée depuis la spécification OpenAPI.

GET/api/v1/agentsPortée agents:read

Lister les agents

Agents du compte, du plus récent au plus ancien, tous canaux confondus (site, WhatsApp, API, MCP, CLI).

Paramètres
Nom	Type	Description
`status`"draft" \| "awaiting_payment" \| "active" \| "paused" \| "error"requête, facultatif	"draft" \| "awaiting_payment" \| "active" \| "paused" \| "error"	Filtrer par statut.
`source`"web" \| "whatsapp" \| "api" \| "mcp" \| "cli"requête, facultatif	"web" \| "whatsapp" \| "api" \| "mcp" \| "cli"	Filtrer par canal de création.
`limit`integerrequête, facultatif	integer	Nombre d'éléments par page.
`cursor`stringrequête, facultatif	string	Valeur `nextCursor` de la page précédente.

Requête

curl -s "https://futureagent.app/api/v1/agents?status=active&limit=20" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "data": [
    {
      "id": "agt_8f2k1x",
      "name": "Veille des avis Google",
      "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
      "kind": "automation",
      "status": "active",
      "source": "api",
      "schedule": {
        "type": "schedule",
        "cron": "0 8 * * 1",
        "timezone": "Europe/Paris",
        "humanReadable": "Tous les lundis à 8 h"
      },
      "price": {
        "monthlyCents": 2900,
        "billedMonthlyCents": 2900,
        "currency": "eur",
        "formatted": "29 €/mois",
        "rationale": "Recherche web hebdomadaire et rapport PDF."
      },
      "billingMode": "trial",
      "nextRunAt": "2026-10-12T06:00:00.000Z",
      "lastRunAt": "2026-10-05T06:00:00.000Z",
      "createdAt": "2026-10-01T09:12:00.000Z",
      "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x"
    }
  ],
  "nextCursor": null
}

Erreurs possibles : 401, 403, 429

POST/api/v1/agentsPortée agents:write

Concevoir un agent

Mode direct (défaut) : conception sans questions bloquantes depuis brief. Mode conversation : poursuite d'une conception avec chatId. Rien n'est facturé à cette étape.

ParamètresVariantes du corps : direct | conversation
Nom	Type	Description
`Idempotency-Key`stringen-tête, facultatif	string	Même clé = même ressource pendant 24 h.
`mode`"direct" \| "conversation"corps, facultatif	"direct" \| "conversation"	« direct » (défaut) ou « conversation ».
`brief`stringcorps, facultatif	string	La tâche, en une ou deux phrases (mode direct).
`answers`objectcorps, facultatif	object	Réponses déjà connues : id de question (ou libellé) → valeur.
`connectors`string[]corps, facultatif	string[]	Apps à utiliser si possible (gmail, googlesheets, slack…).
`locale`"fr" \| "en"corps, facultatif	"fr" \| "en"	Langue de l'agent et des messages : fr ou en.
`idempotencyKey`stringcorps, facultatif	string	Même clé = même conception pendant 24 h.
`chatId`stringcorps, facultatif	string	Conversation à poursuivre (mode conversation).
`message`stringcorps, facultatif	string	Message libre à l'architecte (mode conversation).

Requête

curl -s -X POST "https://futureagent.app/api/v1/agents" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Idempotency-Key: 8d1c5e0a-brief-1" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Chaque lundi à 8 h, un résumé PDF des avis Google de mon restaurant, envoyé à [email protected]",
    "connectors": [
      "gmail"
    ],
    "answers": {
      "city": "Lyon"
    }
  }'

Réponse 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Voici l'agent proposé. Lancez-le pour qu'il démarre lundi prochain.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Veille des avis Google",
    "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
    "objective": "Suivre la réputation en ligne du restaurant sans y passer de temps.",
    "kind": "automation",
    "language": "fr",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Tous les lundis à 8 h"
    },
    "steps": [
      {
        "title": "Lire les nouveaux avis",
        "description": "Récupère les avis publiés depuis la dernière exécution."
      },
      {
        "title": "Rédiger le rapport",
        "description": "Note moyenne, thèmes qui reviennent, avis à traiter en priorité."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "Rapport PDF de 2 pages"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Envoyer le rapport par e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Ne jamais répondre publiquement à un avis."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Semaine du 5 octobre\n\nNote moyenne : 4,6 (12 nouveaux avis)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "29 €/mois",
      "rationale": "Recherche web hebdomadaire et rapport PDF."
    },
    "assumptions": [
      "Livraison par e-mail à [email protected], le lundi à 8 h (heure de Paris)."
    ],
    "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Envoyer le rapport par e-mail.",
      "connected": true
    }
  ]
}

Erreurs possibles : 400, 401, 403, 404, 409, 429

GET/api/v1/agents/{id}Portée agents:read

Lire un agent

État lisible, planning, prix, connecteurs, formulaire d'entrée par run, demande en attente et niveau d'utilisation du mois.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.

Requête

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "id": "agt_8f2k1x",
  "name": "Veille des avis Google",
  "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
  "kind": "automation",
  "status": "active",
  "source": "api",
  "schedule": {
    "type": "schedule",
    "cron": "0 8 * * 1",
    "timezone": "Europe/Paris",
    "humanReadable": "Tous les lundis à 8 h"
  },
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "29 €/mois",
    "rationale": "Recherche web hebdomadaire et rapport PDF."
  },
  "billingMode": "trial",
  "nextRunAt": "2026-10-12T06:00:00.000Z",
  "lastRunAt": "2026-10-05T06:00:00.000Z",
  "createdAt": "2026-10-01T09:12:00.000Z",
  "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x",
  "objective": "Suivre la réputation en ligne du restaurant sans y passer de temps.",
  "state": {
    "code": "ready",
    "label": "Prochaine exécution lundi à 8 h",
    "action": null
  },
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Envoyer le rapport par e-mail.",
      "connected": true
    }
  ],
  "capabilities": [
    "web_research",
    "files",
    "email"
  ],
  "outputs": [
    {
      "format": "pdf",
      "description": "Rapport PDF de 2 pages"
    }
  ],
  "perRunInputs": [
    {
      "id": "city",
      "label": "Ville",
      "type": "text",
      "required": false,
      "placeholder": "Lyon"
    }
  ],
  "pendingInput": null,
  "usage": "normal",
  "publicUrl": null,
  "webhook": true
}

Erreurs possibles : 401, 403, 404

GET/api/v1/agents/{id}/proposalPortée agents:read

Relire la conception

Dernier état de la conception, par identifiant d'agent ou chatId, sans nouvel appel à l'architecte.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.

Requête

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x/proposal" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Voici l'agent proposé. Lancez-le pour qu'il démarre lundi prochain.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Veille des avis Google",
    "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
    "objective": "Suivre la réputation en ligne du restaurant sans y passer de temps.",
    "kind": "automation",
    "language": "fr",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Tous les lundis à 8 h"
    },
    "steps": [
      {
        "title": "Lire les nouveaux avis",
        "description": "Récupère les avis publiés depuis la dernière exécution."
      },
      {
        "title": "Rédiger le rapport",
        "description": "Note moyenne, thèmes qui reviennent, avis à traiter en priorité."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "Rapport PDF de 2 pages"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Envoyer le rapport par e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Ne jamais répondre publiquement à un avis."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Semaine du 5 octobre\n\nNote moyenne : 4,6 (12 nouveaux avis)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "29 €/mois",
      "rationale": "Recherche web hebdomadaire et rapport PDF."
    },
    "assumptions": [
      "Livraison par e-mail à [email protected], le lundi à 8 h (heure de Paris)."
    ],
    "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Envoyer le rapport par e-mail.",
      "connected": true
    }
  ]
}

Erreurs possibles : 401, 403, 404

POST/api/v1/agents/{id}/launchPortée agents:launch

Lancer un agent

Démarre l'agent selon l'offre du compte. Avec une carte enregistrée : status: "active". Sans carte : status: "checkout_required" et checkoutUrl à ouvrir une fois.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`expectedMonthlyCents`integercorps, facultatif	integer	Prix mensuel TTC confirmé par l'utilisateur, en centimes. Différent du prix réel : 409, rien n'est prélevé.
`returnUrl`stringcorps, facultatif	string	Réservé : accepté, ignoré pour l'instant.

Requête

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/launch" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedMonthlyCents": 2900
  }'

Réponse 200

{
  "status": "active",
  "agentId": "agt_8f2k1x",
  "mode": "trial",
  "trialEndsAt": "2026-10-12T09:12:00.000Z",
  "firstRunId": null,
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "29 €/mois",
    "rationale": "Recherche web hebdomadaire et rapport PDF."
  }
}

Erreurs possibles : 401, 402, 403, 404, 409, 429

GET/api/v1/agents/{id}/runsPortée runs:read

Lister les runs

Runs de l'agent, du plus récent au plus ancien, sans le journal.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`status`"queued" \| "running" \| "succeeded" \| "failed" \| "skipped" \| "needs_input"requête, facultatif	"queued" \| "running" \| "succeeded" \| "failed" \| "skipped" \| "needs_input"	Filtrer par statut.
`limit`integerrequête, facultatif	integer	Nombre d'éléments par page.
`cursor`stringrequête, facultatif	string	Valeur `nextCursor` de la page précédente.

Requête

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x/runs?limit=10" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "data": [
    {
      "id": "run_3m9q7d",
      "agentId": "agt_8f2k1x",
      "status": "succeeded",
      "trigger": "manual",
      "createdAt": "2026-10-05T06:00:00.000Z",
      "startedAt": "2026-10-05T06:00:00.000Z",
      "finishedAt": "2026-10-05T06:02:41.000Z",
      "durationMs": 161000,
      "summary": "12 nouveaux avis, note moyenne 4,6.",
      "output": "## Semaine du 5 octobre\n\nNote moyenne : 4,6…",
      "files": [
        {
          "id": "art_7c4n2b",
          "name": "avis-google-semaine-41.pdf",
          "mimeType": "application/pdf",
          "size": 184320,
          "createdAt": "2026-10-05T06:02:40.000Z",
          "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
        }
      ],
      "error": null,
      "inputRequest": null
    }
  ],
  "nextCursor": null
}

Erreurs possibles : 401, 403, 404

POST/api/v1/agents/{id}/runsPortée runs:write

Exécuter un agent

Démarre un run en arrière-plan et répond 202 avec runId. Un rejeu idempotent ou un run déjà en cours répond 200.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`Idempotency-Key`stringen-tête, facultatif	string	Même clé = même run pendant 24 h.
`inputs`objectcorps, facultatif	object	Valeurs du formulaire `perRunInputs` (id → valeur ; fichiers : ids `art_…`).
`instructions`stringcorps, facultatif	string	Consigne ponctuelle pour ce run.
`test`booleancorps, facultatif	boolean	Run d'essai : ne déclenche jamais les agents reliés.
`idempotencyKey`stringcorps, facultatif	string	Même clé = même run pendant 24 h.

Requête

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/runs" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "city": "Lyon"
    }
  }'

Réponse 202

{
  "runId": "run_3m9q7d",
  "status": "queued",
  "agentId": "agt_8f2k1x",
  "replayed": false
}

Erreurs possibles : 400, 401, 402, 403, 404, 409, 429

POST/api/v1/agents/{id}/messagesPortée agents:write

Écrire à un agent

Comme dans la conversation de l'agent dans le dashboard : ajuster son comportement, poser une question, lui confier un fichier. Renvoie sa réponse et runId si un run démarre.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`text`stringcorps, obligatoire	string	Texte du message.
`attachments`string[]corps, facultatif	string[]	Fichiers déjà déposés (`art_…`).

Requête

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/messages" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Ajoutez aussi le restaurant de Paris."
  }'

Réponse 200

{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "kind": "text",
      "text": "Ajoutez aussi le restaurant de Paris.",
      "createdAt": "2026-10-05T06:00:00.000Z"
    },
    {
      "id": "msg_2",
      "role": "agent",
      "kind": "text",
      "text": "Bien noté : j'ajoute le restaurant de Paris dès la prochaine exécution.",
      "createdAt": "2026-10-05T06:00:00.000Z"
    }
  ],
  "runId": null
}

Erreurs possibles : 400, 401, 403, 404, 429

GET/api/v1/runs/{id}Portée runs:read

Lire un run

Statut, résumé, livrable en markdown, fichiers à liens signés (7 jours), erreur lisible et demande en attente.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`log`"1" \| "true"requête, facultatif	"1" \| "true"	1 = ajouter le journal lisible des étapes.

Requête

curl -s "https://futureagent.app/api/v1/runs/run_3m9q7d?log=1" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "id": "run_3m9q7d",
  "agentId": "agt_8f2k1x",
  "status": "succeeded",
  "trigger": "manual",
  "createdAt": "2026-10-05T06:00:00.000Z",
  "startedAt": "2026-10-05T06:00:00.000Z",
  "finishedAt": "2026-10-05T06:02:41.000Z",
  "durationMs": 161000,
  "summary": "12 nouveaux avis, note moyenne 4,6.",
  "output": "## Semaine du 5 octobre\n\nNote moyenne : 4,6…",
  "files": [
    {
      "id": "art_7c4n2b",
      "name": "avis-google-semaine-41.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "createdAt": "2026-10-05T06:02:40.000Z",
      "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
    }
  ],
  "error": null,
  "inputRequest": null,
  "log": [
    {
      "at": "2026-10-05T06:02:40.000Z",
      "level": "info",
      "message": "Rapport PDF enregistré."
    }
  ]
}

Erreurs possibles : 401, 403, 404

POST/api/v1/runs/{id}/answerPortée runs:write

Répondre à un run

Répond à un run en needs_input. Un run de reprise démarre : resumedRunId. Alias : POST /runs/{id}/input.

Paramètres
Nom	Type	Description
`id`stringchemin, obligatoire	string	Identifiant : `agt_…` pour un agent, `run_…` pour un run.
`values`objectcorps, obligatoire	object	Id de champ (`inputRequest.fields`) → valeur.

Requête

curl -s -X POST "https://futureagent.app/api/v1/runs/run_3m9q7d/answer" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "recipient": "[email protected]"
    }
  }'

Réponse 202

{
  "runId": "run_3m9q7d",
  "resumedRunId": "run_4p0s8e"
}

Erreurs possibles : 400, 401, 403, 404, 409

GET/api/v1/templatesPortée templates:read

Chercher un modèle

Modèles de la bibliothèque, avec leur prix calculé et les questions personnelles que l'architecte posera.

Paramètres
Nom	Type	Description
`q`stringrequête, facultatif	string	Recherche libre.
`category`stringrequête, facultatif	string	Catégorie.
`secteur`stringrequête, facultatif	string	Secteur (ex. restauration) ou « tous ».
`metier`stringrequête, facultatif	string	Métier (ex. comptabilite).
`kind`stringrequête, facultatif	string	automation, project ou chain.
`limit`integerrequête, facultatif	integer	Nombre d'éléments par page.
`cursor`stringrequête, facultatif	string	Valeur `nextCursor` de la page précédente.

Requête

curl -s "https://futureagent.app/api/v1/templates?q=revue%20de%20presse&limit=5" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "data": [
    {
      "slug": "revue-de-presse",
      "name": "Revue de presse quotidienne",
      "summary": "Les articles du jour sur vos sujets, résumés et envoyés chaque matin.",
      "category": "Veille",
      "kind": "automation",
      "sectors": [
        "tous"
      ],
      "roles": [
        "direction"
      ],
      "connectors": [
        "gmail"
      ],
      "price": {
        "monthlyCents": 1900,
        "billedMonthlyCents": 1900,
        "currency": "eur",
        "formatted": "19 €/mois"
      },
      "questions": [
        "Quels sujets suivre ?"
      ],
      "url": "https://futureagent.app/bibliotheque/revue-de-presse"
    }
  ],
  "nextCursor": null
}

Erreurs possibles : 401, 403

POST/api/v1/templates/{slug}/agentsPortée agents:write

Partir d'un modèle

Conçoit un agent à partir d'un modèle : l'architecte n'a besoin que de ses questions personnelles.

Paramètres
Nom	Type	Description
`slug`stringchemin, obligatoire	string	Slug du modèle, tel que renvoyé par `GET /templates`.
`Idempotency-Key`stringen-tête, facultatif	string	Même clé = même ressource pendant 24 h, sans doublon.
`step`integercorps, facultatif	integer	Agent d'une chaîne d'agents reliés (0 par défaut).
`answers`objectcorps, facultatif	object	Réponses aux questions du modèle.
`locale`"fr" \| "en"corps, facultatif	"fr" \| "en"	fr ou en.
`idempotencyKey`stringcorps, facultatif	string	Même clé = même conception pendant 24 h.

Requête

curl -s -X POST "https://futureagent.app/api/v1/templates/revue-de-presse/agents" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "topic": "vélos électriques"
    }
  }'

Réponse 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Voici l'agent proposé. Lancez-le pour qu'il démarre lundi prochain.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Veille des avis Google",
    "summary": "Résume chaque semaine les nouveaux avis Google du restaurant dans un PDF envoyé à l'équipe.",
    "objective": "Suivre la réputation en ligne du restaurant sans y passer de temps.",
    "kind": "automation",
    "language": "fr",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Tous les lundis à 8 h"
    },
    "steps": [
      {
        "title": "Lire les nouveaux avis",
        "description": "Récupère les avis publiés depuis la dernière exécution."
      },
      {
        "title": "Rédiger le rapport",
        "description": "Note moyenne, thèmes qui reviennent, avis à traiter en priorité."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "Rapport PDF de 2 pages"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Envoyer le rapport par e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Ne jamais répondre publiquement à un avis."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Semaine du 5 octobre\n\nNote moyenne : 4,6 (12 nouveaux avis)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "29 €/mois",
      "rationale": "Recherche web hebdomadaire et rapport PDF."
    },
    "assumptions": [
      "Livraison par e-mail à [email protected], le lundi à 8 h (heure de Paris)."
    ],
    "dashboardUrl": "https://futureagent.app/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Envoyer le rapport par e-mail.",
      "connected": true
    }
  ]
}

Erreurs possibles : 400, 401, 403, 404, 429

GET/api/v1/webhooksPortée webhooks:write

Lister les webhooks

Rappels du compte, avec la date et le statut de la dernière livraison et le nombre d'échecs consécutifs.

Requête

curl -s "https://futureagent.app/api/v1/webhooks" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "data": [
    {
      "id": "whk_2j6v9c",
      "url": "https://app.example.com/hooks/future-agent",
      "agentId": null,
      "events": [
        "run.finished",
        "run.needs_input"
      ],
      "active": true,
      "lastDeliveryAt": "2026-10-05T06:00:00.000Z",
      "lastStatus": 204,
      "failures": 0
    }
  ]
}

Erreurs possibles : 401, 403

PUT/api/v1/webhooksPortée webhooks:write

Enregistrer un webhook

Crée ou modifie le rappel du compte, ou d'un agent avec agentId. url: null le supprime. Alias : PUT /webhook.

Paramètres
Nom	Type	Description
`url`string \| nullcorps, obligatoire	string \| null	Adresse https publique, ou null pour supprimer.
`agentId`stringcorps, facultatif	string	Un seul agent ; absent : tout le compte.
`events`("run.finished" \| "run.needs_input" \| "agent.activated" \| "agent.paused")[]corps, facultatif	("run.finished" \| "run.needs_input" \| "agent.activated" \| "agent.paused")[]	Événements à recevoir (tous par défaut).
`rotateSecret`booleancorps, facultatif	boolean	Nouveau secret : l'ancien cesse de valoir.

Requête

curl -s -X PUT "https://futureagent.app/api/v1/webhook" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/hooks/future-agent",
    "events": [
      "run.finished",
      "run.needs_input"
    ]
  }'

Réponse 200

{
  "deleted": false,
  "id": "whk_2j6v9c",
  "url": "https://app.example.com/hooks/future-agent",
  "agentId": null,
  "events": [
    "run.finished",
    "run.needs_input"
  ],
  "active": true,
  "secret": "whsec_…"
}

Erreurs possibles : 400, 401, 403, 404

DELETE/api/v1/webhooksPortée webhooks:write

Supprimer un webhook

Supprime le rappel du compte, ou celui d'un agent avec ?agentId=.

Paramètres
Nom	Type	Description
`agentId`stringrequête, facultatif	string	Agent concerné.

Requête

curl -s -X DELETE "https://futureagent.app/api/v1/webhooks?agentId=agt_8f2k1x" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "deleted": true,
  "agentId": "agt_8f2k1x"
}

Erreurs possibles : 401, 403, 404

GET/api/v1/accountPortée account:read

Lire le compte

Forfait, carte enregistrée (4 derniers chiffres), nature du prochain lancement, nombre d'agents, stockage et quotas restants.

Requête

curl -s "https://futureagent.app/api/v1/account" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Réponse 200

{
  "user": {
    "id": "usr_1a2b3c",
    "name": "Camille Martin",
    "email": "[email protected]"
  },
  "plan": {
    "id": "libre",
    "name": "Libre"
  },
  "card": {
    "saved": true,
    "brand": "visa",
    "last4": "4242"
  },
  "nextLaunch": {
    "kind": "trial",
    "trialDays": 7
  },
  "agents": {
    "total": 3,
    "active": 2
  },
  "usage": "normal",
  "storage": {
    "usedBytes": 52428800,
    "quotaBytes": 1073741824,
    "level": "low"
  },
  "limits": {
    "requestsPerMinute": 120,
    "createsPerDay": {
      "limit": 50,
      "used": 2
    },
    "runsPerDay": {
      "limit": 300,
      "used": 14
    },
    "messagesPerDay": {
      "limit": 300,
      "used": 0
    },
    "launchesPerDay": {
      "limit": 50,
      "used": 1
    }
  },
  "billingUrl": "https://futureagent.app/dashboard/facturation",
  "dashboardUrl": "https://futureagent.app/dashboard"
}

Erreurs possibles : 401, 403

Serveur MCP

Donnez à votre IA de développement les outils pour concevoir, lancer, exécuter et intégrer vos agents, sans écrire l'appel vous-même.

Adresse : https://futureagent.app/api/mcp. Transport Streamable HTTP sans état, authentification Authorization: Bearer fa_live_… sur chaque requête. Le serveur expose 15 outils, des guides en lecture (future-agent://guide/lifecycle, typescript, python, webhooks, errors, setup) et une invite integrate_agent. Les erreurs d'un outil reviennent avec le même corps que l'API REST, pour que l'IA s'adapte.

Configurer votre outil

Claude CodeDans un terminal, à la racine de votre projet :

Claude Code

claude mcp add --transport http future-agent https://futureagent.app/api/mcp \
  --header "Authorization: Bearer fa_live_…"

CursorDans ~/.cursor/mcp.json (ou .cursor/mcp.json pour un seul projet) :

Cursor

{
  "mcpServers": {
    "future-agent": {
      "url": "https://futureagent.app/api/mcp",
      "headers": {
        "Authorization": "Bearer fa_live_…"
      }
    }
  }
}

CodexDans ~/.codex/config.toml, avec la clé dans la variable FUTURE_AGENT_API_KEY :

Codex

# export FUTURE_AGENT_API_KEY=fa_live_…
[mcp_servers.future-agent]
url = "https://futureagent.app/api/mcp"
bearer_token_env_var = "FUTURE_AGENT_API_KEY"

VS CodeDans .vscode/mcp.json : VS Code demande la clé au premier lancement et la garde chiffrée.

VS Code

{
  "inputs": [
    {
      "type": "promptString",
      "id": "future-agent-key",
      "description": "Future Agent API key",
      "password": true
    }
  ],
  "servers": {
    "future-agent": {
      "type": "http",
      "url": "https://futureagent.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:future-agent-key}"
      }
    }
  }
}

Les 15 outils

Outil	Rôle	Portée
`create_agent`	Concevoir un agent depuis un brief (mode direct ou conversation).	`agents:write`
`answer_architect`	Répondre aux questions de l'architecte ou lui écrire.	`agents:write`
`get_proposal`	Relire l'état de la conception, sans nouvel appel à l'architecte.	`agents:read`
`launch_agent`	Lancer l'agent avec le prix confirmé (carte enregistrée, sinon lien de paiement).	`agents:launch`
`list_agents`	Lister les agents du compte, tous canaux confondus.	`agents:read`
`get_agent`	Lire un agent : état, planning, prix, formulaire d'entrée, demande en attente.	`agents:read`
`run_agent`	Exécuter maintenant, avec attente facultative jusqu'à 55 secondes.	`runs:write`
`get_run`	Lire un run : statut, livrable, fichiers, journal.	`runs:read`
`list_runs`	Lister les runs d'un agent.	`runs:read`
`message_agent`	Écrire à un agent existant, comme dans sa conversation du dashboard.	`agents:write`
`answer_input_request`	Répondre à un agent qui attend une information en cours de run.	`runs:write`
`list_templates`	Chercher dans la bibliothèque de modèles.	`templates:read`
`create_from_template`	Concevoir un agent à partir d'un modèle.	`agents:write`
`set_webhook`	Enregistrer, modifier ou supprimer le rappel signé.	`webhooks:write`
`get_account`	Lire le forfait, la carte enregistrée et les quotas restants.	`account:read`

Exemple de dialogue
- Vous : Crée un agent Future Agent qui m'envoie chaque lundi un résumé PDF des avis Google de mon restaurant, et affiche le dernier rapport dans mon app Next.js.
- IA : appelle create_agent, reçoit la proposition « Veille des avis Google, tous les lundis à 8 h, 29 €/mois » et ses hypothèses, puis vous demande de confirmer le prix.
- Vous : OK pour ce prix.
- IA : appelle launch_agent avec expectedMonthlyCents: 2900 (essai gratuit, carte enregistrée), puis set_webhook vers votre route, lit le guide webhooks et écrit la route qui vérifie la signature et enregistre le rapport.
- IA : lance un essai avec run_agent (test: true, waitSeconds: 55) et vérifie que la route reçoit bien le livrable.

L'IA demande votre accord avant de lancer : le prix confirmé passe dans expectedMonthlyCents. Pour une clé qui ne peut jamais démarrer d'abonnement, retirez la portée agents:launch.

CLI

Le même parcours depuis votre terminal : npm install -g future-agent.

Commandes

# Se connecter (clé masquée à la saisie)
future-agent login --base-url https://futureagent.app
future-agent whoami

# Concevoir, lancer, exécuter
future-agent agents create "Chaque lundi, un résumé PDF des avis Google de mon restaurant" --connector gmail
future-agent agents launch agt_8f2k1x --expect-cents 2900
future-agent agents run agt_8f2k1x --input city=Lyon --wait --download --out ./reports

# Suivre
future-agent agents list --source cli
future-agent agents status run_3m9q7d --wait
future-agent agents logs run_3m9q7d
future-agent agents answer run_3m9q7d --value [email protected]

# Bibliothèque et rappels
future-agent templates list "revue de presse" --secteur restauration
future-agent webhook set https://app.example.com/hooks/future-agent --event run.finished

Commande	Rôle
`login`, `whoami`	Enregistrer la clé (fichier en 0600 sous `~/.config/future-agent`), voir le compte et les quotas.
`agents create`	Concevoir depuis un brief (`--answer`, `--connector`) ou poursuivre (`--chat`).
`agents launch`	Lancer (`--expect-cents`, `--open` pour ouvrir la page de paiement si besoin).
`agents run`	Exécuter (`--input`, `--wait`, `--download`, `--out`).
`agents list \| get \| runs \| status \| logs \| files`	Suivre agents, runs, journaux et fichiers.
`agents message \| answer`	Écrire à un agent, répondre à une demande en cours de run.
`templates list \| use`	Chercher un modèle de la bibliothèque et en partir.
`webhook set \| delete`	Configurer le rappel signé.
`mcp`	Pont stdio vers le serveur MCP, pour les outils qui ne lancent que des serveurs locaux.

Options communes : --json (réponse brute), --idempotency-key, --lang fr|en, --no-color. Codes de sortie : 0 succès, 1 erreur de l'API ou du réseau, 2 erreur d'utilisation. Variables : FUTURE_AGENT_API_KEY, FUTURE_AGENT_BASE_URL.

Limites et quotas

120 requêtes par minute et par clé. Par compte et par 24 heures glissantes, toutes clés confondues (vingt clés ne donnent pas vingt fois le quota) :

Action	Compte sans agent lancé	Compte avec un agent lancé
Conceptions (brief ou modèle)	10	50
Runs	30	300
Messages aux agents	60	300
Lancements	10	50

30 runs manuels par agent et par 24 heures.
S'y ajoutent les limites quotidiennes du compte (messages à l'architecte, constructions de sites) et la limite d'utilisation mensuelle de chaque agent (budget_exhausted, avec un lien pour passer à la formule adaptée).
Au-delà : erreur 429 avec l'en-tête Retry-After et retryAfterSeconds. GET /account donne les quotas restants.
Serveur MCP : 20 messages JSON-RPC au plus par lot, corps de 1 Mo au plus.

Codes d'erreur

Une erreur a toujours la même forme : un code stable, une phrase qui dit quoi faire, un lien vers sa documentation et, selon le cas, des détails.

Corps d'erreur

{
  "error": {
    "code": "invalid_request",
    "message": "…",
    "docs": "…",
    "retryAfterSeconds": 12,
    "details": { "fields": { "brief": "…" } }
  }
}

401unauthorized: Clé absente, invalide ou révoquée : envoyez une clé valide.
403forbidden: La clé n'a pas la portée requise (details.scope) ou la ressource appartient à un autre compte.
404not_found: Identifiant inconnu pour ce compte : vérifiez-le avec GET /agents.
400invalid_request: Corrigez les champs listés dans details.fields.
409conflict: État incompatible (agent pas encore lancé, run terminé, prix changé) : relisez la ressource.
429rate_limited: Trop de requêtes par minute : attendez retryAfterSeconds.
429quota_exceeded: Quota quotidien du compte atteint pour cette action : réessayez après retryAfterSeconds.
429limit_reached: Limite quotidienne du compte atteinte (messages à l'architecte, constructions) : réessayez plus tard.
402payment_required: Une carte est nécessaire : faites ouvrir details.checkoutUrl une fois, elle servira pour tous les agents.
402budget_exhausted: L'agent a atteint sa limite d'utilisation du mois : details.raiseUrl propose la formule adaptée.
413storage_full: Espace de stockage plein : libérez des fichiers ou changez de forfait.
403account_required: Un compte complet est nécessaire (ni anonyme, ni bloqué).
501not_implemented: Action pas encore disponible.
500internal_error: Erreur inattendue : réessayez dans un instant.

Idempotence

Un réseau coupe, une requête part deux fois : l'en-tête Idempotency-Key (ou le champ idempotencyKey) évite le doublon. Même clé d'API, même action et même valeur pendant 24 heures : la ressource déjà créée est renvoyée au lieu d'une nouvelle.

Accepté par POST /agents, POST /agents/:id/runs et POST /templates/:slug/agents. 200 caractères au plus.
Un rejeu de run répond 200 avec replayed: true au lieu de 202.
Utilisez un identifiant de votre domaine (numéro de commande, id d'événement) ou un UUID généré une fois par opération, jamais un horodatage.
POST /agents/:id/launch est sûr à rejouer : un agent déjà actif n'est pas relancé.

Bonnes pratiques

Gardez la clé côté serveur, une clé par application, avec les seules portées utiles. Révoquez-la au moindre doute.
Confirmez toujours le prix avec l'utilisateur et passez-le dans expectedMonthlyCents.
N'inventez jamais un destinataire, une adresse e-mail ou un identifiant : posez la question à l'utilisateur et transmettez sa réponse dans answers.
Préférez les webhooks au polling ; vérifiez la signature sur le corps brut et dédoublonnez avec Future-Agent-Delivery.
Respectez Retry-After sur une erreur 429 et espacez le polling (3 secondes, puis de plus en plus).
Téléchargez les fichiers dont vous avez besoin : les liens signés expirent après 7 jours.
Testez avec test: true : un run d'essai ne déclenche jamais les agents reliés.
Affichez state.label et state.action d'un agent : ils disent à l'utilisateur ce qui l'attend (connecter une app, répondre).

Questions fréquentes

L'API est-elle payante ?

Non, aucun supplément n'est facturé pour l'API, le serveur MCP ou le CLI. Vous payez les agents que vous lancez, au même prix que sur le site, avec le même essai gratuit.

Où apparaissent les agents créés par l'API ?

Dans le dashboard du compte, comme les autres, avec un badge API, MCP ou CLI. Vous pouvez les modifier, les mettre en pause ou leur écrire depuis le dashboard.

Une IA peut-elle lancer un agent et payer sans mon accord ?

Le lancement utilise la carte enregistrée, c'est pourquoi les outils demandent de confirmer le prix et de le passer dans expectedMonthlyCents. Pour l'interdire tout à fait, créez une clé sans la portée agents:launch : elle concevra et exécutera, sans jamais démarrer d'abonnement.

Le CLI est-il disponible sur npm ?

Oui : npm install -g future-agent, puis future-agent login.

Puis-je recevoir un webhook sur localhost ?

Le serveur n'envoie qu'à une adresse https publique. Pour développer en local, exposez votre route avec un tunnel https, ou interrogez GET /runs/:id.

L'API expose-t-elle les coûts de calcul ou le modèle d'IA utilisé ?

Non. Les réponses contiennent des prix, des durées, des nombres d'exécutions et un niveau d'utilisation, jamais de coût interne ni de nom de modèle.

Dans quelle langue l'agent travaille-t-il ?

Dans la langue demandée par le champ locale ou l'en-tête Accept-Language (français ou anglais), sinon dans celle du compte.

Prêt à brancher votre premier agent ?

Créez une clé, collez la configuration MCP ou lancez le premier appel curl. Votre agent apparaît aussitôt dans votre dashboard.

Créer une clé Concevoir un agent sur le site

Vue d'ensemble

Démarrage rapide

Créez une clé

Décrivez l'agent

Lancez-le

Exécutez-le et lisez le résultat

Authentification

Cycle de vie d'un agent

1. Concevoir : mode direct ou conversation

2. Connecter les apps

3. Proposition et prix

4. Lancer : la carte, une seule fois

5. Exécuter avec des entrées

6. Lire le résultat et les fichiers

Webhooks signés

Référence de l'API

Serveur MCP

Configurer votre outil

Les 15 outils

Exemple de dialogue

CLI

Limites et quotas

Codes d'erreur

Idempotence

Bonnes pratiques

Questions fréquentes

Prêt à brancher votre premier agent ?