Agents

Six agents run against every project and feed one queue: the things they did that need a human. Some agents only propose (a drafted reply is never sent until you approve it); some act and let you undo (an auto-closed ticket can be reopened); some just report. Turn each one on and tune it under Project Settings → Agents; the queue itself is the Agents Activity page in the dashboard — and, since this is the part of Helmdesk an AI assistant most needs to see, the same queue is available over the API, the SDK, and the MCP server.

The six agents

Agent	Runs	What it does	Review
Auto-Responder	On every new ticket	Reads the ticket, searches your knowledge base, and drafts a grounded reply — or escalates when the KB has nothing.	Propose-only. The draft waits as pending; approving posts it and emails the customer.
KB Gap Analysis	Weekly	Finds questions your tickets keep asking that no article answers, and drafts up to three articles to fill the gaps.	Propose-only. Approve publishes the draft; revert deletes it.
Auto-Close	Daily	Closes tickets still in new, open or pending whose last message came from the customer and that have gone quiet past your threshold (10 days by default).	Auto-executes, then logs pending so you can revert — the ticket reopens to its previous status.
Log Watch	Every 15 minutes	Watches the live log plane for new error fingerprints or a known error recurring past a threshold, and alerts you.	Approve ("Got it") acknowledges the underlying log issue so it stops re-alerting.
Email Health	Weekly	Checks that a provider is configured and sending is not paused, looks for missing SPF/DMARC records, and flags a high bounce rate or a growing suppression list.	Informational — findings only; nothing to approve.
Weekly Digest	Weekly	Summarises the week’s support activity — volume, resolved, still open, recurring themes — in a short note.	Informational — history only.

Agents need AI features on your plan, count against the monthly agent-run allowance, and act on the live plane only. Log Watch and Auto-Close are deterministic (no model call); the rest use the same AI the dashboard does.

Review agent activity over the API

Every item in the queue is one thing an agent did, with a details object whose kind tells you exactly what approving or reverting will do. The three endpoints need the agents:review scope, which is part of the MCP / AI assistant key preset. It is a scope of its own because approving a drafted reply emails a customer — granting it should be a decision, not a side effect of tickets:write.

Which project?

Every agent-activity item belongs to one project. A key limited to one project implies it — send nothing extra. A key that reaches several projects (the kind you give a coding agent) names the project on each request with the Helmdesk-Project header (slug or id) or ?project=; without it the API answers 400 project.required with the projects it could have meant. Every object in a response carries projectId and projectSlug, so you can always tell what you are looking at.

curl

curl https://helmdesk.dev/api/v1/agent-activity \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"

SDK

// Pin the project once — or set HELMDESK_PROJECT and omit it.
const helmdesk = new HelmdeskClient({ apiKey, project: 'ledgerly' })
await helmdesk.agentActivity.list()

See Authentication for how keys and projects fit together.

What details.kind means for approve and revert:

Field	Type	Description
`auto-reply`	Auto-Responder	A drafted reply to a ticket (`details.reply`, with the KB `sources` it drew on). Approve posts it as a staff message and emails the customer; the ticket moves to `open`. Revert discards the draft — or, if `messageId` is set because the reply was already posted, removes it from the thread.
`drafted-article`	KB Gap Analysis	A draft knowledge-base article. Approve publishes it; revert deletes the draft.
`closed-ticket`	Auto-Close	A ticket the agent already closed. Approve keeps it closed; revert reopens it to `details.ticket.previousStatus`.
`log-issue`	Log Watch	An error alert. Approve acknowledges the underlying log issue; revert just dismisses the alert.
`email-health`	Email Health	Findings only. Either action marks the item reviewed.

GET/api/v1/agent-activityagents:review

The queue, newest first. Defaults to state=pending; state=all also returns reviewed items and informational rows (digests, email health). Filter to one agent with workflowType.

Request

curl "https://helmdesk.dev/api/v1/agent-activity?state=pending" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"

Response

{
  "items": [
    {
      "id": "c4f2a8e1-6b3d-4f0a-9e17-2d8b5c7a1f34",
      "projectId": "0f4e7a2c-9b1d-4c6e-8a3f-5d2b7e9c1a40",
      "projectSlug": "ledgerly",
      "workflowType": "auto_responder",
      "status": "success",
      "summary": "Drafted a reply to #42 — Login link expired",
      "details": {
        "kind": "auto-reply",
        "ticket": { "id": "9b1c7f2e-…", "number": 42, "subject": "Login link expired" },
        "reply": "Hi Dana — magic links expire after 15 minutes. Request a new one…",
        "sources": [{ "id": "6a1e3b7c-…", "title": "Signing in with a magic link", "slug": "magic-link-sign-in" }]
      },
      "reviewState": "pending",
      "executedAt": "2026-09-09T08:14:03.512Z"
    }
  ],
  "total": 1, "page": 1, "limit": 25
}

