Créer un agent

Builder conversationnel, création directe, procédure écrite ou manifest YAML : toutes les façons de configurer un agent, ses entrées, ses sorties et ses outils.

Un agent FORGE est une configuration versionnée : instructions, formulaire d'entrée, schéma de sortie, outils, skills et fichiers de contexte. Vous le créez une fois, puis vous l'exécutez en run unitaire, en batch, sur planning ou dans une campagne.

Cinq façons de créer un agent

Méthode	Quand l'utiliser	API
Builder conversationnel	Vous partez d'une description en langage naturel.	`POST /v1/agents/builds`
Création directe	Vous savez exactement ce que vous voulez configurer.	`POST /v1/agents`
Depuis une procédure (SOP)	Vous disposez déjà d'un mode opératoire écrit.	`POST /v1/agents/from-sop`
Manifest YAML	Vous versionnez vos agents dans Git.	`POST /v1/agents/apply`
Depuis le catalogue	Vous partez d'un agent intégré : vérification de société, enrichissement de fiche produit, veille prix.	`POST /v1/agents/:id/clone`

Le builder pose au plus trois questions, sélectionne 3 à 8 skills et les outils, puis lance un run d'essai ; sa progression est visible en Live. L'extraction de SOP transforme un texte brut (20 à 60 000 caractères) en instructions, formulaire, schéma de sortie, étapes et outils suggérés, que vous relisez avant d'enregistrer. En création directe, POST /v1/agents/validate vérifie une configuration sans l'enregistrer.

Manifest déclaratif

apiVersion: forge/v1
kind: Agent
metadata:
  slug: verif-societe
  name: Vérification de société
spec:
  description: Identité, dirigeants, bénéficiaires effectifs et signaux de risque
  instructions: |
    Identifie la société dans Sirene, puis complète avec le RNE (INPI).
    Liste les annonces BODACC des 24 derniers mois et vérifie le gel des avoirs.
    Cite une source pour chaque champ.
  input_form:
    - name: company_name
      label: Raison sociale ou SIREN
      type: string
      required: true
  output_schema:
    type: object
    required: [siren, dirigeants]
    properties:
      siren: { type: string }
      dirigeants: { type: array, items: { type: string } }
      beneficiaires_effectifs: { type: array, items: { type: string } }
      risque: { type: string, enum: [faible, moyen, eleve] }
  tools:
    - sirene.search
    - rne.company
    - rne.documents
    - bodacc.search
    - gels_avoirs.search
    - web.search
  required_tool_calls: [sirene.search]
  side_effect_policy: deny
  default_effort: medium
  max_cost_eur: 2
skills:
  - name: lecture-bodacc
    description: Interpréter les annonces BODACC
    content_md: |
      # Lecture BODACC
      Une procédure collective ouverte est un signal de risque élevé.
context_files:
  - name: grille-risque.md
    content: |
      Faible : aucune annonce. Moyen : dirigeants modifiés récemment. Élevé : procédure collective.

# Afficher le plan de changements, sans rien écrire
forge agents apply agent.yaml --dry-run

# Appliquer le manifest
forge agents apply agent.yaml

# Exporter un agent existant en manifest
forge agents export <agent_id> -o agent.yaml

apply compare le manifest à l'agent existant, identifié par metadata.slug, et n'applique que le minimum : création, champs modifiés, skills et fichiers de contexte changés. Le mode --dry-run liste ces changements sans rien écrire. Le même manifest s'applique par l'API ou par l'outil MCP apply_agent_manifest.

Entrées, sorties, outils

Formulaire d'entrée (input_form) : champs typés string, text, number, boolean, url, email, date, enum (avec options) ou file, chacun requis ou non. Il génère le formulaire de l'app, le mapping des batches et la validation des entrées API.
Schéma de sortie (output_schema) : JSON Schema validé à la finalisation, avec une nouvelle tentative ciblée si un champ manque. output_type choisit le livrable : report, answer, json, spreadsheet, document, slides, dashboard, pdf ou site.
Outils (tools) : choisis dans le catalogue (GET /v1/tools), par exemple sirene.search, rne.company, gels_avoirs.search, web.search ou web.browse. required_tool_calls liste les outils que l'agent doit obligatoirement appeler.
Skills : savoir-faire réutilisables au format SKILL.md, issus du catalogue ou créés par votre organisation (POST /v1/skills).
Fichiers de contexte : grilles, modèles, référentiels déposés dans le workspace de chaque run (POST /v1/agents/:id/context-files).
Règles de revue (review_rules) : conditions qui envoient le run en revue humaine.

Politique d'effets de bord

Valeur	Comportement
`deny` (défaut)	Les outils qui agissent sur le monde extérieur (envoi, écriture, achat) sont refusés.
`confirm`	Chaque appel attend une approbation humaine, dans le Live ou dans la file de revue.
`allow`	Les appels s'exécutent sans confirmation. À réserver aux agents éprouvés.

Versions et tests

Toute modification de configuration (PATCH /v1/agents/:id, apply, activation d'une optimisation) crée une nouvelle version ; l'historique (GET /v1/agents/:id/versions) permet de restaurer une version antérieure. Avant de déployer, testez l'agent sur 3 à 10 entrées (POST /v1/agents/:id/test) : les runs sont comparés côte à côte sur les champs requis, les sources, le coût et la durée.