Handler context
Reference for Message and the reliable actions available when wrapping an existing agent or workflow.
defineAgent({ handle }) calls the handler with a normalized Message and Noir context.
async handle(message, noir) {
await noir.status('Working…')
const result = await noir.run('answer', () => existingAgent.run(message.text))
return result
}Message
Message contains all InboundMessage fields plus aliases optimized for handler code:
user: verified actorconversation: channel locationfiles: current message attachmentstext,id,receivedAt,replyToId, and metadata
Noir actions
| Method | Purpose |
|---|---|
send(output) | queue a durable message or rich output |
status(text) | show non-final progress |
edit(messageId, text) | replace an existing message |
react(messageId, reaction, options) | add or remove a reaction |
sendFile(file, text?) | deliver an encoded file |
sendCard(card, text?) | deliver an interactive card |
typing(active, messageId?) | set native typing/status where supported |
markRead(messageId) | send a read receipt where supported |
run(name, execute) | checkpoint and reuse successful JSON work |
ask(options) | pause for requester-bound approval |
resolveFile(id, options?) | resolve a signed current-message attachment |
The context also exposes executionId, signal, and normalized services. user, conversation, and files are the canonical names. The older runId, actor, channel, attachments, progress, step, and approve names remain deprecated.
Return value
A handler may return nothing, a string, one AgentOutput, or an array of strings and outputs. Returning a string is shorthand for noir.send(string). Explicit sends and the returned output are delivered in order through the outbox.
Use the abort signal for downstream model and provider calls. Stop work promptly when the turn is superseded, canceled, or timed out.