So erstellen Sie einen KI-Coding-Agenten, der Dateien schreibt und eine App bereitstellt

Dieser Leitfaden erstellt eine konkrete Referenzintegration für einen SaaS-Code-Builder. Der Benutzer bittet im Chat um eine Anwendung; AgentChat liest den bereitgestellten API-Vertrag, schreibt Projektdateien über die SaaS-API, startet genehmigte Prüfungen, behebt Fehler, stellt einen Cloudflare Worker bereit und gibt die Vorschau-URL zurück. Der Code-Builder – nicht AgentChat – bleibt für Dateien, Jobs, Deployments, Zugangsdaten und die endgültige Projektoberfläche zuständig.

Was AgentChat zu diesem Workflow beiträgt

AppForge implementiert kein separates Modelltool für create_directory, write_file, run_build und deploy_worker. Stattdessen veröffentlicht es diese Vorgänge als normale HTTP-APIs und registriert ein genaues API-Dokument in AgentChat. Jeder Chat, an den dieses Dokument angehängt wird, erhält über das integrierte http_request-Tool das vollständige Paket an Coding-Funktionen.

AgentChat ist für die asynchrone Reasoning-Schleife, dauerhaft gespeicherte Nachrichten, die Reihenfolge der Tool-Ausführung, das Beenden und Fortsetzen sowie den Polling-Cursor zuständig. AppForge ist für die Vorgänge und deren Autorisierung verantwortlich. Diese Trennung bildet das zentrale Design der Integration.

Schritt 1: Eine kontrollierte AppForge-API bereitstellen

Die Geschäfts-API ist bewusst enger gefasst als eine Shell. Jeder Pfad wird innerhalb des authentifizierten Projektarbeitsbereichs aufgelöst, jede Änderung gibt eine Revision zurück, und Build-Aufgaben werden aus einer Allowlist ausgewählt.

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 validiert das Benutzertoken, überprüft die Projektmitgliedschaft, weist Pfad-Traversal zurück, begrenzt die Dateigröße und führt Prüfungen in einer isolierten Umgebung aus. Cloudflare-Zugangsdaten verbleiben in AppForge. Keine dieser Geheimnisse wird in das API-Dokument geschrieben.

Schritt 2: Das Dokument schreiben, das der Agent tatsächlich erhält

Das Dokument muss mehr als nur Endpunktnamen enthalten. Es muss sichere Abläufe, Anfragefelder, Antwortfelder, asynchrones Polling und die Fehlerbehebung erläutern. Der folgende verkürzte Vertrag enthält die Regeln, die das Verhalten des Agenten ändern.

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

Schritt 3: Registrieren Sie dieses Dokument über die AgentChat-API

AppForge führt diese Bereitstellung über sein Backend mithilfe eines AgentChat-Benutzer-API-Schlüssels durch. Das Inhaltsfeld enthält den vollständigen oben genannten Vertrag und nicht lediglich einen Link zur Dokumentation.

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

Die Antwort enthält eine generierte Dokument-ID. AppForge speichert diese ID als Konfiguration für seine Coding-Agent-Erfahrung. Wenn das registrierte Dokument später aktualisiert wird, ändern sich die Anweisungen, die für nachfolgende Chat-Nachrichten verfügbar sind, ohne dass das Dokument in jede Sitzung kopiert werden muss.

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

Schritt 4: Erstellen Sie eine AgentChat-Sitzung für den Benutzer des aktuellen Projekts

Wenn ein AppForge-Benutzer den Coding-Assistenten öffnet, erstellt das AppForge-Backend eine Sitzung. Es bindet die ausgewählte LLM-Konfiguration, das API-Dokument des Projekts, Betriebsgrenzen und ein kurzlebiges Zugangstoken, das nur auf das Projekt des aktuellen Benutzers zugreifen kann.

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

Header-Werte sind nur schreibbar. AgentChat fügt sie nur ein, wenn das HTTP-Tool den passenden Host aufruft, und das Modell erhält ihre Werte niemals. Wenn eine Weiterleitung den Host ändert, wird die Zuordnung erneut geprüft, damit Projektzugangsdaten nicht an einen anderen Dienst weitergegeben werden.

Schritt 5: Coding-Lauf starten

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

Der Endpunkt antwortet sofort mit dem Status „processing“. Er hält die SaaS-Anfrage nicht offen, während das Modell Code schreibt. AgentChat übernimmt die Verarbeitungssperre und setzt den Lauf asynchron fort.

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

Was der Agent mit dem bereitgestellten Dokument macht

1. Den Projektbaum und die vorhandene Konfiguration über http_request lesen.
2. Dateien lesen, die beibehalten werden müssen, einschließlich ihrer aktuellen Revisionen.
3. Erstellen Sie über die AppForge-APIs Verzeichnisse und schreiben Sie den Worker-Quellcode, die Validierungslogik und die Konfiguration.
4. Starten Sie den genehmigten Build-Auftrag. Da Tool-Aufrufe aus derselben Modellantwort gleichzeitig ausgeführt werden, wartet der Agent in einem separaten Durchlauf, bevor er den Auftrag abfragt.
5. Lesen Sie die strukturierten Diagnosedaten. Wenn der Build fehlschlägt, aktualisieren Sie die genaue Datei und wiederholen Sie die Prüfung.
6. Übermitteln Sie die erfolgreiche Revision an den Deployment-Endpunkt, warten Sie und fragen Sie das Deployment in späteren Durchläufen ab.
7. Geben Sie die Vorschau-URL und eine kurze Liste der geänderten Dateien zurück.

Jeder sichtbare Schritt wird als Assistenten- oder Tool-Nachricht gespeichert. Wenn der Benutzer den Durchlauf stoppt oder das maximale Durchlaufkontingent erreicht ist, kann AppForge später continue aufrufen, und AgentChat setzt den Vorgang anhand des dauerhaft gespeicherten Verlaufs fort.

Schritt 6: Dauerhafte Nachrichten vom AppForge-Frontend abfragen

AppForge fragt einmal pro Sekunde ab und speichert die letzte Nachrichten-ID und Revision. Eine gestreamte Assistentenzeile behält dieselbe ID bei, während ihre Revision steigt, sodass der Client diese Zeile ersetzt, anstatt Duplikate anzuhängen.

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

Der AppForge-Browser sollte sein eigenes Backend oder einen eng begrenzten Proxy aufrufen, statt den langlebigen AgentChat-API-Schlüssel zu erhalten. Das Backend ordnet den AppForge-Benutzer und das Projekt der richtigen AgentChat-Sitzung zu.

Schritt 7: Die bereitgestellte Anwendung aus den AppForge-Daten anzeigen

Die Deployment-API schreibt deployment_id, project_id, revision, status und preview_url in die AppForge-Datenbank. Nachdem AgentChat den Vorgang abgeschlossen hat, liest das vorhandene Deployment-Panel diese Tabelle und zeigt die Vorschau an. Die Chatnachricht ist ein nützliches Feedback, aber nicht die maßgebliche Datenquelle.

Deshalb lässt sich dieses Muster problemlos erweitern: AgentChat koordiniert die Vorgänge, während AppForge weiterhin für den dauerhaft gespeicherten Produktstatus verantwortlich ist, den der Rest der Anwendung bereits anzeigen kann.

Produktions-Checkliste für genau diese Integration