Working rule: every consequential agent-facing action should return a receipt with a stable identifier, current status, links to inspect the result, and explicit next actions. “Accepted” and “completed” must not be confused.
Why receipts matter
Autonomous agents operate in loops: inspect, plan, act, verify, recover, and report. Most tools only optimize the action step. Receipts make the rest of the loop possible because they give the agent something concrete to verify and hand back to a human.
Without receipts, agents invent confidence from weak signals: HTTP 200s, UI text, spinners, or incomplete logs. With receipts, they can say exactly what changed and where to look if something needs review.
Minimum viable receipt
Stable handleA job ID, resource ID, commit SHA, invoice ID, message ID, deployment ID, or audit-event ID.
Status URLA URL or endpoint the agent can fetch later to distinguish queued, running, succeeded, failed, cancelled, and rolled back.
Result evidenceLinks to diffs, logs, previews, created records, changed resources, or other concrete outputs.
Next actionClear options such as poll, approve, rollback, retry with idempotency key, open review, or escalate to a human.
Example response shape
{
"operation": "deploy.run",
"request_id": "req_01HZ...",
"idempotency_key": "deploy-main-9f3a1c2",
"status": "accepted",
"job": {
"id": "dep_3481",
"status_url": "https://api.example.com/deployments/dep_3481",
"logs_url": "https://app.example.com/deployments/dep_3481/logs"
},
"target": {
"environment": "production",
"ref": "9f3a1c2",
"previous_release": "rel_9120"
},
"evidence": [
{"type": "plan", "url": "https://app.example.com/deployments/dep_3481/plan"},
{"type": "audit_event", "id": "evt_7782"}
],
"next_actions": ["poll_status", "cancel", "open_human_review"]
}Anti-patterns
- Boolean success:
{"success": true}tells the agent nothing about what changed or how to verify it. - Accepted as completed: returning 200 for queued work without a job ID causes agents to report outcomes prematurely.
- Human-only proof: screenshots, toast messages, and dashboards that cannot be fetched or linked break automated verification.
- No recovery handle: if a timeout happens and the agent cannot query by request ID or idempotency key, it cannot know whether retrying is safe.
Checklist for agent-facing actions
- Does every mutation return a durable ID or URL?
- Can an agent re-fetch status after a network failure or model/tool restart?
- Are intermediate states represented explicitly rather than hidden in logs?
- Is there a clear distinction between validation errors, permission errors, queued work, partial success, and completed work?
- Can the receipt be pasted into a ticket, commit message, audit log, or human handoff note?
- Does the response say which actions are safe to retry, cancel, rollback, or escalate?
Next: audit one high-value workflow and replace its vague success message with a receipt. This is often the smallest change that moves a tool from “automatable” to genuinely agent-first.