Cómo crear un agente de programación con IA que escribe archivos y despliega una aplicación

Esta guía crea una integración de referencia concreta para un generador de código SaaS. El usuario solicita una aplicación en el chat; AgentChat lee el contrato de API aprovisionado, escribe los archivos del proyecto a través de la API del SaaS, inicia comprobaciones aprobadas, corrige los fallos, despliega un Cloudflare Worker y devuelve la URL de vista previa. El generador de código, no AgentChat, sigue siendo responsable de los archivos, los trabajos, los despliegues, las credenciales y la interfaz final del proyecto.

Qué aporta AgentChat a este flujo de trabajo

AppForge no implementa una herramienta de modelo independiente para create_directory, write_file, run_build y deploy_worker. Publica esas operaciones como API HTTP normales y registra un documento de API preciso en AgentChat. Cada chat al que se adjunta este documento obtiene el conjunto completo de capacidades de programación mediante la herramienta integrada http_request.

AgentChat se encarga del bucle de razonamiento asíncrono, los mensajes persistentes, el orden de ejecución de las herramientas, el comportamiento de detención y continuación, y el cursor de sondeo. AppForge se encarga de las operaciones y su autorización. Esta separación es el diseño central de la integración.

Paso 1: exponer una API controlada de AppForge

La API empresarial es intencionadamente más limitada que un shell. Cada ruta se resuelve dentro del espacio de trabajo del proyecto autenticado, cada mutación devuelve una revisión y las tareas de compilación se seleccionan de una lista de permitidos.

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 valida el token del usuario, verifica la pertenencia al proyecto, rechaza el recorrido de rutas, limita el tamaño de los archivos y ejecuta las comprobaciones en un entorno aislado. Las credenciales de Cloudflare permanecen dentro de AppForge. Ninguno de esos secretos se escribe en el documento de la API.

Paso 2: escribir el documento que el agente recibirá realmente

El documento debe incluir algo más que los nombres de los endpoints. Debe explicar las secuencias seguras, los campos de solicitud, los campos de respuesta, el sondeo asíncrono y cómo recuperarse de los errores. El siguiente contrato abreviado contiene las reglas que cambian el comportamiento del 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.

Paso 3: registrar ese documento mediante la API de AgentChat

AppForge realiza este aprovisionamiento desde su backend utilizando una clave de API de usuario de AgentChat. El campo de contenido contiene el contrato completo anterior, no solo un enlace a la documentación.

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 respuesta devuelve un ID de documento generado. AppForge almacena este ID como configuración para su experiencia con el agente de codificación. Actualizar posteriormente el documento registrado cambia las instrucciones disponibles para los turnos de chat posteriores sin copiar el documento en cada sesión.

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

Paso 4: crear una sesión de AgentChat para el usuario del proyecto actual

Cuando un usuario de AppForge abre el asistente de programación, el backend de AppForge crea una sesión. Vincula la configuración de LLM seleccionada, el documento de API del proyecto, los límites operativos y una credencial de corta duración que solo puede acceder al proyecto del usuario actual.

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

Los valores de los encabezados son de solo escritura. AgentChat solo los inyecta cuando la herramienta HTTP realiza una llamada al host correspondiente, y el modelo nunca recibe sus valores. Si una redirección cambia el host, se vuelve a evaluar la coincidencia para que las credenciales del proyecto no se transfieran a otro servicio.

Paso 5: iniciar la ejecución de programación

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

El endpoint responde inmediatamente con el estado «processing». No mantiene abierta la solicitud de SaaS mientras el modelo escribe código. AgentChat adquiere el bloqueo de procesamiento y continúa la ejecución de forma asíncrona.

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

Qué hace el agente con el documento aprovisionado

1. Leer el árbol del proyecto y la configuración existente mediante http_request.
2. Leer los archivos que deben conservarse, incluidas sus revisiones actuales.
3. Cree directorios y escriba el código fuente del Worker, la lógica de validación y la configuración mediante las API de AppForge.
4. Inicie el trabajo de compilación aprobado. Como las llamadas a herramientas de una misma respuesta del modelo se ejecutan simultáneamente, el agente espera en un turno separado antes de consultar el trabajo.
5. Lea los diagnósticos estructurados. Si la compilación falla, actualice el archivo exacto y repita la comprobación.
6. Envíe la revisión correcta al endpoint de despliegue, espere y consulte el despliegue en turnos posteriores.
7. Devuelva la URL de vista previa y una lista concisa de los archivos modificados.

Cada paso visible se conserva como un mensaje del asistente o de una herramienta. Si el usuario detiene la ejecución o se alcanza el presupuesto máximo de turnos, AppForge puede llamar a continue más adelante y AgentChat reanuda la ejecución a partir del historial persistente.

Paso 6: consultar los mensajes persistentes desde el frontend de AppForge

AppForge consulta una vez por segundo y conserva el último ID de mensaje y la revisión. Una fila de asistente en streaming mantiene el mismo ID mientras aumenta su revisión, por lo que el cliente reemplaza esa fila en lugar de añadir duplicados.

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

El navegador de AppForge debe llamar a su propio backend o a un proxy con un alcance estrictamente limitado, en lugar de recibir la clave de API de AgentChat de larga duración. El backend vincula al usuario y el proyecto de AppForge con la sesión de AgentChat correcta.

Paso 7: mostrar la aplicación desplegada a partir de los datos de AppForge

La API de despliegue escribe deployment_id, project_id, revision, status y preview_url en la base de datos de AppForge. Cuando AgentChat termina, el panel de despliegue existente lee esa tabla y muestra la vista previa. El mensaje del chat proporciona información útil, pero no es la fuente de verdad del sistema.

Por eso este patrón se puede ampliar fácilmente: AgentChat coordina las operaciones, mientras que AppForge sigue siendo responsable del estado persistente del producto que el resto de la aplicación ya sabe mostrar.

Lista de comprobación de producción para esta integración exacta