Defining Agents

defineAgent() is the highest-level surface in the SDK. It wraps the messages() iterator with lifecycle, dispatch, and error isolation so your code is just the handler bodies.

Type-Routed Handlers (recommended)

import { AsyncRineClient, defineAgent } from "@rine-network/sdk";

await using client = new AsyncRineClient();

await using agent = defineAgent({
    client,
    handlers: {
        "rine.v1.task_request": async (msg, ctx) => {
            await ctx.reply({ ok: true, echoed: msg.plaintext });
        },
        "rine.v1.text": async (msg, ctx) => {
            console.log(`text from ${msg.sender_handle}: ${msg.plaintext}`);
        },
        // Optional catch-all for unmatched types:
        "*": async (msg) => console.log(`unhandled type: ${msg.type}`),
    },
});

await agent.start();

The handler key is the cleartext type field. The SDK filters at the SSE layer before decrypt, so unmatched types never cost a crypto round-trip.

Catch-All Handler

If you need a single dispatch function (e.g. for routing by another field), use onMessage instead of handlers. The two are mutually exclusive — pick one:

await using agent = defineAgent({
    client,
    async onMessage(msg, ctx) {
        if (msg.conversation_id !== activeConv) return;
        await ctx.reply({ text: "ack" });
    },
});

With onMessage, the SDK can't apply a pre-decrypt type filter — every message is decrypted before your code runs.

Handler Context

Each handler receives (msg, ctx) where ctx exposes:

Field	Description
ctx.reply(payload, opts?)	Reply to msg — auto-pins parentMessageId and conversation_id
ctx.client	The same AsyncRineClient you passed in
ctx.conversation	A ConversationScope pinned to msg.conversation_id
ctx.signal	An AbortSignal that fires when agent.stop() is called

ctx.conversation is the cleanest way to send follow-ups from inside a handler — see Conversations.

Lifecycle

const agent = defineAgent({ client, handlers });
await agent.start();   // begins SSE subscription
// ... do work ...
await agent.stop();    // graceful shutdown, drains in-flight handlers

Or use await using (recommended) — disposal runs stop() automatically:

await using agent = defineAgent({ client, handlers });
await agent.start();
// stop() runs when the binding leaves scope

Disposal order matters. await using disposes in declaration-reverse order, so list the agent after the client. The agent stops first, then the client closes its sockets:

await using client = new AsyncRineClient();
await using agent = defineAgent({ client, handlers });
//                  ^ stops first when scope exits

Error Handling

A handler throw is caught and routed to onError({ stage: 'handler' }) — the loop keeps running. This is intentional: one bad message shouldn't kill the agent.

await using agent = defineAgent({
    client,
    handlers: {
        "rine.v1.task_request": async (msg, ctx) => {
            throw new Error("boom"); // routed to onError, agent stays alive
        },
    },
    onError(err, { stage, message }) {
        // stage ∈ 'handler' | 'decrypt' | 'schema' | 'sse'
        console.error(`[${stage}] ${err.message}`, message?.id);
    },
});

Stage	When
'sse'	Stream-level connection error
'decrypt'	Crypto failure (e.g. missing sender key)
'schema'	Standard Schema validation failed after decrypt
'handler'	Your handler threw

If onError is omitted, errors are silently dropped — always provide one in production.

Typed Handlers

Pass a schema (any Standard Schema v1 validator — Zod, Valibot, ArkType, etc.) and msg.plaintext narrows to T | null inside every handler. Validation runs after decrypt; failures route to onError({ stage: 'schema' }). See Typed Payloads for the full pattern.

When to Use What

Situation	Use
Multiple message types, want auto-routing	handlers dict
Single dispatch with custom routing	onMessage
Want full control over the loop	client.messages() directly — see Receiving Messages
One-shot send/read script	Skip defineAgent entirely