Agent work protocol reference

For concepts, start with From delivery to agent outcome. For setup and a verified local example, follow Connect an agent runtime. This page is the protocol reference; its existing URL remains stable.

Agent work connects participating runtime endpoints to progress tracking, human input, conversation sessions, private email attachments, and in-app outcome notices. Enable config.agent_work on your runtime endpoint and provision a scoped credential before receiving handoffs. Existing receivers keep their original event format. Self-hosted deployments also need the database migrations, private object storage, queue, and scheduler described below.

An HTTP delivery acknowledgement records message delivery. A runtime callback records agent progress or outcome. A human decision receipt records that the runtime accepted an answer or approval. These three statuses are independent; an external runtime's completion report does not independently verify its side effects.

Endpoint and credentials

Create a webhook or agent-runtime endpoint, provision an endpoint-bound runtime credential, and enable config.agent_work. Operator CLI credentials manage configuration; a separate runtime token authorizes reports and downloads. Tokens are returned once, hashed at rest, and expire within 90 days. Rotate with overlap, then revoke the old token.

agentowl --json runtime-credentials create <endpoint> --days 30
agentowl runtime-credentials list <endpoint>
agentowl runtime-credentials revoke <credential>

Install the token as a receiver secret. The envelope carries its public credential ID, never its token. Configure an HTTPS decision_url and stored bearer secret for automatic decision delivery. Keep the original destination available while pending work drains.

Runtime handoff and callbacks

An opted-in delivery adds this block:

{
  "work": {
    "version": "agent-work.v1",
    "work_id": "work_example",
    "conversation_id": "conv_example",
    "generation": 1,
    "callback_url": "https://api.agentowl.dev/runtime/v1/work/work_example/callbacks",
    "credential_id": "runtime_credential_example"
  }
}

Follow-ups include runtime_session_id after the runtime establishes it. Work identity is persisted before dispatch and reused on transport retry. An intentional replay creates new work with retained conversation context.

POST callbacks to the supplied URL using Authorization: Bearer <runtime-token>. A minimal report is:

{
  "version": "agent-work.v1",
  "callback_id": "work_example:1",
  "work_id": "work_example",
  "sequence": 1,
  "status": "accepted",
  "occurred_at": "2026-10-06T12:00:00.000Z",
  "runtime_session_id": "receiver_session_example"
}

Reported statuses are accepted, running, needs_input, completed, failed, and cancelled. Completion may include result: { "summary": "Report ready", "url": "https://runtime.example/results/report" }. Result links require HTTPS without embedded URL credentials; AgentOwl does not fetch them.

Reuse the callback ID, sequence, timestamp, and body on retry. Exact duplicates return the original receipt. A lower sequence is recorded as stale without changing state; gaps are allowed. Conflicting identities/sequences and terminal reopening fail with 409. Bodies are capped at 64 KiB, endpoint volume at 60 requests/minute across credential rotation, and recorded callbacks at 10,000/work. Retry 429 with Retry-After and retryable 5xx using backoff. Correct other failures before retrying.

Questions and approvals

A needs_input callback supplies requests. Each request has stable ID, positive revision, kind, prompt, allowed_decisions, and UTC expiry. Questions support answer. Approval requests support approve/reject and include action: { "description": "The concrete proposed action", "digest": "<64 lowercase SHA-256 hex characters>" }. Edit is unsupported in v1. Changed content requires a new revision; older approvals cannot authorize the replacement action.

Operators respond in Needs attention or through agentowl attention decide <attention> decision.json to preview the current request, then add --submit after reviewing the action. An approval file includes stable decision_id, request_revision, decision, and expected_action_digest. An answer includes answer instead of the action digest. One decision wins atomically. The receiver must deduplicate decision IDs and enforce the declared expiry before acting.

A push receiver returns { "accepted": true, "decision_id": "…" }. Scoped decision recovery routes are GET /runtime/v1/work/:work/decisions and POST /runtime/v1/work/:work/decisions/:decision/receipt. Receipt confirms acceptance, while a later callback reports execution. Receipt recovery never reopens completed work.

Conversations and attachments

Email references match only within a receiving binding, tenant, and compatible sender; missing/ambiguous references start a new conversation. SMS follows a sliding 24-hour inactivity window. Voice groups provider call-session lifecycle events. Routing remains authoritative. Operators can explicitly link an event before runtime handoff or reset an idle session using audited configuration commands.

Managed retained bytes cover SMTP and Cloudflare email attachments. Use the runtime token's attachments:read scope:

GET /runtime/v1/work/:work/attachments
GET /runtime/v1/work/:work/attachments/:attachment

Manifests provide names, sizes, hashes, Content-ID, expiry, and availability. Downloads are private streamed responses with safe attachment headers. New hosted email attachments after the October 16, 2026 rollout have 30-day retention and share the complete message limit of 1 MB including MIME encoding. Existing files keep their recorded expiry. Self-hosted storage defaults remain seven days unless configured otherwise, with parser ceilings of 20 parts/message, 10 MiB/file, and 25 MiB decoded/message; the inbound message limit can be lower. Expired, blocked, and missing content is explicit; expired downloads fail even if physical deletion is delayed. Replay does not substitute missing bytes. Existing provider MMS/voice media links are outside managed archival.

Operator views and notifications

Agent work, Needs attention, Conversations, and Notifications have tenant-scoped API and CLI equivalents. Inbox messages link to work and retained files. Acknowledgement assigns an attention item without executing or resolving its requested action. Answers/approvals resolve through runtime receipt or a later outcome. Non-request incidents can be resolved after review.

Notifications cover results, failures, and input requests with authorized deep links, read state, and recipient preferences. They are in-app only. Visible pages refresh every 30 seconds; browser-closed email/push delivery is not provided. Duplicate callbacks and transport retries create one logical notice per cause/recipient. Routine running progress is quiet.

agentowl --json work list --tenant <tenant>
agentowl work inspect <work>
agentowl attention list --tenant <tenant> --status open
agentowl conversations events <conversation>
agentowl attachments download <event> <attachment> <new-file>
agentowl notifications list --tenant <tenant>
agentowl work-doctor <tenant>

Maintenance detects overdue work without inferring a terminal outcome, recovers queue/outbox intent, expires requests, deletes retained bytes, and releases quotas. Operators can inspect/redrive failed outgoing jobs with work-outbox and ingress-publications commands. Self-hosting operators should follow the repository's agent-work operating guide and rollout gates before enabling traffic.