Aiden automation guide

This guide shows how to drive Aiden workflows and agents from CI, scripts, or backend jobs using the StackGen SDK. Every example uses explicit config (not a dozen environment variables) and is shown in Python and TypeScript.

Authoring vs running

• Create workflows in code with createAgent / createStage / createWorkflow and client.aiden.publishWorkflow — see Create a workflow.
• Run existing workflows with webhook or Ask journeys below.

Quick links

For SRE alerts and investigations see Usage.

Glossary

Plain-language definitions for terms you will see in responses and logs.

How it fits together

Two common paths:

flowchart LR
  subgraph webhookPath [Webhook path]
    A[Your alert or JSON] --> B[POST webhooks/trigger]
    B --> C[Workflow runs]
    C --> D[session_id]
    D --> E[session-report.md]
  end

  subgraph askPath [Ask path]
    F[Natural language message] --> G[POST guild/ask/start]
    G --> H[Poll executions/traceId]
    H --> I[session_id]
    I --> E
  end

Webhook path — best when you already have a webhook URL/token (e.g. wired from Datadog) and a structured alert body.

Ask path — best when you only have an API token and want to say “run workflow X for this incident” in plain language. Pin the workflow with entity_refs in CI.

Setup

Install

pip install stackgen-sdk==0.1.5

npm install stackgen-sdk@0.1.5

Connect

Use three mothership fields everywhere. Add webhook_token only for webhook journeys.

Python

from stackgen import StackgenClient, StackgenConfig

client = StackgenClient(
    StackgenConfig(
        base_url="https://app.stackgen.com",
        api_token="stackgen_…",           # stackgen_… from StackGen UI
        org_id="4f942a41-…",              # project UUID → orgId
        webhook_token="sg_aios_…",        # only for webhook trigger
        poll_interval_seconds=5,
        timeout_seconds=1800,             # 30 min default
        artifact_name="session-report.md",
        output_path="session-report.md",
    )
)

TypeScript

import { StackgenClient, StackgenConfig } from "stackgen-sdk";

const client = new StackgenClient(
  new StackgenConfig({
    baseUrl: "https://app.stackgen.com",
    apiToken: "stackgen_…",
    orgId: "4f942a41-…",
    webhookToken: "sg_aios_…",          // only for webhook trigger
    pollIntervalSeconds: 5,
    timeoutSeconds: 1800,
    artifactName: "session-report.md",
    outputPath: "session-report.md",
  }),
);

Optional convenience — three env vars only (STACKGEN_URL, STACKGEN_TOKEN, STACKGEN_PROJECT), then set webhook token in code:

from dataclasses import replace
from stackgen import StackgenClient, StackgenConfig

client = StackgenClient(
    replace(StackgenConfig.from_env(), webhook_token="sg_aios_…")
)

const base = StackgenConfig.fromEnv();
const client = new StackgenClient(
  new StackgenConfig({ ...base, webhookToken: "sg_aios_…" }),
);

Which token when?

Journey 1: Trigger a workflow via webhook

Use this when a webhook is already configured to start a workflow (for example incident-triage) and you have the sg_aios_… token.

What happens

1. SDK POSTs your alert text/JSON to /guild/api/v1/webhooks/trigger?orgId=…
2. Aiden starts the target workflow. Newer motherships may return session_id on the 202 body; otherwise the SDK polls GET /webhooks/{webhook_id}/runs/{invocation_id} until session_id is set (same as Guild’s reference script).
3. SDK waits until session-report.md (or your artifact name) appears
4. SDK downloads the file to output_path

For queue + scheduler architectures, use stateless methods (trigger_webhook, wait_for_webhook_session, …) — see Async webhook CI.

One call (recommended)

Python

from pathlib import Path

payload = Path("alert.json").read_text(encoding="utf-8")
# Or plain text: payload = "P1 | checkout-api error rate above SLO"

result = client.aiden.run_webhook_and_download_report(payload)

print("webhook_id", result.webhook_id)
print("session_id", result.session_id)
print("report", result.output_path)

TypeScript

import { readFileSync } from "node:fs";

const payload = readFileSync("alert.json", "utf8");

const result = await client.aiden.runWebhookAndDownloadReport(payload);

console.log("webhookId", result.webhookId);
console.log("sessionId", result.sessionId);
console.log("report", result.outputPath);

Equivalent curl

The SDK does the same as:

curl -X POST \
  "https://app.stackgen.com/guild/api/v1/webhooks/trigger?orgId=<project-uuid>" \
  -H "Authorization: Bearer sg_aios_…" \
  -H "Content-Type: text/plain" \
  -d @alert.txt

Then the SDK uses your API token to wait for the session artifact and download it.

Trigger only, wait for session yourself

If you only need session_id and will download the report later, see Webhook → session only on the code samples page. The step-by-step flow:

1. POST the webhook (JSON or plain text)
2. Read session_id from the 202 body when present, or poll run detail with wait_for_webhook_session
3. Optionally wait for and download the report

Journey 2: Start work or an agent with Ask Guild

Use Ask when you have only the API token and want to send a natural-language task. In CI, always pin the workflow or agent with entity_refs so routing is predictable.

