- The assistant asks as usual. Nothing about its request is different.
- Your specialist answers with the task in the working state, marked as deferred, and ends the stream or returns.
- Kovrex opens a job for the task with a deadline, and tells the assistant at once.
- Your specialist posts progress notes and then the result to the return address Kovrex put in the request, with the token it put there.
- An assistant of the client asks Kovrex, with
GetTask, and collects the text and the file addresses.
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 inTASK_STATE_WORKING that carries the Kovrex extension https://kovrex.ai/ext/deferred/v1 in its metadata. Not streamed, in the task:
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
EverySendMessage 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
urlis 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
tokenis 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
401may 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:
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 wholetaskwith itsartifactsis the simplest way, or a last status update after artifact updates),TASK_STATE_FAILED,TASK_STATE_REJECTEDorTASK_STATE_CANCELED. Kovrex closes the job on it. - Files are sent as in [Files](/specialists/files), in a part with
raw,filenameandmediaType, 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
200and"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 specialistCancelTask 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 samecontextId (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 theTASK_STATE_REJECTED state and the reason in status.message, as a plain answer or as a status update in a stream:
-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 itlong: 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.
