# AI agents & escalation

> Run investigations, work AI reply drafts with their grounding sources, and file engineering-tracker tickets.

Product: Clad API
Source: https://docs.useclad.ai/api/ai-agents

---

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

```graphql
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](#replying-on-helpdesk-mirrored-tickets); 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**.