Threads

An extension can start an agent thread for the member, the same kind of thread they’d start themselves in Matter. The member sees it in Matter, and it works with Matter’s own tools.

const { threadId } = await matter.threads.start({
  prompt: 'Draft a reply to Sam about the renewal, using the notes on the Acme deal.',
  title: 'Reply to Sam',
})

await matter.threads.send(threadId, 'Keep it under 100 words.')

const thread = await matter.threads.get(threadId)
// { id, title, status, running, messages: [{ role, text, at, turnId }] }

Call	What it does
threads.start({ prompt, title? })	Starts a thread in the extension’s space with this prompt as its first message. Resolves to { threadId }. Without a title, it’s the extension’s name and the start of the prompt.
threads.send(threadId, text)	Sends a message in a thread the extension started, on the model it’s on; queued while a turn is under way. Resolves to { threadId, turnId }.
threads.get(threadId, { limit? })	The thread’s id, title, status and whether a turn is running, with its latest turns’ messages (20 by default, at most 100): the member’s, and the agent’s final replies, each { role, text, at, turnId }.

An extension reaches only the threads it started: send and get answer not_found for any other thread of the member’s. A thread the extension starts runs on this computer, on the member’s default model. Like a routine run, its working directory is the extension’s current version, and it gets the extension’s tools. If the member hasn’t chosen a default model, start fails with no_default_model, and its message asks them to choose one in Matter’s Settings.

Tasks, boards and docs

Tasks, boards and docs aren’t in the data API. To work with them, start a thread, or run a routine, and say what you want in the prompt: agents manage them with Matter’s own tools.

await matter.threads.start({
  prompt: `Create a task on the Sales board to follow up with ${deal.title} next Tuesday, and link it to the deal.`,
})