Comment créer un agent de programmation IA qui écrit des fichiers et déploie une application

Ce guide met en place une intégration de référence concrète pour un générateur de code SaaS. L’utilisateur demande une application dans le chat ; AgentChat lit le contrat d’API provisionné, écrit les fichiers du projet via l’API du SaaS, lance les vérifications approuvées, corrige les échecs, déploie un Cloudflare Worker et renvoie l’URL de prévisualisation. Le générateur de code, et non AgentChat, reste responsable des fichiers, des tâches, des déploiements, des identifiants et de l’interface finale du projet.

Ce qu’AgentChat apporte à ce flux de travail

AppForge n’implémente pas d’outil de modèle distinct pour create_directory, write_file, run_build et deploy_worker. Il publie ces opérations sous forme d’API HTTP standard et enregistre un document d’API précis dans AgentChat. Chaque chat auquel ce document est associé bénéficie de l’ensemble complet des capacités de programmation grâce à l’outil intégré http_request.

AgentChat prend en charge la boucle de raisonnement asynchrone, les messages persistants, l’ordre d’exécution des outils, le comportement d’arrêt et de reprise, ainsi que le curseur d’interrogation. AppForge prend en charge les opérations et leur autorisation. Cette séparation constitue la conception centrale de l’intégration.

Étape 1 : exposer une API AppForge contrôlée

L’API métier est volontairement plus limitée qu’un shell. Chaque chemin est résolu au sein de l’espace de travail du projet authentifié, chaque mutation renvoie une révision et les tâches de build sont sélectionnées à partir d’une liste d’autorisation.

GET    /v1/projects/{project_id}/tree
GET    /v1/projects/{project_id}/files?path=src/index.ts
POST   /v1/projects/{project_id}/directories
PUT    /v1/projects/{project_id}/files
DELETE /v1/projects/{project_id}/files?path=src/old.ts
POST   /v1/projects/{project_id}/checks
GET    /v1/checks/{job_id}
POST   /v1/projects/{project_id}/deployments
GET    /v1/deployments/{deployment_id}

AppForge valide le jeton utilisateur, vérifie l’appartenance au projet, rejette les traversées de chemin, limite la taille des fichiers et exécute les vérifications dans un environnement isolé. Les identifiants Cloudflare restent dans AppForge. Aucun de ces secrets n’est écrit dans le document de l’API.

Étape 2 : rédiger le document que l’agent recevra réellement

Le document doit contenir plus que les noms des points de terminaison. Il doit expliquer les séquences sûres, les champs de requête, les champs de réponse, l’interrogation asynchrone et la manière de récupérer après des erreurs. Le contrat abrégé suivant contient les règles qui modifient le comportement de l’agent.

# AppForge Project API

Base URL: https://builder.example.com/v1

All paths are relative to the project workspace. Never use absolute paths or ../.

## Read project tree
GET /projects/{project_id}/tree
Returns entries with path, type, revision, and bytes. Read the tree before editing.

## Write complete file
PUT /projects/{project_id}/files
Body: path, content, expected_revision.
For a new file omit expected_revision. For an existing file, read it first and send its revision.

## Run approved check
POST /projects/{project_id}/checks
Body task is one of format, typecheck, test, build.
Returns job_id, status, poll_after_seconds. Start the job in one model turn. Wait and poll in a later turn.

## Read check
GET /checks/{job_id}
When failed, diagnostics contains file, line, category, and message. Fix the files and run the check again.

## Deploy validated revision
POST /projects/{project_id}/deployments
Body target=cloudflare-worker, environment=preview, revision. Only deploy the revision returned by a successful build.
Returns deployment_id and poll_after_seconds. Poll GET /deployments/{deployment_id} until succeeded or failed.

Étape 3 : enregistrer ce document via l’API AgentChat

AppForge effectue ce provisionnement depuis son backend à l’aide d’une clé d’API utilisateur AgentChat. Le champ de contenu contient l’intégralité du contrat ci-dessus, et pas seulement un lien vers la documentation.

curl -X POST "$AGENT_CHAT_URL/api/api-documents" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "AppForge Project and Deployment API",
    "description": "Read and modify a scoped project, run approved checks, and deploy a validated revision.",
    "content": "# AppForge Project API\n\nBase URL: https://builder.example.com/v1\n...complete contract..."
  }'

La réponse renvoie un identifiant de document généré. AppForge enregistre cet identifiant dans la configuration de son expérience avec l’agent de codage. La mise à jour ultérieure du document enregistré modifie les instructions disponibles lors des tours de conversation suivants, sans qu’il soit nécessaire de copier le document dans chaque session.

{ "success": true, "data": { "id": "doc_uuid", "title": "AppForge Project and Deployment API" } }

