파일을 작성하고 앱을 배포하는 AI 코딩 에이전트 구축 방법

이 가이드는 SaaS 코드 빌더를 위한 구체적인 레퍼런스 통합을 구축합니다. 사용자가 채팅에서 애플리케이션을 요청하면 AgentChat은 프로비저닝된 API 계약을 읽고, SaaS API를 통해 프로젝트 파일을 작성하며, 승인된 검사를 시작하고, 실패를 수정한 다음, Cloudflare Worker를 배포하고 미리보기 URL을 반환합니다. 파일, 작업, 배포, 자격 증명 및 최종 프로젝트 UI의 소유권을 계속 유지하는 주체는 AgentChat이 아니라 코드 빌더입니다.

이 워크플로에서 AgentChat이 제공하는 기능

AppForge는 create_directory, write_file, run_build 및 deploy_worker를 위한 별도의 모델 도구를 구현하지 않습니다. 대신 이러한 작업을 일반 HTTP API로 공개하고, 정확한 API 문서 하나를 AgentChat에 등록합니다. 이 문서를 연결한 모든 채팅은 기본 제공 http_request 도구를 통해 완전한 코딩 기능 세트를 사용할 수 있습니다.

AgentChat은 비동기 추론 루프, 영속 메시지, 도구 실행 순서, 중지 및 계속 동작, 폴링 커서를 담당합니다. AppForge는 작업과 그에 대한 권한 부여를 담당합니다. 이러한 분리가 이 통합의 핵심 설계입니다.

1단계: 제어된 AppForge API 노출하기

비즈니스 API는 의도적으로 셸보다 더 좁은 범위로 제한됩니다. 모든 경로는 인증된 프로젝트 작업 공간 내에서 확인되고, 모든 변경 작업은 리비전을 반환하며, 빌드 작업은 허용 목록에서 선택됩니다.

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는 사용자 토큰을 검증하고, 프로젝트 멤버십을 확인하며, 경로 순회 공격을 거부하고, 파일 크기를 제한하고, 격리된 환경에서 검사를 실행합니다. Cloudflare 자격 증명은 AppForge 내부에 유지됩니다. 이러한 비밀 정보 중 어느 것도 API 문서에 기록되지 않습니다.

2단계: 에이전트가 실제로 받게 될 문서 작성하기

문서에는 엔드포인트 이름만 포함되어서는 안 됩니다. 안전한 순서, 요청 필드, 응답 필드, 비동기 폴링, 오류 복구 방법을 설명해야 합니다. 다음의 축약된 계약에는 에이전트의 동작을 변경하는 규칙이 포함되어 있습니다.

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

3단계: AgentChat API를 통해 해당 문서 등록

AppForge는 AgentChat 사용자 API 키를 사용하여 백엔드에서 이 프로비저닝을 수행합니다. content 필드에는 위의 전체 계약이 포함되며, 문서 링크만 포함되는 것은 아닙니다.

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

응답에는 생성된 문서 ID가 반환됩니다. AppForge는 이 ID를 코딩 에이전트 환경의 구성으로 저장합니다. 나중에 등록된 문서를 업데이트하면 문서를 모든 세션에 복사하지 않아도 이후 채팅 턴에서 사용할 수 있는 지침이 변경됩니다.

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

4단계: 현재 프로젝트 사용자를 위한 AgentChat 세션 하나 생성

AppForge 사용자가 코딩 어시스턴트를 열면 AppForge 백엔드가 세션을 생성합니다. 선택한 LLM 구성, 프로젝트 API 문서, 실행 제한, 그리고 현재 사용자의 프로젝트에만 액세스할 수 있는 단기 자격 증명을 세션에 연결합니다.

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

헤더 값은 쓰기 전용입니다. AgentChat은 HTTP 도구가 일치하는 호스트를 호출할 때만 해당 값을 주입하며, 모델은 그 값을 절대 전달받지 않습니다. 리디렉션으로 호스트가 변경되면 일치 여부를 다시 확인하므로 프로젝트 자격 증명이 다른 서비스로 전달되지 않습니다.

5단계: 코딩 실행 시작

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

엔드포인트는 상태를 processing으로 설정하여 즉시 반환합니다. 모델이 코드를 작성하는 동안 SaaS 요청을 열린 상태로 유지하지 않습니다. AgentChat이 processing 잠금을 획득하고 실행을 비동기적으로 계속합니다.

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

프로비저닝된 문서에 대해 에이전트가 수행하는 작업

1. http_request를 통해 프로젝트 트리와 기존 구성을 읽습니다.
2. 보존해야 하는 파일을 현재 리비전과 함께 읽습니다.
3. AppForge API를 통해 디렉터리를 만들고 Worker 소스, 검증 로직 및 구성을 작성합니다.
4. 승인된 빌드 작업을 시작합니다. 하나의 모델 응답에서 발생한 도구 호출은 동시에 실행되므로, 에이전트는 작업을 폴링하기 전에 별도의 턴에서 대기합니다.
5. 구조화된 진단 정보를 읽습니다. 빌드에 실패하면 해당 파일을 업데이트하고 검사를 반복합니다.
6. 성공한 리비전을 배포 엔드포인트에 제출하고 대기한 다음, 이후 턴에서 배포 상태를 폴링합니다.
7. 미리보기 URL과 변경된 파일의 간결한 목록을 반환합니다.

표시되는 모든 단계는 어시스턴트 메시지 또는 도구 메시지로 영속화됩니다. 사용자가 실행을 중지하거나 최대 턴 예산에 도달하면 AppForge는 나중에 continue를 호출할 수 있으며, AgentChat은 영속적인 기록에서 재개합니다.

6단계: AppForge 프런트엔드에서 영속 메시지 폴링하기

AppForge는 초당 한 번 폴링하고 마지막 메시지 ID와 리비전을 유지합니다. 스트리밍 중인 어시스턴트 행은 리비전이 증가하는 동안에도 동일한 ID를 유지하므로, 클라이언트는 중복 항목을 추가하는 대신 해당 행을 교체합니다.

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

AppForge 브라우저는 수명이 긴 AgentChat API 키를 전달받는 대신 자체 백엔드 또는 범위가 엄격하게 제한된 프록시를 호출해야 합니다. 백엔드는 AppForge 사용자와 프로젝트를 올바른 AgentChat 세션에 매핑합니다.

7단계: AppForge 데이터에서 배포된 애플리케이션 표시

배포 API는 deployment_id, project_id, revision, status, preview_url을 AppForge 데이터베이스에 기록합니다. AgentChat이 작업을 완료하면 기존 배포 패널이 해당 테이블을 읽고 미리 보기를 표시합니다. 채팅 메시지는 유용한 피드백이지만 시스템의 기준 데이터는 아닙니다.

이 패턴이 원활하게 확장되는 이유가 바로 여기에 있습니다. AgentChat은 작업을 조정하고, AppForge는 애플리케이션의 다른 부분이 이미 표시할 수 있는 영구적인 제품 상태를 계속 관리합니다.

이 통합을 위한 프로덕션 체크리스트