Queued Is Not Finished: Handling Agent Tools Job States Without Inventing Completion
Asynchronous processing makes one mistake easy: treating a submit response or a long wait as proof that work finished. With Skavio Agent Tools, the safer pattern is to separate job identity, observed state, terminal outcome and result retrieval. This guide outlines that discipline without inventing status names or transitions the documentation does not publish.
A request is not a result
Skavio Agent Tools is a live, company-scoped authenticated API for document, invoice, audio and data processing. It provides self-service keys, asynchronous jobs and a shared prepaid credit wallet. It is distinct from the staging Invoice, Reporting or Research AI agents, so do not conflate their roles. The exact status strings, transitions, error codes and result-retrieval behavior must come from the current Agent Tools documentation, not from assumptions built around a spinner or a timeout.
- A submit response means the server received a request; it does not prove the job finished.
- Waiting states such as queued or processing are not outcomes.
- A prepaid credit balance is not a processing result.
- Completion requires the documented terminal-success condition and retrieval of the artifact through the authenticated path the documentation defines.
Persist the job record before the browser forgets
An Agent Tools integration should keep a durable job record outside the browser tab. Store the server-issued job identifier, the company scope, the submission time, the last observed state, the last time that state was checked, and whether an artifact has actually been retrieved. In the interface, show the last observed state with a timestamp rather than a bare “done” badge or an open-ended progress bar. Keep API keys server-side and scoped to the company. Treat job identifiers and API keys as different access concerns, and follow the authentication rules in the current documentation.
- Save the server-issued job identifier before redirecting, closing the tab or sending an acknowledgement.
- Display “last checked” information so an operator can distinguish fresh status from stale status.
- Keep job state, credit state and accounting records separate.
- If the documentation does not publish a particular status label, show a neutral label or “status unavailable” instead of inventing one.
Gate downstream actions on documented success
Downstream actions should wait for the documented terminal-success condition and an authenticated result retrieval. Do not send a completion email, write a final spreadsheet, or mark a document approved merely because time has passed, a status endpoint returned an HTTP success code, or a job looked fast in a test. If the current documentation defines completion notifications, treat an unverified notification only as a prompt to re-check the documented status and retrieval path; it is not itself a result. Human review is a separate control; a processed artifact is not automatically an approved accounting write.
- Elapsed time is not a completion event.
- If completion notifications are part of the documented contract, an unverified notification is not an outcome; confirm through the documented path before trusting it.
- Keep “processing finished” distinct from “approved for business use.”
- Retrieve the artifact only through the authenticated retrieval path specified by the current documentation.
When status is missing or ambiguous, say so
A status can be unavailable, stale, contradictory or outside the error cases your client maps. In those situations, the honest interface is “still processing” or “status unavailable,” followed by an escalation path. Do not silently retry a job, fabricate extracted values, or show a completed file to fill the gap. Give support or operations the job identifier, last observed state, timestamps and the request context so the case can be investigated against the live service.
- Show plain language such as “still processing” or “status unavailable.”
- Escalate with the job identifier, last state, timestamp history and the original request reference.
- Do not resubmit automatically unless the current documentation supports a safe retry pattern.
- Never invent a completed artifact, a success message or extracted content when status is uncertain.