> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Serverless protocol reference
description: Implement and verify the workerless.v1 manifest, signed invoke request, checkpoint, and result schemas.
last_verified: 2026-07-20
---

`workerless.v1` is the HTTP contract between the AGNT5 runtime and a serverless endpoint. Use an official SDK adapter when possible; use this reference when implementing or auditing another language adapter.


**Manifest**: `GET /.well-known/agnt5`
**Invoke**: `POST /agnt5/invoke`
**Signature message**: `<timestamp>.<attempt-id>.<exact-request-body>`
**Signature algorithm**: HMAC-SHA256


## Return the manifest

`GET /.well-known/agnt5` returns JSON:

```json
{
  "protocol_version": "workerless.v1",
  "service_name": "orders-api",
  "service_version": "git-4f91c2a",
  "components": [
    {
      "name": "process-order",
      "type": "workflow",
      "component_type": "workflow"
    }
  ]
}
```

Component types are `workflow`, `function`, `tool`, or `agent`. SDKs may add schemas, metadata, triggers, and flow-control declarations.

## Verify the invoke signature

AGNT5 sends these headers with `POST /agnt5/invoke`:

| Header | Value |
| --- | --- |
| `X-AGNT5-Signature-Version` | `workerless-hmac-sha256.v1` |
| `X-AGNT5-Timestamp` | Unix time in milliseconds |
| `X-AGNT5-Attempt-ID` | Unique dispatch attempt identifier |
| `X-AGNT5-Signature` | `sha256=<lowercase-hex-digest>` |

Compute HMAC-SHA256 over the exact bytes of:

```text
<timestamp>.<attempt-id>.<request-body>
```

Use constant-time comparison and reject timestamps outside a five-minute window. Verify the raw body before parsing JSON.

## Parse the invoke request

```json
{
  "protocol_version": "workerless.v1",
  "run_id": "run_123",
  "project_id": "project_123",
  "deployment_id": "deployment_123",
  "component_type": "workflow",
  "component_name": "process-order",
  "attempt": 0,
  "is_streaming": false,
  "input": {"order_id": "order_123"},
  "metadata": {},
  "checkpoint": {"steps": {}},
  "budget": {
    "deadline_ms": 1784500000000,
    "request_timeout_ms": 10000,
    "yield_before_timeout_ms": 1000
  }
}
```

The runtime may replace `input` with a signed `input_ref` and may include `output_upload` for large output. An adapter that does not implement those fields must fail with a stable unsupported-feature error instead of ignoring them.

## Return a result

Return HTTP `200` for component-level completion, failure, or suspension. Transport and authentication failures use their corresponding non-2xx status.

### Complete

```json
{"status":"completed","output":{"accepted":true},"checkpoint":{"steps":{}}}
```

### Fail

```json
{
  "status":"failed",
  "error":{"code":"ORDER_REJECTED","message":"order cannot be processed","retryable":false}
}
```

### Suspend

```json
{
  "status":"suspended",
  "reason":"budget",
  "checkpoint":{"steps":{"step:load-order":{"id":"order_123"}}}
}
```

Timer suspension also returns `ready_at_ms` and may return `timer_key`. Every result may include an `events` array for AGNT5 to append to the run journal.

## Preserve durability

- Keep checkpoint keys stable across compatible deployments.
- Treat the body as untrusted until signature verification succeeds.
- Return suspension before the provider terminates the request.
- Do not send durable client output directly from the provider; append events through the AGNT5 response.
- Keep retries pinned to the deployment and manifest version selected by AGNT5.

## Next steps

- [Serverless SDK reference](/docs/run/serverless-sdk-reference.md): use supported language adapters instead of hand-writing the protocol.
- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): validate signing, manifests, and rollout compatibility.
- [Serverless CLI reference](/cli/serverless.md): inspect endpoint validation and synchronization commands.