What happens

1. SDK POSTs to /guild/api/v1/guild/ask/start?orgId=… with message (+ optional entity_refs)
2. Response includes trace_id and usually session_id
3. SDK polls /guild/api/v1/executions/{traceId} until status is terminal and trace_settled
4. SDK waits for the session artifact and downloads it

There is no SSE in the SDK — polling only, which works in CI and locked-down networks.

One call — workflow pinned (recommended for CI)

Python

result = client.aiden.run_ask_and_download_artifact(
    message="Run triage for checkout CPU alert",
    entity_refs=[{"name": "incident-triage", "type": "workflow"}],
    artifact_name="session-report.md",
    output_path="session-report.md",
)

print("trace_id", result.trace_id)
print("session_id", result.session_id)
print("plan", result.plan)
print("report", result.output_path)

TypeScript

const result = await client.aiden.runAskAndDownloadArtifact({
  message: "Run triage for checkout CPU alert",
  entityRefs: [{ name: "incident-triage", type: "workflow" }],
  artifactName: "session-report.md",
  outputPath: "session-report.md",
});

console.log("traceId", result.traceId);
console.log("sessionId", result.sessionId);
console.log("plan", result.plan);
console.log("report", result.outputPath);

Pin an agent instead of a workflow

entity_refs=[{"name": "my-sre-agent", "type": "agent"}]

entityRefs: [{ name: "my-sre-agent", type: "agent" }]

Valid type values: workflow, agent, integration, knowledge, or any.

Agent query without pinning (interactive only)

Omitting entity_refs lets Aiden choose among candidates. That is fine for exploratory chat; for pipelines, always pin a workflow or agent.

Waiting for a session

A session is created when Aiden starts handling your request. You need session_id to fetch artifacts and to continue a conversation.

When do you get session_id?

Ask — step by step (start → wait → optional download)

Advanced control when you want to branch between “started” and “finished”:

Python

start = client.aiden.start_ask(
    "Run triage for checkout-api error rate alert",
    entity_refs=[{"name": "incident-triage", "type": "workflow"}],
)

trace_id = start["trace_id"]
session_id = start.get("session_id")
print("started", trace_id, session_id)

# Block until execution is finished
trace = client.aiden.wait_for_execution(trace_id)
session_id = session_id or trace.get("session_id")
print("settled", trace["execution"]["status"], session_id)

TypeScript

const start = await client.aiden.startAsk(
  "Run triage for checkout-api error rate alert",
  {
    entityRefs: [{ name: "incident-triage", type: "workflow" }],
  },
);

const traceId = String(start.trace_id ?? "");
let sessionId = String(start.session_id ?? "");
console.log("started", traceId, sessionId);

const trace = await client.aiden.waitForExecution(traceId);
if (!sessionId) {
  sessionId = String(trace.session_id ?? "");
}
console.log("settled", (trace.execution as { status?: string }).status, sessionId);

If start_ask returns inputs_required, the workflow needs more fields — pass them via inputs={...} / inputs: { ... } or fix your message; the SDK raises StackgenError on the one-shot helper.

Webhook — step by step

See Webhook → session → artifact for full Python and TypeScript scripts. Minimal CLI shape:

export WEBHOOK_TOKEN='sg_aios_…'
python webhook-wait-session.py \
  --base-url https://app.stackgen.com \
  --api-token stackgen_… \
  --org-id 4f942a41-… \
  --json-body \
  --query-file alert.json
# prints session_id=… when ready

Download session artifacts

After you have session_id, the full journeys download session-report.md by default. Customize:

client.aiden.run_ask_and_download_artifact(
    "…",
    entity_refs=[{"name": "incident-triage", "type": "workflow"}],
    artifact_name="session-report.md",
    output_path="./out/report.md",
)

await client.aiden.runAskAndDownloadArtifact({
  message: "…",
  entityRefs: [{ name: "incident-triage", type: "workflow" }],
  artifactName: "session-report.md",
  outputPath: "./out/report.md",
});

Artifact name matching is case-insensitive.

When no artifact file is present, export the session write-up:

Python

export = client.aiden.export_session(session_id, parts="report")

TypeScript

await client.aiden.exportSession(sessionId, { parts: "report" });

Search or cancel long runs from a scheduler:

Python

client.aiden.list_sessions(q="corr-123")
client.aiden.terminate_session(session_id, reason="scheduler timeout")
client.aiden.list_executions(session_id=session_id)

TypeScript

await client.aiden.listSessions({ q: "corr-123" });
await client.aiden.terminateSession(sessionId, { reason: "scheduler timeout" });
await client.aiden.listExecutions({ session_id: sessionId });

For SRE Copilot investigate-from-alert (alert already in the SRE app), see SRE → investigate alert and Automation surface.

Runnable examples

Full scripts with syntax highlighting are on the Code samples page — copy directly from your browser; no separate download required.

Errors and timeouts

GET polling retries transient 429, 502, 503, 504. Trigger POST is not retried automatically (avoid duplicate runs).

FAQ

Common questions about installation, tokens, webhooks, inputs/outputs, retries, and operational limits are answered in the dedicated FAQ (Guild + SRE use cases).

Quick picks