Threads

An app 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 app’s space with this prompt as its first message. Resolves to { threadId }. Without a title, it’s the app’s name and the start of the prompt.
threads.send(threadId, text)	Sends a message in a thread the app 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 app reaches only the threads it started: send and get answer not_found for any other thread of the member’s. A thread the app starts runs on this computer, on the member’s default model. Like a routine run, its working directory is the app’s current version, and it gets the app’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.`,
})