# Service Conversations

<Badge type="warning" text="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) <Badge type="warning" text="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

```js
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](https://docs.micromeet.ai/extension-sdk/service.md): Where `ctx.agent` comes from