A production agent API should admit and validate work, create a durable run, and return quickly; workers execute leased jobs, persist events and checkpoints, and publish outcomes. Clients observe through event streams or polling, submit approvals through authenticated endpoints, and fetch final artifacts separately. Long-running work must survive disconnected clients and failed processes.
You will design the service boundaries and HTTP contracts for queued, resumable SupportOps runs.
Return 202 Accepted for queued work and a stable run ID. Require idempotency on create. Authorize every run/artifact/approval by tenant and role.
Acquire a lease, load checkpoint and budget, start/continue the adapter, persist events before acknowledging critical transitions, heartbeat, honor cancellation, reconcile tool attempts, save checkpoints, and atomically publish terminal outcome. A worker crash must release only through lease expiry, not create a second active owner immediately.
Server-Sent Events fit one-way progress; WebSockets fit bidirectional interactive input; polling is simplest and robust. Normalize events, use sequence IDs, support reconnect, and never make a browser connection the owner of execution.
Failure injection: Close the client, kill the API, and restart a worker independently. The run should remain observable and reach one terminal outcome.
Run chaos tests for duplicate create, queue redelivery, lease loss, API restart, stream reconnect, worker death, delayed approval, cancellation, and event-store outage.
Write an OpenAPI state model for these endpoints and a sequence diagram for create, approval pause, process restart, resume, and completion.