Skip to content
General Augment Docs

Run Long-Running Agent Jobs

Use long-running agent jobs when your app needs work that may take more than one request/response turn: report generation, account research, workflow planning, channel follow-up, approval-gated actions, scheduled work, or background tasks started from your backend.

General Augment gives each job a durable run ID. Your app can create the run, stream progress, wait for completion, inspect the final result, approve or reject pending actions, and export a support bundle without building a custom orchestration layer.

Production Flow

Section titled “Production Flow”

Create

Start a background run with a stable app user ID and workflow metadata.

Stream

Attach live UI or operator progress to canonical run events.

Wait

Let backend workers block on the stable result envelope.

Debug

Export a support bundle with run, trace, usage, memory, and recovery evidence.

The same run ID works across the dashboard, CLI, SDKs, raw API, traces, usage records, webhooks, and support bundles.

For a canonical Project, the runtime key selects Candidate or Live when the key is issued. A background-turn request cannot override that target. General Augment persists the exact release ID, generation, fingerprint, target, and operation evidence before queue delivery. A worker retry fails with background_turn_release_changed if the target pointer moved; it never switches the queued run to a different release.

CLI Happy Path

Section titled “CLI Happy Path”
Terminal window
export GENAUG_PROJECT_ID="demo-agent"


RUN_ID="$(
  genaug runs background-turn "Prepare a renewal brief for Acme." \
    --project "$GENAUG_PROJECT_ID" \
    --user-id app-user-123 \
    --metadata-json '{"source":"renewals","job_id":"renewal-123"}' \
    --json | jq -r '.id'
)"


genaug runs stream "$RUN_ID" --project "$GENAUG_PROJECT_ID" --follow
genaug runs wait "$RUN_ID" --project "$GENAUG_PROJECT_ID" --timeout-seconds 600 --json
genaug runs result "$RUN_ID" --project "$GENAUG_PROJECT_ID" --json


genaug runs support-bundle "$RUN_ID" \
  --project "$GENAUG_PROJECT_ID" \
  --output artifacts/renewal-run-support-bundle.json

If the run pauses for approval, inspect the approval and resume with explicit input:

Terminal window
genaug runs approval "$RUN_ID" \
  --project "$GENAUG_PROJECT_ID" \
  --approval-id "$GENAUG_APPROVAL_ID" \
  --json


genaug runs resume "$RUN_ID" \
  --project "$GENAUG_PROJECT_ID" \
  --resume-token "$GENAUG_RESUME_TOKEN" \
  --input-json '{"approved":true}' \
  --metadata-json '{"source":"ops-cli"}' \
  --yes

TypeScript Backend Example

Section titled “TypeScript Backend Example”

Keep project keys on your server. Browser and mobile clients should call your backend, not General Augment directly.

import { GeneralAugmentClient } from "@general-augment/sdk";


const client = new GeneralAugmentClient({
  apiKey: process.env.GENAUG_API_KEY!,
  projectId: process.env.GENAUG_PROJECT_ID!,
});


const handle = await client.runs.create({
  input: "Prepare a renewal brief for Acme.",
  user: "app-user-123",
  metadata: { source: "renewals", job_id: "renewal-123" },
});


for await (const event of handle.stream({ follow: true })) {
  console.log(event.sequence, event.event_type, event.status);
}


const result = await handle.wait({ timeoutMs: 600_000 });
console.log(result.status, result.output_text);


const supportBundle = await handle.supportBundle({ limit: 50 });
console.log(supportBundle.operator_hints);

Python Backend Example

Section titled “Python Backend Example”
import os
from genaug import GeneralAugmentClient


client = GeneralAugmentClient(
    api_key=os.environ["GENAUG_API_KEY"],
    project_id=os.environ["GENAUG_PROJECT_ID"],
)


handle = client.runs.create(
    input="Prepare a renewal brief for Acme.",
    user="app-user-123",
    metadata={"source": "renewals", "job_id": "renewal-123"},
)


for event in handle.stream(follow=True):
    print(event["sequence"], event["event_type"], event["status"])


result = handle.wait(timeout_seconds=600)
print(result["status"], result.get("output_text"))


support_bundle = handle.support_bundle(limit=50)
print(support_bundle["operator_hints"])

Raw API Example

Section titled “Raw API Example”

Create the run:

Terminal window
curl https://api.generalaugment.com/v1/agent-runs/background-turns \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "X-Project-ID: $GENAUG_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Prepare a renewal brief for Acme.",
    "user_id": "app-user-123",
    "metadata": {"source":"renewals","job_id":"renewal-123"}
  }'

Stream events:

Terminal window
curl -N "https://api.generalaugment.com/v1/agent-runs/$RUN_ID/events/stream?after_sequence=-1&wait_seconds=30" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "X-Project-ID: $GENAUG_PROJECT_ID"

Wait briefly for the result envelope:

Terminal window
curl "https://api.generalaugment.com/v1/agent-runs/$RUN_ID/result?wait_seconds=30" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "X-Project-ID: $GENAUG_PROJECT_ID"

Choosing The Right Read

Section titled “Choosing The Right Read”
Need Use Why
Live progress in a UI or operator console stream / /events/stream Returns ordered run events and a resumable event cursor.
Backend worker needs completion wait / /result?wait_seconds= loop Waits on the stable result envelope.
App needs the latest user-safe output result / /result Returns current or final app-facing output without raw logs.
Debugging, launch review, or support support-bundle Packages run detail, trace IDs, related observability, usage, memory, and recovery commands.

Dashboard Operations

Section titled “Dashboard Operations”

The project dashboard run console shows recent runs with filters for status, surface, user, and session. Select a run to inspect status, result, step evidence, timeline events, approvals, usage, trace IDs, and support-bundle actions. Operators can cancel, retry, approve, reject, resume, copy commands, and download a support bundle from the same page.

Section titled “Related”