← All code samples

Ask → wait for execution

Start Ask with a pinned workflow, then poll until execution.status settles. No artifact download — use this when you only need trace/session ids or execution outcome.

Ask journeys use the API token only (no webhook token). Pin a workflow with entity_refs in CI so routing is deterministic.

Step What the SDK does
1. Start POST /guild/api/v1/guild/ask/start with message and optional entity_refs
2. Poll GET /guild/api/v1/executions/{traceId} until status is terminal and trace_settled

Minimal — start and poll

from stackgen import StackgenClient, StackgenConfig

client = StackgenClient(
    StackgenConfig(
        base_url="https://app.stackgen.com",
        api_token="stackgen_…",
        workspace_id="<workspace-uuid>",
    )
)

start = client.aiden.start_ask(
    "Run triage for checkout CPU alert",
    entity_refs=[{"name": "incident-triage", "type": "workflow"}],
)
trace = client.aiden.wait_for_execution(start["trace_id"])
print(trace["session_id"], trace["execution"]["status"])

Runnable CLI

#!/usr/bin/env python3
"""Ask start → wait for execution (no artifact download).

Documented at https://appcd-dev.github.io/stackgen-sdk/code-samples/ask-execution/

Usage:

  python ask-wait-session.py \\
    --base-url https://app.stackgen.com \\
    --api-token stackgen_… \\
    --workspace-id <workspace-uuid> \\
    --message 'Run triage for checkout CPU alert' \\
    --workflow incident-triage
"""

from __future__ import annotations

import argparse
import json
import os
import sys

from stackgen import StackgenClient, StackgenConfig
from stackgen.errors import StackgenError


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--base-url", default=os.environ.get("STACKGEN_URL", ""))
    parser.add_argument("--api-token", default=os.environ.get("STACKGEN_TOKEN", ""))
    parser.add_argument(
        "--workspace-id",
        "--org-id",
        default=os.environ.get("STACKGEN_WORKSPACE_ID") or os.environ.get("STACKGEN_PROJECT") or os.environ.get("STACKGEN_PROJECT_ID", ""),
    )
    parser.add_argument("--message", required=True)
    parser.add_argument(
        "--workflow",
        required=True,
        help="Workflow name for entity_refs pin",
    )
    parser.add_argument("--timeout-seconds", type=int, default=1800)
    parser.add_argument("--poll-interval-seconds", type=int, default=5)
    args = parser.parse_args()
    if not args.base_url or not args.api_token or not args.workspace_id:
        parser.error("set --base-url/--api-token/--workspace-id or STACKGEN_URL/STACKGEN_TOKEN/STACKGEN_WORKSPACE_ID")

    client = StackgenClient(
        StackgenConfig(
            base_url=args.base_url,
            api_token=args.api_token,
            workspace_id=args.workspace_id,
            timeout_seconds=args.timeout_seconds,
            poll_interval_seconds=args.poll_interval_seconds,
        )
    )

    start = client.aiden.start_ask(
        args.message,
        entity_refs=[{"name": args.workflow, "type": "workflow"}],
    )
    trace_id = start.get("trace_id")
    session_id = start.get("session_id")
    print("start:", json.dumps(start, indent=2))

    trace = client.aiden.wait_for_execution(str(trace_id))
    execution = trace.get("execution") or {}
    session_id = session_id or trace.get("session_id")
    print(
        f"settled status={execution.get('status')} "
        f"trace_settled={execution.get('trace_settled')} "
        f"session_id={session_id}",
        file=sys.stderr,
    )
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except StackgenError as exc:
        print(f"error: {exc}", file=sys.stderr)
        raise SystemExit(1)

Related: Ask → artifact — same start flow plus artifact download.