orangeforge.ai Télécharger

documentation

Comment Forge fonctionne

Les concepts à connaître avant d'écrire un agent : ce qu'est un agent, comment il est versionné, où il s'exécute et comment il est facturé.

En une phrase#

Un agent Forge est un dossier de votre disque — du code déterministe, des prompts, un schéma de sortie, des cas de test. forge push en fait une URL HTTPS servie mondialement, en streaming SSE. Rien d'autre à administrer.

Forge est conçu pour être piloté par un agent de code (Claude Code, Codex…) plutôt que tapé à la main. forge init installe une *skill* qui apprend à votre assistant l'ensemble des commandes et la méthodologie. En pratique vous décrivez l'intention, l'assistant édite les fichiers et lance les commandes. Voir Piloter Forge depuis un agent de code.

Pourquoi « un prompt + des tools » ne suffit plus#

La définition courante d'un agent — un prompt système et une liste d'outils — plafonne vite. Un agent de production a besoin de *décider en code* : router selon l'intention avant d'appeler le modèle, exécuter deux recherches en parallèle, appliquer une règle métier non négociable, reconstruire une réponse à partir de données vérifiées plutôt que de faire confiance au modèle.

Forge part de l'idée inverse : un agent est du code qui orchestre des appels LLM. Le fichier agent.ts est un vrai module TypeScript. Il appelle le modèle quand il en a besoin, plusieurs fois, avec des jeux d'outils différents à chaque étape, et garde la main sur tout le reste. C'est ce qui permet de garantir des propriétés qu'un prompt seul ne garantira jamais — par exemple qu'aucune référence inventée ne puisse sortir de l'agent, parce que le code ne renvoie que ce qu'il a lui-même vérifié.

Anatomie d'un agent#

agents/mon-agent/
  agent.json          # runtime, modèle, maxSteps, tools
  agent.ts            # le code de l'agent (runtime worker)
  prompt.md           # prompt système
  prompts/*.md        # prompts nommés, un par phase
  output.schema.json  # schéma JSON de la sortie
  golden/*.json       # cas de test avec leurs attentes

Ces fichiers sont la source de vérité. On ne modifie jamais l'état déployé directement : on édite un fichier, on pousse, on observe. forge pull fait le chemin inverse sur une machine neuve, et forge diff dit ce qui diverge.

Le cycle de travail#

  1. Éditer — une intention par modification, pas une refonte à chaque tour.
  2. Pousser — forge push mon-agent.
  3. Éprouver — forge bench mon-agent rejoue tous les cas du golden set.
  4. Lire les traces avant de toucher au prompt — forge trace <runId> montre chaque étape LLM, chaque appel d'outil, ses entrées et sorties, les tokens et le coût. La majorité des échecs viennent d'un outil mal décrit, pas d'un prompt mal écrit.
  5. Juger — forge verdict enregistre PASS/FAIL par cas, ce qui construit un historique de qualité.
  6. Publier — forge push --activate, seulement quand le golden set est vert.

Versions immuables#

Chaque push enregistre une version : prompts, code, configuration, schéma, plus un hash de la bibliothèque partagée (lib/) et le SHA git du workspace. La timeline (forge versions) indique pour chaque version ce qui a changé — prompt, code, lib, config ou statut.

Conséquence utile : forge trace <runId> --version restitue l'état complet de l'agent qui a produit ce run précis. Un comportement observé en production est toujours rattachable à un état exact du code, des mois plus tard. Et forge pull <slug> --version <n> réécrit les fichiers locaux depuis une version passée — c'est le rollback.

Exécution à l'edge#

Un agent en runtime: "worker" est déployé sur son propre worker Cloudflare, isolé des autres. Le tool loop tourne à l'edge, au plus près de l'appelant. L'invocation est publique :

POST https://agents.agent-forge.cc/<slug>/invoke
x-api-key: fak_…

La réponse est un flux SSE : un premier événement porte le runId, puis les événements bruts du modèle (tool-call, tool-result, text-delta…), et enfin {"type":"final","output":…}. Les traces structurées ne transitent pas par ce flux — elles se consultent dans l'UI ou avec forge trace.

Isolation entre équipes#

Chaque équipe est un tenant étanche. Le slug d'un agent n'est jamais global : c'est la clé API présentée à l'invocation qui détermine le tenant, et donc quel agent répond. Deux équipes peuvent avoir chacune un music-advisor sans se voir ni se gêner.

Une clé fak_… donne accès à tous les agents du tenant. Elle est destinée à vos serveurs — jamais à un front navigateur, où elle serait lisible par n'importe quel visiteur.

Secrets#

Les clés API de vos outils (une API métier, un service tiers) vivent en secrets du worker de l'agent, posées par forge secret set. Elles ne sont ni dans une base, ni dans un prompt, ni dans le dépôt git. Le CLI ne détient jamais de jeton Cloudflare : le déploiement est relayé par le control plane.

Les appels sortants passent par un proxy qui injecte la bonne clé au dernier moment — le code de l'agent n'a donc pas besoin de connaître la clé du modèle.

Modèles et coûts#

Vous choisissez le modèle par agent, et même par phase à l'intérieur d'un agent. Deux modes :

  • BYOK — vous branchez votre propre clé Vercel AI Gateway ou OpenRouter (forge llm set). Vos tokens sont facturés par votre fournisseur, sans marge de notre part, et le crédit Forge ne s'applique plus.
  • Crédit prépayé — vous utilisez nos clés et rechargez à l'usage (forge credit add). Le coût réel de chaque run est visible dans les traces.

La recherche web et les connecteurs applicatifs (Gmail, Notion, Slack… via Composio) sont inclus, avec un quota mensuel en offre gratuite.

Aller plus loin#