# Percakapan Layanan

<Badge type="warning" text="Belum dirilis" />

Tugas latar belakang bisa menyerahkan sekumpulan file ke percakapan AI, yang membacanya dan bertindak dengan alat yang dideklarasikan Extension. Percakapan itu muncul di Cowork seperti percakapan lain, sehingga pengguna bisa mengikutinya.

## dozin.agent

| Field | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| `brief` | `string` | Ya | File `.md` di dalam paket: instruksi untuk percakapan |
| `model` | `{ id, effort? }` | Tidak | Model yang dipakai; `effort` adalah `max`, `xhigh`, `high`, `medium`, atau `low` |
| `tools` | `string[]` | Tidak | Alat bisnis yang boleh dipakai percakapan, hingga 8. Cowork belum punya alat yang bisa ditawarkan, jadi kosongkan saja |
| `secret` | `string` | Tidak | Sebuah `env` dari `dozin.secrets` yang dipakai alat tersebut |

## ctx.agent.handoff(input) <Badge type="warning" text="Belum dirilis" />

| Nama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| `input.title` | `string` | Ya | Judul percakapan; yang lebih dari 120 karakter dipotong |
| `input.files` | `string[]` | Ya | 1–50 file di dalam `dataDir`, path relatif atau absolut |
| `input.summary` | `string` | Tidak | Isi kumpulan file ini; yang lebih dari 4000 karakter dipotong |

### Nilai kembalian

`Promise<HandoffResult>`, selesai saat percakapan berakhir.

| Field | Tipe | Deskripsi |
|---|---|---|
| `status` | `'completed' \| 'failed' \| 'stopped' \| 'timeout' \| 'cancelled' \| 'model_unavailable'` | Cara percakapan berakhir |
| `submitted` | `number` | Item yang dikirim percakapan. Untuk saat ini selalu `0` di Cowork: belum ada alat bisnis untuk mengirimnya |
| `failed` | `number` | Item yang gagal. Untuk saat ini selalu `0` di Cowork |
| `sessionId` | `string` | Percakapannya, jika ada yang dibuka |
| `error` | `string` | Apa yang salah |

### Error

Promise di-reject dengan error yang `code`-nya:

| `code` | Arti |
|---|---|
| `AGENT_NOT_DECLARED` | Tidak ada `dozin.agent` di `package.json` |
| `BAD_REQUEST` | `title` tidak ada, atau `files` kosong atau lebih dari 50 |
| `FILE_NOT_FOUND` | Ada file yang tidak ada, berupa folder, atau folder data tidak ada |
| `FILE_OUTSIDE_DATA` | Ada file di luar `dataDir`, atau berupa link |
| `AGENT_BUSY` | Sudah ada satu percakapan berjalan dan satu lagi menunggu |
| `NOT_AVAILABLE` | Percakapan layanan tidak tersedia di Cowork ini |
| `RUN_ENDED` | Run yang melakukan panggilan sudah berakhir |

Satu percakapan berjalan dalam satu waktu per tugas dan satu lagi boleh menunggu; sisanya ditolak.

## Contoh

```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}`);
```

## Terkait

- [Tugas Latar Belakang](https://docs.micromeet.ai/id/extension-sdk/service.md): Asal `ctx.agent`