Service Conversations

Not yet released

A background task can hand a batch of files to an AI conversation, which reads them and acts with the tools the Extension declared. The conversation shows in Cowork like any other, so the person can follow it.

dozin.agent

Field	Type	Required	Description
brief	string	Yes	A .md file in the package: the conversation's instructions
model	{ id, effort? }	No	Model to use; effort is max, xhigh, high, medium or low
tools	string[]	No	Business tools the conversation may use, up to 8. Cowork has none to offer yet, so leave it out
secret	string	No	An env from dozin.secrets those tools use

ctx.agent.handoff(input) Not yet released

Name	Type	Required	Description
input.title	string	Yes	Conversation title; longer than 120 characters is cut
input.files	string[]	Yes	1–50 files inside dataDir, relative or absolute paths
input.summary	string	No	What the batch is; longer than 4000 characters is cut

Returns

Promise<HandoffResult>, resolved when the conversation has ended.

Field	Type	Description
status	'completed' | 'failed' | 'stopped' | 'timeout' | 'cancelled' | 'model_unavailable'	How it ended
submitted	number	Items the conversation submitted. Always 0 in Cowork for now: it has no business tools to submit with
failed	number	Items that failed. Always 0 in Cowork for now
sessionId	string	The conversation, when one was opened
error	string	What went wrong

Errors

The promise rejects with an error whose code is:

code	Meaning
AGENT_NOT_DECLARED	No dozin.agent in package.json
BAD_REQUEST	Missing title, or files empty or over 50
FILE_NOT_FOUND	A file does not exist, is a folder, or the data folder does not exist
FILE_OUTSIDE_DATA	A file is outside dataDir, or is a link
AGENT_BUSY	One conversation is running and one is waiting already
NOT_AVAILABLE	Service conversations are not available in this Cowork
RUN_ENDED	The run that made the call has ended

One conversation runs at a time per task and one more may wait; the rest are refused.

Example

await ctx.writeJson('batches/0001.json', changedPatients);
const result = await ctx.agent.handoff({ title: 'Patients changed', files: ['batches/0001.json'], summary: '3 patients' });
ctx.status(`Handoff ${result.status}`);

Related

• Background Tasks Where ctx.agent comes from