Long-Horizon AI Agent Tasks in Practice: A Full-Stack Development Guide

    This article presents a spec-driven development approach for long-running AI agent tasks, using a short-video UGC generation SaaS platform as a test case. It covers the three workflow stages, core modules, task state machine, asynchronous queue handling, authentication, idempotent credit billing, file access, context management, and acceptance criteria, along with the limits of agent-driven engineering.

    Long-Horizon AI Agent Tasks in Practice: A Full-Stack Development Guide

    1. Problem Background: From Generating Pages to Delivering Systems

    Until recently, the most common demonstration of AI coding tools was generating a web page quickly or completing a function. These demos are useful, but they remain far from real business systems. A SaaS product that can go live or be verified includes at least requirements breakdown, data modeling, API design, asynchronous jobs, authentication and billing, error handling, logging and monitoring, and an acceptance process. The page is only the outermost layer. Systems engineering determines whether a project actually works.

    This article uses a short-video UGC generation SaaS platform as a test case. Users upload images or materials, enter product information and style requirements, and the system creates a video generation task. The task is queued for asynchronous processing. When it finishes, the user receives a video result that can be previewed and downloaded. The platform provides phone number and verification code login, token-based authentication, credit deduction, task querying, and failure compensation. This scenario covers long-running asynchronous tasks, user management, billing consistency, and frontend interaction. It is a good way to test whether an AI agent can maintain context, split tasks, and close the engineering loop during a long-horizon task.

    This article discusses general technical methods. It does not review or recommend any specific product. The experiment aims to verify whether an agent working under a spec-driven development process can keep its structure clear across an automated task lasting several hours, and deliver reviewable engineering outputs stage by stage.

    2. Why Spec-Driven Development

    The biggest risk in a long-horizon task is not that the agent cannot write code. It is that the work drifts away from the goal over time. Without stable specifications, an agent tends to keep revising local implementations. This leads to inconsistent interfaces, drifting data models, and missing acceptance criteria. For this reason, the experiment uses SDD (Spec-Driven Development) and divides the process into three stages:

    1. Research and constraint clarification: Define business goals, user roles, core flows, non-functional constraints, and boundary conditions.
    2. Architecture and specification lock-in: Produce the module breakdown, data tables, interface contracts, state machines, error codes, and an acceptance checklist.
    3. Development and verification loop: Implement according to the spec, run checks item by item, record deviations, and fix regressions.

    At the prompt level, avoid vague goals such as “build a video generation website.” Write an executable spec instead, for example:

    1. Goal: Build a minimum viable version of a short-video UGC generation SaaS.
    2. Roles: Visitors, regular users, operations administrators.
    3. Core flow: Log in -> create task -> deduct credits -> queue generation -> query result -> download.
    4. Constraints: Generation tasks must be asynchronous; credit deduction must be idempotent; task status must be traceable; failures must be compensable.
    5. Deliverables: Data model, API contracts, frontend and backend code, acceptance scripts, run instructions.
    6. Process: Research first and list assumptions, then present the architecture, then develop module by module. Output a checkpoint after each stage.

    The value of this approach is that it turns long-horizon capability into a verifiable engineering process. It does not depend on one-off code generation.

    3. System Breakdown: Minimum Viable Architecture

    3.1 Core Modules

    The platform can be split into six modules:

    • User and authentication module: Phone number and verification code login, token issuance and validation, user profile management.
    • Credit account module: Credit balance, deduction ledger, refund compensation, idempotency control.
    • Video task module: Task creation, state machine, parameter snapshots, result URLs, failure reasons.
    • Async queue module: Task enqueueing, consumer processing, retries, and dead-letter handling.
    • File and asset module: Uploads, temporary storage, access control for result files, expiration cleanup.
    • Operations and monitoring module: Task list, failure statistics, log search, alert rules.

    3.2 Task State Machine

    Video generation takes minutes, so it cannot block the request synchronously. The task states should include at least:

    1. CREATED -> QUEUED -> RUNNING -> SUCCEEDED
    2. |-> FAILED -> RETRYING -> RUNNING
    3. |-> CANCELED

    When a task is created, write it to the database and deduct credits first, then push it to the queue. Consumers only process QUEUED tasks. Before processing, a consumer changes the status to RUNNING with a conditional update, which prevents duplicate consumption. After a failure, the task moves to RETRYING or FAILED, depending on the retry count. On final failure, credits are compensated.

    3.3 Key Data Model Points

    The following example shows the table structures:

    1. -- Task table
    2. task(
    3. id, user_id, status, prompt_snapshot, source_url,
    4. result_url, error_code, retry_count, created_at, updated_at
    5. )
    6. -- Credit ledger table
    7. credit_ledger(
    8. id, user_id, task_id, amount, type, status, idempotency_key, created_at
    9. )
    10. -- User table
    11. user(id, phone, nickname, created_at)

    The two key design choices are the task parameter snapshot and the idempotency key in the credit ledger. The parameter snapshot ensures that later configuration changes do not affect historical tasks. The idempotency key ensures that the same task is never charged twice.

    4. Key Engineering Problems and Implementation Strategies

    4.1 Async Queue and Task Scheduling

    Video generation is slow, so the API layer only validates parameters, creates the task, deducts credits, enqueues the task, and returns the task ID immediately. Queue consumers run as separate deployments and pull tasks up to a concurrency limit. The consumer flow should include:

    1. Conditionally update the task status to RUNNING.
    2. Call the general video generation service or the internal generation flow.
    3. On success, write the result URL and update the status to SUCCEEDED.
    4. On failure, record the error code and retry with a backoff strategy.
    5. After the retry limit is exceeded, mark the task FAILED and trigger credit compensation.

    Pseudocode:

    1. def consume(task_id):
    2. task = claim_task(task_id, from_status="QUEUED", to_status="RUNNING")
    3. if not task:
    4. return # Already claimed by another consumer
    5. try:
    6. result = render_video(task.prompt_snapshot, task.source_url)
    7. mark_succeeded(task_id, result.url)
    8. except RetryableError as e:
    9. schedule_retry(task_id, e.code)
    10. except Exception as e:
    11. mark_failed_and_refund(task_id, e.code)

    Queue design should account for visibility timeouts, duplicate consumption, dead-letter queues, and backlog monitoring. For long tasks, consumer heartbeats and timeouts should match the actual processing time, so that tasks are not claimed twice.

    4.2 Authentication, Verification Codes, and API Protection

    User login uses a phone number and verification code flow: request a code, verify the code, and issue an access token. The token contains only necessary information, such as the user ID and expiration time. Permission checks happen on the server. The verification code endpoint needs rate limiting, a code validity period, and a limit on wrong attempts. The task creation endpoint needs login state validation, parameter validation, and per-user rate limiting.

    The API layer should use unified error codes so that internal exceptions are not exposed to the frontend. For example:

    1. {
    2. "code": "INSUFFICIENT_CREDIT",
    3. "message": "Insufficient credits",
    4. "requestId": "..."
    5. }

    4.3 Credit Deduction and Idempotent Consistency

    Credit systems often run into two problems: a task is created but the deduction fails, or a repeated callback causes a double charge. The recommended approach is a local transaction combined with an idempotent ledger. Creating the task and writing the deduction record happen in the same transaction. The ledger table uses task_id + type as a unique constra