Query parameters:

Field	Type	Description
`state`	pending \| approved \| reverted \| all	Default pending. all includes informational rows whose reviewState is null.
`workflowType`	string	auto_close, auto_responder, kb_gap_analysis, weekly_digest, email_health, or log_watch.
`page`	integer	Default 1.
`limit`	integer	Default 25, max 100.

POST/api/v1/agent-activity/{logId}/approveagents:review

Keep what the agent did. For a drafted reply this posts it to the ticket as a staff message attributed to your API key and emails the customer; for a drafted article it publishes; for a Log Watch alert it acknowledges the issue. Returns the item with reviewState approved; 409 if it was already reviewed.

Request

curl -X POST "https://helmdesk.dev/api/v1/agent-activity/c4f2a8e1-6b3d-4f0a-9e17-2d8b5c7a1f34/approve" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"

Response

{
  "id": "c4f2a8e1-6b3d-4f0a-9e17-2d8b5c7a1f34",
  "workflowType": "auto_responder",
  "details": { "kind": "auto-reply", "…": "…" },
  "reviewState": "approved",
  "executedAt": "2026-09-09T08:14:03.512Z",
  "projectId": "0f4e7a2c-9b1d-4c6e-8a3f-5d2b7e9c1a40",
  "projectSlug": "ledgerly"
}

POST/api/v1/agent-activity/{logId}/revertagents:review

Undo what the agent did: reopen an auto-closed ticket to its previous status, delete a drafted article, or remove a posted auto-reply from the thread. Nothing is emailed. Returns the item with reviewState reverted; 409 if it was already reviewed.

Request

curl -X POST "https://helmdesk.dev/api/v1/agent-activity/e7a1c3d5-8f2b-4a6e-9c0d-3b5f7e1a9d28/revert" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Helmdesk-Project: ledgerly"

Response

{
  "id": "e7a1c3d5-8f2b-4a6e-9c0d-3b5f7e1a9d28",
  "workflowType": "auto_close",
  "details": {
    "kind": "closed-ticket",
    "ticket": { "id": "2c8e4a6f-…", "number": 37, "subject": "Invoice PDF is blank", "previousStatus": "pending" }
  },
  "reviewState": "reverted",
  "executedAt": "2026-09-08T07:00:12.004Z",
  "projectId": "0f4e7a2c-9b1d-4c6e-8a3f-5d2b7e9c1a40",
  "projectSlug": "ledgerly"
}

Sandbox

Agents act on the live plane, so the queue is not environment-scoped: a sandbox key (or a live key sent with Helmdesk-Environment: sandbox) sees the same list. Approving a drafted reply on a sandbox ticket posts it to the thread but sends no email — the same rule as every other sandbox notification.

With the SDK

client.agentActivity mirrors the three endpoints. Read the item before you act on it — for an auto-reply, that means showing the draft to whoever is deciding.

import { HelmdeskClient } from '@helmdesk/sdk'

const helmdesk = new HelmdeskClient({ apiKey: process.env.HELMDESK_API_KEY!, project: 'ledgerly' })

// Anything waiting for me?
const { items } = await helmdesk.agentActivity.list()

for (const item of items) {
  if (item.details?.kind === 'auto-reply') {
    console.log(`#${item.details.ticket.number}: ${item.details.reply}`)
  }
}

// Approve a drafted reply — this posts it and emails the customer.
await helmdesk.agentActivity.approve(items[0].id)

// Reopen a ticket Auto-Close got wrong.
const closed = await helmdesk.agentActivity.list({ workflowType: 'auto_close' })
await helmdesk.agentActivity.revert(closed.items[0].id)

// Everything, including reviewed and informational rows.
const history = await helmdesk.agentActivity.list({ state: 'all', limit: 100 })

From an AI assistant (MCP)

The MCP server exposes the queue as list_agent_activity, approve_agent_item and revert_agent_item. The list tool is read-only, so a client can run it freely; approve is annotated as reaching a customer, so a well-behaved client asks before it runs. "Anything waiting for me in Ledgerly?" is the whole prompt. See MCP Server.