Campagnes multi-agents

Enchaîner plusieurs agents dans un plan en graphe, le relire et l'approuver, puis suivre son exécution sur un graphe animé.

Une campagne enchaîne plusieurs agents dans un plan en graphe orienté (DAG) : une étape trouve des entités, les suivantes les vérifient et les analysent, puis les résultats sont fusionnés, synthétisés et exportés. Un plan compte jusqu'à 32 étapes.

Le plan

Type d'étape	Rôle
`agent`, `fanout: root`	Produit la liste des entités de départ (`max_entities`, 500 par défaut).
`agent`, `fanout: per_entity`	Lance un run par entité issue des étapes amont.
`agent`, `fanout: aggregate`	Lance un seul run sur l'ensemble des résultats : synthèse, classement.
`join`	Fusionne au moins deux étapes par entité, en mode `inner` ou `left`.
`export`	Produit un livrable CSV ou XLSX, avec colonnes et nom de feuille au choix.
`metrics`	Calcule des indicateurs sur les champs choisis.

{
  "name": "E-commerçants maison FR",
  "objective": "Identifier 200 e-commerçants français de la maison et qualifier leur solidité",
  "plan": {
    "stages": [
      { "key": "sourcing", "type": "agent", "agent_id": "a1…", "fanout": "root",
        "question": "Trouve 200 e-commerçants français spécialisés dans la maison", "max_entities": 200 },
      { "key": "kyb", "type": "agent", "agent_id": "b2…", "fanout": "per_entity",
        "depends_on": ["sourcing"], "inputs": { "company_name": "name" }, "effort": "low" },
      { "key": "stack", "type": "agent", "agent_id": "c3…", "fanout": "per_entity",
        "depends_on": ["sourcing"], "inputs": { "website": "website" } },
      { "key": "fusion", "type": "join", "depends_on": ["kyb", "stack"] },
      { "key": "fichier", "type": "export", "format": "xlsx", "depends_on": ["fusion"] },
      { "key": "synthese", "type": "agent", "agent_id": "d4…", "fanout": "aggregate",
        "depends_on": ["fusion"] }
    ]
  }
}

Les inputs d'une étape pointent vers un champ du contexte (website, stages.kyb.siren, entity_key), une valeur fixe ({ "value": … }) ou un gabarit ({ "template": … }). accept_if fixe les conditions qu'une entité doit remplir pour être retenue ; les autres sont marquées exclues, avec la raison.

Brouillon, approbation, exécution

Créez la campagne : elle reste en brouillon (POST /v1/campaigns).
Modifiez le plan autant que nécessaire : chaque modification crée une révision (PATCH /v1/campaigns/:id).
Approuvez la révision relue. L'approbation porte sur l'empreinte SHA-256 du plan (digest) : un plan modifié après relecture doit être approuvé à nouveau.
L'exécution démarre. Les étapes s'enchaînent selon leurs dépendances ; les étapes indépendantes, comme kyb et stack ci-dessus, tournent en parallèle.

# Lire la campagne et son empreinte de plan
curl https://api.forge.example/v1/campaigns/<campaign_id> \
  -H "Authorization: Bearer $FORGE_API_KEY"

# Approuver la révision relue
curl -X POST https://api.forge.example/v1/campaigns/<campaign_id>/approve \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "digest": "<empreinte de la révision relue>" }'

Graphe Live et incidents

Dans le Live, le graphe des étapes s'anime : enregistrements qui circulent d'une étape à l'autre, compteurs, coût. Un clic sur une étape ouvre ses runs. Si plus de 20 % des runs d'une étape échouent, la campagne passe en needs_attention avec une action suggérée et l'événement campaign.needs_attention est émis. Après correction, relancez avec POST /v1/campaigns/:id/retry. Par API, le flux agrégé est disponible sur /v1/campaigns/:id/live.

Livrables

Les livrables (fichiers CSV ou XLSX, synthèse) sont listés par GET /v1/campaigns/:id/artifacts ; les enregistrements d'une étape, acceptés ou exclus, par GET /v1/campaigns/:id/stages/:key/records. L'événement campaign.completed signale la fin de la campagne.