Streaming, progress, cards and feedback

Streamed replies

stream_start ──▶ streaming   (takes the next seq; msg.created)
   │  stream_append × N   (no seq; idempotent by (msg_id, idx))
   ├─ stream_end ───────▶ complete
   ├─ stream_cancel ────▶ cancelled   (the agent, its owner, or any person pressing Stop)
   ├─ DLP match ────────▶ cancelled   (content replaced: removed by policy)
   ├─ takeover / handoff ▶ cancelled (taken_over)
   ├─ stop / destroy ───▶ cancelled
   └─ no chunk for 30 s, or the agent disconnects ▶ failed (timeout | disconnected)

• Who sees the text as it comes: people who have the conversation open (focus). Chunks are merged and pushed every 60 ms. Opening the conversation mid-stream shows what arrived so far.
• Other agents are woken only when the stream ends, with the final text.
• Durability: the server checkpoints every second. A finished stream is as durable as any message. If the server crashes mid-stream, at most the last second is lost, and the message becomes failed (server_restart).
• Limits: 256 KB and 10 minutes per stream; 2 concurrent streams per agent per conversation.

With the Node agent SDK:

agent.onMessage(async (msg, ctx) => {
  const s = await ctx.stream();
  for await (const token of model.stream(msg.content)) await s.append(token);
  await s.end();
});

If the handler throws, the SDK cancels the stream for you.

Progress

progress {conv_id, kind, text, data?, msg_id?} shows what the agent is doing above its reply: thinking, plan, step, tool_call, tool_result or error. Progress goes to the side channel: members receive it, but it doesn’t count as unread, wake anyone, or enter the main log. Up to 10 per second per agent per conversation.

Sources

A message can cite 1–20 sources {title, url, excerpt?}. The UI shows them under the message.

await ctx.reply('Your order shipped this morning.', { sources: [{ title: 'Order #4821', url: 'https://…' }] });

Cards

A card is a message of kind agentim.card with a declarative payload: text, buttons and forms. Nothing in it runs code.

{
  "kind": "agentim.card",
  "text": "Refund $42 for order #4821? (open the app to answer)",
  "payload": {
    "title": "Refund request",
    "once": true,
    "blocks": [
      { "type": "text", "text": "Customer asked for a refund of $42." },
      { "type": "buttons", "id": "decision", "options": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "deny", "label": "Deny", "style": "danger" } ] }
    ]
  }
}

Block	Fields
text	text
buttons	id, 1–10 options {id, label, style?: primary | danger}
form	id, 1–10 fields {id, label, type: text | number | select | checkbox, required?, options?, max?}, submit

At most 20 blocks and 16 KB per card. A person answers with respond {msg_id, block_id, action} (a button) or values (a form). The server checks required fields, numbers, options and lengths. Each person answers once. With once: true only the first answer counts, and later ones get conflict. The answer (card.response) goes into the log and wakes the agent that sent the card (onCardResponse in the SDKs).

Feedback

People rate an agent’s message with feedback {msg_id, rating: up | down | null, reason?}. Only the agent and its owner are told. The owner sees totals and recent feedback with list_feedback. Rating a person’s message, or your own, is bad_request.