Étape 4 : créer une session AgentChat pour l’utilisateur du projet actuel

Lorsqu’un utilisateur d’AppForge ouvre l’assistant de programmation, le backend d’AppForge crée une session. Il associe la configuration LLM sélectionnée, le document d’API du projet, les limites d’utilisation et un identifiant d’accès à courte durée de vie qui ne peut accéder qu’au projet de l’utilisateur actuel.

curl -X POST "$AGENT_CHAT_URL/api/agent/sessions" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "Build project prj_42",
    "llm_config_id": "llm_config_uuid",
    "api_document_ids": ["doc_uuid"],
    "system_prompt": "You are the coding agent for project prj_42. Make focused changes, validate them, and deploy only after build succeeds.",
    "max_turns": 30,
    "tool_timeout_seconds": 120,
    "tool_result_max_chars": 20000,
    "host_headers": [
      { "host": "builder.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_project_token" },
      { "host": "builder.example.com", "header_key": "X-Project-ID", "header_value": "prj_42" }
    ]
  }'

Les valeurs des en-têtes sont en écriture seule. AgentChat ne les injecte que lorsque l’outil HTTP appelle l’hôte correspondant, et le modèle ne reçoit jamais leurs valeurs. Si une redirection modifie l’hôte, la correspondance est réévaluée afin que les identifiants du projet ne soient pas transmis à un autre service.

Étape 5 : démarrer l’exécution de programmation

curl -X POST "$AGENT_CHAT_URL/api/agent/sessions/session_uuid/chat" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{ "message": "Create a feedback form as a Cloudflare Worker. Store submissions in the existing FEEDBACK KV binding, add validation, run the build, and deploy a preview." }'

Le point de terminaison répond immédiatement avec l’état « processing ». Il ne maintient pas la requête SaaS ouverte pendant que le modèle écrit du code. AgentChat acquiert le verrou de traitement et poursuit l’exécution de manière asynchrone.

{ "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

Ce que l’agent fait avec le document provisionné

1. Lire l’arborescence du projet et la configuration existante via http_request.
2. Lire les fichiers qui doivent être préservés, y compris leurs révisions actuelles.
3. Créez des répertoires et écrivez le code source du Worker, la logique de validation et la configuration via les API d’AppForge.
4. Démarrez le travail de build approuvé. Comme les appels d’outils d’une même réponse du modèle s’exécutent simultanément, l’agent attend lors d’un tour séparé avant d’interroger le travail.
5. Lisez les diagnostics structurés. Si le build échoue, mettez à jour le fichier exact et répétez la vérification.
6. Soumettez la révision validée au point de terminaison de déploiement, attendez, puis interrogez le déploiement lors de tours ultérieurs.
7. Renvoyez l’URL de prévisualisation et une liste concise des fichiers modifiés.

Chaque étape visible est enregistrée sous forme de message de l’assistant ou d’un outil. Si l’utilisateur arrête l’exécution ou si le nombre maximal de tours est atteint, AppForge peut appeler continue ultérieurement et AgentChat reprend à partir de l’historique persistant.

Étape 6 : interroger les messages persistants depuis le frontend d’AppForge

AppForge interroge le système une fois par seconde et conserve le dernier identifiant de message ainsi que la révision. Une ligne d’assistant en streaming conserve le même identifiant tandis que sa révision augmente ; le client remplace donc cette ligne au lieu d’ajouter des doublons.

GET /api/agent/sessions/session_uuid/messages?after_id=last_message_uuid&after_revision=4
Authorization: Bearer ac_live_AGENT_CHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "msg_uuid", "role": "assistant", "content": "Build passed...", "stream_status": "streaming", "revision": 5 }],
    "last_id": "msg_uuid",
    "last_revision": 5,
    "is_processing": true,
    "total_tokens": 8421
  }
}

Le navigateur AppForge doit appeler son propre backend ou un proxy à portée strictement limitée, plutôt que de recevoir la clé API AgentChat persistante. Le backend associe l’utilisateur et le projet AppForge à la session AgentChat appropriée.

Étape 7 : afficher l’application déployée à partir des données AppForge

L’API de déploiement écrit deployment_id, project_id, revision, status et preview_url dans la base de données AppForge. Une fois qu’AgentChat a terminé, le panneau de déploiement existant lit cette table et affiche la prévisualisation. Le message de chat constitue un retour utile, mais il ne fait pas foi dans le système.

C’est pourquoi ce modèle s’étend facilement : AgentChat coordonne les opérations, tandis qu’AppForge reste responsable de l’état durable du produit que le reste de l’application sait déjà afficher.

Liste de contrôle de production pour cette intégration précise