Part 10 of 12 · 1 min read
Quick notes
- An agent run can take minutes, so a single blocking HTTP request is the wrong interface. Use a job API:
POST /runsreturns 202 with a job id, the client polls or receives a webhook, andDELETE /runs/{id}cancels. - Sync fails twice over: proxies time out before the run ends, and client retries make the server run the same job again.
- Idempotency keys stop duplicate jobs. Same owner, key and body returns the original job; same key with a different body returns 409.
- The job is a state machine (
queued -> running -> succeeded | failed | cancelled), terminal states never change, and the status endpoint returnsRetry-Afterwhile running and 404 for another owner's job. - Webhooks are far cheaper than polling but are at-least-once, so sign them, check the timestamp, and dedupe by a stable event id. Users must be able to cancel.