Wire protocol

Wire-format detail for AI Transport over Ably channels: the fields AI Transport writes on each message, and how a streamed response is laid out on the channel.

AI Transport writes ordinary Ably messages to the conversation's Ably channel. Any Ably client can read them, and the fields below are what AI Transport puts on them. The codec owns a message's name, data and most of its extras. The adaptor adds a small number of fields of its own.

Extras fields

Ably accepts only known keys at the top level of a message's extras. AI Transport uses three:

KeyWritten byContents
extras.aiThe codec builder and the adaptorThe SDK's own fields. Ably reserves this key for AI Transport, and a value under it travels as it is, nested objects included.
extras.headersThe codec and the callerFlat headers, which Ably's server-side filtering reads. Values must be strings, numbers, booleans or null.
extras.ephemeralThe codec buildertrue when a codec row marks the message ephemeral. Ably delivers it to subscribed clients and keeps it out of history.

Under extras.ai, a codec built with defineCodec writes three fields, and the adaptor writes two more:

FieldWritten byMeaning
typeCodec builderThe event type, which picks the codec row on decode.
fieldsCodec builderThe row's event fields that travel beside data, nested values included.
codecCodec builderThe codec's id, on every message the codec encodes.
streamAdaptortrue on every write under a live stream key: the publish that opens the stream, each append, and each update.
endsAdaptorOn the message that ends a stream, the serial of the stream's message.

Every message also carries the codec's name as its message name. A decoder passes a message to its codec only when the message has both the codec's name and its id under extras.ai.codec.

A codec written by hand must also write its name and id, and can put its own fields anywhere Ably allows. The adaptor's two fields are the only ones it writes under extras.ai.

Call headers

send() and pipe() take headers, which the adaptor adds under extras.headers on every message the call publishes. A codec row can write headers there too. Where both set a key, the row's value is used. The adaptor also takes default headers for every message it publishes, and a call's value is used over a default. A subscriber reads the merged map from delivery.message.extras.headers.

The codecs that ship with the SDK write no headers of their own, so extras.headers holds only the call's headers and the adaptor's defaults. A common use is a requestId that ties a response to the prompt it answers.

Plain and streamed messages

A codec row says where each message goes:

  • A plain publish has no key. It is one Ably message that nothing appends to.
  • A streamed message is opened under a key. The pipe publishes it for the stream's first delta, remembers its serial under the key, and appends each later delta's data to it. Ably concatenates appended data, so the message's data is the stream's text so far.
  • The message that ends a stream is published after the stream's appends have been acknowledged, with extras.ai.ends set to the serial of the stream's message.

Ably replaces a message's name and extras with those of the latest append. That is why a stream's first delta opens the message, rather than a separate start event: history then holds the start event, one message with the stream's whole text under the delta's type, and the end event, which decode the same way as the live sequence.

Read a streamed message back

A streamed message reaches a client in one of three ways:

How it arrivesdataVersion
A live appendThe appended fragment.Each append has a new version.serial.
The first delivery after an attachThe full content so far, as a message.update.The message's latest version.serial.
A history readThe whole message at its latest version.The message's latest version.serial.

The decoder core uses the message serial to identify the stream, and the version.serial to tell which deliveries it has already seen.

Channel options

Your application gets the channel with ably.channels.get(channelName) and sets its options, such as the channel modes. The adaptor and the decoder add no channel options, so your application can reuse the same channel for presence or LiveObjects.