ファイルを書き込み、アプリをデプロイするAIコーディングエージェントの構築方法

このガイドでは、SaaSコードビルダー向けの具体的なリファレンス統合を構築します。ユーザーがチャットでアプリケーションを依頼すると、AgentChatはプロビジョニング済みのAPIコントラクトを読み取り、SaaS APIを介してプロジェクトファイルを書き込み、承認済みのチェックを開始し、失敗を修正し、Cloudflare Workerをデプロイして、プレビューURLを返します。ファイル、ジョブ、デプロイ、認証情報、最終的なプロジェクトUIの所有権を引き続き持つのはAgentChatではなくコードビルダーです。

このワークフローでAgentChatが担う役割

AppForgeは、create_directory、write_file、run_build、deploy_worker用の個別のモデルツールを実装していません。これらの操作を通常のHTTP APIとして公開し、正確なAPIドキュメントを1つ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 セッションを 1 つ作成する

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. 承認済みのビルドジョブを開始します。1回のモデル応答からのツール呼び出しは並行して実行されるため、エージェントはジョブをポーリングする前に別のターンで待機します。
5. 構造化された診断情報を読み取ります。ビルドに失敗した場合は、該当するファイルを更新してチェックを繰り返します。
6. 成功したリビジョンをデプロイエンドポイントに送信し、待機してから、後続のターンでデプロイをポーリングします。
7. プレビューURLと、変更したファイルの簡潔な一覧を返します。

表示されるすべてのステップは、アシスタントメッセージまたはツールメッセージとして永続化されます。ユーザーが実行を停止した場合や、ターン数の上限に達した場合、AppForgeは後でcontinueを呼び出すことができ、AgentChatは永続的な履歴から再開します。

ステップ6：AppForgeフロントエンドから永続メッセージをポーリングする

AppForgeは毎秒1回ポーリングし、最後のメッセージ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 は、アプリケーションの他の部分がすでに表示方法を把握している永続的なプロダクト状態を引き続き管理します。

この統合に特化した本番環境チェックリスト