# Run Long-Running Agent Jobs

Source: https://docs.generalaugment.com/guides/long-running-agent-jobs/
Description: Create, stream, wait for, approve, inspect, and debug durable General Augment agent runs from your backend.

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

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

```bash
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:

```bash
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

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

```ts
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

```py
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

Create the run:

```bash
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:

```bash
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:

```bash
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

| 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

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.

## Related

- [CLI commands](/cli/commands/) for every `genaug runs` command.
- [SDK reference](/sdk/reference/) for TypeScript and Python helpers.
- [API reference](/api/) for `/v1/agent-runs` endpoints.
- [Migrate app automation](/guides/migrate-app-automation/) for moving existing jobs
into governed General Augment workflows.