Internals

The internals section is for engineers who want to understand the system before they depend on it, and for anyone building a custom codec.

Four layers fit together, from the application-facing model down to the SDK's internal components:

• Conversation tree: the highest-level structure. Every session is a tree of ConversationNodes (InputNodes keyed by codec-message-id for user prompts and RunNodes keyed by runId for agent replies), joined by parent and fork-of pointers. The view walks the tree to produce a flat message list for rendering.
• Codec architecture: the encoder converts client-published TInputs and agent-published TOutputs into Ably publish operations. The decoder converts inbound Ably messages back into typed events. The codec lets AI Transport work with any AI framework.
• Wire protocol: the Ably channel format. Two header tiers (extras.ai.transport for run and message identity plus the stream lifecycle; extras.ai.codec for the payload identity a codec declares), four run lifecycle event names (ai-run-start, ai-run-suspend, ai-run-resume, ai-run-end), two step lifecycle event names (ai-step-start, ai-step-end), one cancel signal (ai-cancel), and two content event names (ai-input for client publishes, ai-output for agent publishes). Nine message names in all.
• Transport patterns: the SDK-internal components that carry the codec's messages over the wire: the stream router that fans inbound channel messages out to per-run streams, the input-event lookup that resolves a POSTed invocation to its channel events, and the cancel-routing pipeline.

Topics