Skip to main content
Some work takes longer than a conversation will wait: reading a hundred filings, running a model for an hour. Your specialist may answer later. It says so, finishes in its own time, and delivers the result to Kovrex, which keeps it for the client’s assistants to collect. Kovrex never calls an assistant, and an assistant never gives Kovrex an address: an assistant asks Kovrex how the task stands, and Kovrex answers from its own record. In short:
  1. The assistant asks as usual. Nothing about its request is different.
  2. Your specialist answers with the task in the working state, marked as deferred, and ends the stream or returns.
  3. Kovrex opens a job for the task with a deadline, and tells the assistant at once.
  4. Your specialist posts progress notes and then the result to the return address Kovrex put in the request, with the token it put there.
  5. An assistant of the client asks Kovrex, with GetTask, and collects the text and the file addresses.
The limits, stated once. A job lasts at most 24 hours from the moment Kovrex accepted it, and your specialist may say it needs less. Past the deadline Kovrex ends the job as failed and tells your specialist to cancel. The assistant is told your estimate and the exact time the job will end, when the job is accepted. A stream that merely ends while the task is still working, without the mark below, is not a deferral: it is still treated as your specialist having stopped part-way.

Deferring

Answer with a task in TASK_STATE_WORKING that carries the Kovrex extension https://kovrex.ai/ext/deferred/v1 in its metadata. Not streamed, in the task:
Streamed, in the metadata of a status update, after which you close the stream:
The mark is read from the metadata of a task or a statusUpdate in the working state, or from the metadata of its status.message. In any other state it means nothing. A task has one open job at a time: a second deferral of a task whose job is still open keeps the first job’s deadline. What the assistant is told, at once and in the answer it was already waiting for, is written by Kovrex: that the job is deferred, your estimate, the time it will be ended automatically, how and how often to ask again, and what to tell the person. Your own message text, if any, is added after Kovrex’s words, as what your specialist added. Several jobs at once for one client are allowed.

The return address and the token

Every SendMessage and SendStreamingMessage carries, in params.configuration, an A2A push notification configuration made for that request:
  • Keep both with your task, if you defer it. They exist only for that task. If your specialist never defers, it can ignore them.
  • The url is always on Kovrex’s own address. Post to that address and nowhere else, and never accept an address from anyone else for this. Its ID is random and is not Kovrex’s ID for the task.
  • The token is random, for this one task, and never part of the address. Kovrex keeps only a hash of it. Do not log it. A request without it is refused and nothing is recorded.
  • A job exists only once Kovrex has received your deferral. If you post within a second of deferring, an answer of 401 may only mean Kovrex has not caught up: wait a moment and post again.

Delivering

POST one event to the url, with the token in A2A-Notification-Token, as A2A libraries do:
The body is one event in the shapes of Conversations: a statusUpdate, an artifactUpdate, a whole task, or a message, as the result of a stream event would hold it. The same inside a JSON-RPC reply ({"jsonrpc":"2.0","id":…,"result":{…}}) is accepted too. Your own task ID goes in it. Instead of the token your specialist may sign the call with its own key, as a Bearer token made as in Signing a call; the token alone is enough.
  • Progress notes are status updates in the working state with a message. Kovrex keeps the latest one for the assistant and for the person, and writes every one into the conversation’s record. They are optional.
  • The final event has a final state: TASK_STATE_COMPLETED (a whole task with its artifacts is the simplest way, or a last status update after artifact updates), TASK_STATE_FAILED, TASK_STATE_REJECTED or TASK_STATE_CANCELED. Kovrex closes the job on it.
  • Files are sent as in [Files](/specialists/files), in a part with raw, filename and mediaType, in an artifact or a message. Kovrex stores them and gives assistants an address in place of each, as it does for a live answer. The same rules and limits apply as to any answer: one event up to 70 MB, the types and sizes in Files.
  • Everything is encrypted with the client’s key when it is written, like the rest of the record.
  • A repeat of the same event changes nothing. Kovrex recognises an identical body, so a delivery that was retried because your specialist did not see the answer is safe, and a repeat of the final event after the job closed is answered with 200 and "duplicate": true.
  • A job takes at most 1000 events and 60 deliveries a minute.
Retry a delivery that fails with a 5xx or a network error (a refused or dropped connection, a timeout), and one answered 429 or 503, with a pause that grows, for as long as the job is open: a delivery posted once and abandoned is lost, and the job then ends as failed at its deadline. Do not retry a 400, 410 or 422. Access does not decide a delivery. Kovrex checks that the person had access when it accepted the message that opened the job, so a delivery for an open job is recorded, with its files, even if your specialist began to charge, or the person’s pass ended, after the job began. Only a new message needs access. A file that arrives this way stays with the person like any other: it is on the client’s own clock, described in [Files](/specialists/files#how-long-a-clients-files-last). What still ends the job is the relationship ending, your specialist no longer being open, the deadline, or the job’s own end.

Cancelling, and the deadline

When the assistant cancels the task, or the deadline passes, Kovrex sends your specialist CancelTask with your own task ID, as in Conversations (it carries no client details). Stop work and answer with the task in the canceled state. Kovrex has already ended the job on its side, so a result delivered afterwards is refused with 410, and a specialist that cannot be told changes nothing. The same happens when the person ends their relationship with your specialist, which they can do at any time: every open job for that client is cancelled at once, your specialist is sent CancelTask once for each, and anything it delivers afterwards is refused with 410 and not recorded. Whether the relationship is still active is checked again at every delivery, in the step that writes it. Likewise a specialist that is no longer open on Kovrex has its open jobs cancelled and its deliveries refused. When the deadline passes, the assistant is told the job ended as failed because it was not finished in time.

More messages while a job runs

The conversation goes on. The assistant may send more messages, with the same contextId (and, if it wishes, the taskId), while a job is open. Kovrex forwards them like any other, with the client metadata of Conversations and a fresh return address and token for that request. What your specialist does with them is its own choice: answer, ask a question, or defer another task.

Saying no to a job

A specialist that does not want a task, including when it already has work for that client, answers with the task in the TASK_STATE_REJECTED state and the reason in status.message, as a plain answer or as a status update in a stream:
Kovrex records the reason, passes it on to the assistant, and opens no job. (A JSON-RPC error with -32004, as in “Saying no”, is for a request your specialist cannot understand or does not do at all.)

Try it

Echo, the stand-in specialist (stand-in-specialist.py), shows all of this. Send it long: it defers with an estimate, posts a progress note, and delivers a result with a file after LONG_DELAY seconds (5 by default). Send it never: it defers and delivers nothing, so the job ends at its deadline.