Come creare un agente di programmazione con IA che scrive file e distribuisce un’app

Questa guida realizza un'integrazione di riferimento concreta per un generatore di codice SaaS. L'utente richiede un'applicazione nella chat; AgentChat legge il contratto API fornito, scrive i file del progetto tramite l'API SaaS, avvia i controlli approvati, corregge gli errori, distribuisce un Cloudflare Worker e restituisce l'URL di anteprima. Il generatore di codice, non AgentChat, continua a essere responsabile dei file, dei job, dei deployment, delle credenziali e dell'interfaccia finale del progetto.

Cosa apporta AgentChat a questo flusso di lavoro

AppForge non implementa uno strumento del modello separato per create_directory, write_file, run_build e deploy_worker. Pubblica queste operazioni come normali API HTTP e registra un documento API accurato in AgentChat. Ogni chat a cui viene allegato questo documento ottiene il pacchetto completo di funzionalità di programmazione tramite lo strumento http_request integrato.

AgentChat gestisce il ciclo di ragionamento asincrono, i messaggi persistenti, l’ordine di esecuzione degli strumenti, il comportamento di arresto e continuazione e il cursore di polling. AppForge gestisce le operazioni e la relativa autorizzazione. Questa separazione costituisce il design centrale dell’integrazione.

Passaggio 1: esporre un’API AppForge controllata

L’API aziendale è intenzionalmente più ristretta di una shell. Ogni percorso viene risolto all’interno dell’area di lavoro del progetto autenticato, ogni mutazione restituisce una revisione e le attività di build vengono selezionate da una lista di elementi consentiti.

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 convalida il token dell’utente, verifica l’appartenenza al progetto, rifiuta il path traversal, limita le dimensioni dei file ed esegue i controlli in un ambiente isolato. Le credenziali Cloudflare rimangono all’interno di AppForge. Nessuno di questi segreti viene scritto nel documento dell’API.

Passaggio 2: scrivere il documento che l’agente riceverà effettivamente

Il documento deve includere più dei soli nomi degli endpoint. Deve spiegare le sequenze sicure, i campi della richiesta, i campi della risposta, il polling asincrono e come recuperare dagli errori. Il seguente contratto abbreviato contiene le regole che modificano il comportamento dell’agente.

# 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.

Passaggio 3: registrare il documento tramite l’API AgentChat

AppForge esegue questo provisioning dal proprio backend utilizzando una chiave API utente di AgentChat. Il campo del contenuto contiene il contratto completo riportato sopra, non semplicemente un link alla documentazione.

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 risposta restituisce un ID documento generato. AppForge memorizza questo ID nella configurazione della propria esperienza con l’agente di codifica. L’aggiornamento successivo del documento registrato modifica le istruzioni disponibili per i turni di chat successivi, senza dover copiare il documento in ogni sessione.

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

Passaggio 4: creare una sessione AgentChat per l’utente del progetto corrente

Quando un utente di AppForge apre l’assistente di programmazione, il backend di AppForge crea una sessione. Associa la configurazione LLM selezionata, il documento API del progetto, i limiti operativi e una credenziale a breve durata che può accedere solo al progetto dell’utente corrente.

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" }
    ]
  }'

I valori degli header sono di sola scrittura. AgentChat li inserisce solo quando lo strumento HTTP chiama l’host corrispondente, e il modello non riceve mai i loro valori. Se un reindirizzamento cambia l’host, la corrispondenza viene valutata nuovamente, in modo che le credenziali del progetto non vengano trasferite a un altro servizio.

Passaggio 5: avviare l’esecuzione di programmazione

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." }'

L’endpoint risponde immediatamente con lo stato «processing». Non mantiene aperta la richiesta SaaS mentre il modello scrive il codice. AgentChat acquisisce il blocco di elaborazione e continua l’esecuzione in modo asincrono.

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

Cosa fa l’agente con il documento predisposto

1. Leggere l’albero del progetto e la configurazione esistente tramite http_request.
2. Leggere i file che devono essere conservati, comprese le relative revisioni attuali.
3. Crea le directory e scrivi il codice sorgente del Worker, la logica di convalida e la configurazione tramite le API di AppForge.
4. Avvia il processo di build approvato. Poiché le chiamate agli strumenti provenienti dalla stessa risposta del modello vengono eseguite contemporaneamente, l’agente attende in un turno separato prima di interrogare il processo.
5. Leggi i diagnostici strutturati. Se la build non riesce, aggiorna il file esatto e ripeti il controllo.
6. Invia la revisione riuscita all’endpoint di deployment, attendi e interroga il deployment nei turni successivi.
7. Restituisci l’URL di anteprima e un elenco conciso dei file modificati.

Ogni passaggio visibile viene salvato come messaggio dell’assistente o di uno strumento. Se l’utente interrompe l’esecuzione o viene raggiunto il numero massimo di turni, AppForge può chiamare continue in un momento successivo e AgentChat riprende dalla cronologia persistente.

Passaggio 6: interroga i messaggi persistenti dal frontend di AppForge

AppForge esegue un’interrogazione al secondo e conserva l’ultimo ID del messaggio e la revisione. Una riga dell’assistente in streaming mantiene lo stesso ID mentre la revisione aumenta, quindi il client sostituisce quella riga invece di aggiungere duplicati.

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
  }
}

Il browser di AppForge dovrebbe chiamare il proprio backend o un proxy con ambito strettamente limitato, invece di ricevere la chiave API AgentChat a lunga durata. Il backend associa l’utente e il progetto AppForge alla sessione AgentChat corretta.

Passaggio 7: visualizzare l’applicazione distribuita dai dati di AppForge

L’API di distribuzione scrive deployment_id, project_id, revision, status e preview_url nel database di AppForge. Al termine di AgentChat, il pannello di distribuzione esistente legge quella tabella e visualizza l’anteprima. Il messaggio della chat è un feedback utile, ma non è la fonte di verità del sistema.

Per questo il modello si estende facilmente: AgentChat coordina le operazioni, mentre AppForge rimane responsabile dello stato persistente del prodotto che il resto dell’applicazione sa già visualizzare.

Checklist di produzione per questa specifica integrazione