AI agents & escalation

Clad's AI-agent workflow — investigations, suggested-reply drafts, and engineering-tracker filing — is available in the API, so an external agent can run the same playbook a teammate runs in the Clad app or the in-helpdesk panel.

Investigations

startInvestigation kicks off an asynchronous root-cause dig for an issue: kind: code works through the connected GitHub repo, kind: billing works through Stripe. Runs take a few minutes — poll investigation(id) (or investigations(issueId)) until status is complete or failed, then read output (markdown findings), summary, and answerFound.

mutation Investigate($input: StartInvestigationInput!) {
  startInvestigation(input: $input) {
    investigation { id status }
    error { code message }
  }
}

Per-organization in-flight and daily caps protect spend (RATE_LIMITED when hit). Requires investigations:run; reads require investigations:read.

Drafts

Clad auto-drafts a suggested reply when a customer message arrives and the knowledge base has a confident answer. latestDraft(issueId) returns the newest attempt in any status — generating, pending (awaiting review), discarded_* (the gate declined), approved, rejected — including the draft body and its sources: the knowledge-base articles and resolved tickets the answer was grounded in.

• generateDraft produces a draft on demand through the same gated pipeline (optionally steered with instructions). A declined gate returns withheld: true with a reason — that's a valid outcome, not an error. It returns CONFLICT if a pending draft already exists; deny that one first.
• generateDraftFromInvestigation turns a completed investigation's findings into a pending draft.
• approveDraft sends the draft to the customer. This requires a human-authorized credential (OAuth) — the send is attributed to the approving person, so headless machine keys are refused with FORBIDDEN. v1 delivers approvals on helpdesk-mirrored issues (Pylon/Zendesk), with the same Observe/Assist mode gate and idempotent delivery as replies; other channels approve in the Clad app.
• denyDraft rejects a pending draft with a reason, which feeds regeneration and quality analytics.

Draft reads require drafts:read; generate/approve/deny require drafts:write.

Tracker escalation

When a ticket needs engineering, fileTrackerTicket files a Linear ticket from the issue and links it: the Clad issue moves to On hold and the tracker ticket gets a back-link comment with the customer context. linkedTickets returns the linked tickets' live state and comment threads (check it before filing to avoid duplicates), and commentOnLinkedTicket posts follow-up context for the engineers. These use the issues:read / issues:write scopes.

Helpdesk connection

helpdeskConnections reports the connected helpdesks (provider, status, operating mode, sync scope) with settings:read — check it before attempting replies or approvals: in Observe mode every write to the helpdesk returns FORBIDDEN until an admin switches the connection to Assist.