Add AI Transport LiveObjects docs by owenpearson · Pull Request #3423 · ably/docs

owenpearson · 2026-06-18T15:53:39Z

coderabbitai · 2026-06-18T15:53:48Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: db1f3f64-2ab6-4ec9-a8b3-942dab66a72f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch ait-liveobjects

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

paddybyers · 2026-06-19T06:51:46Z

Much of this reads like Claude in smartarse mode. Can you de-claudeify the writing style?

VeskeR · 2026-06-19T17:14:45Z

+import { OBJECT_MODES } from '@ably/ai-transport';
+import { createAgentSession } from '@ably/ai-transport/vercel';
+
+const session = createAgentSession({


The example above used createClientSession from @ably/ai-transport. I'd prefer we stick to a single import inside one file to avoid confusion.
My preference goes to more abstract @ably/ai-transport as we do plan to introduce more codecs

ah good spot, i've amended it now

VeskeR · 2026-06-19T17:25:17Z

 | Property | Description | Type |
 | --- | --- | --- |
 | presence | The Ably presence object for the session's channel. Use it to see which clients are connected — for example, to detect whether the requesting user is still online (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics — it is the same instance the channel exposes — and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |
+| object | The Ably LiveObjects root for the session's channel. Use it to read and write shared `LiveMap` / `LiveCounter` state on the channel the session already uses. The session adds no semantics; it is the same instance the channel exposes. Operating on it requires the client to be constructed with the `LiveObjects` plugin from `ably/liveobjects` and the object modes to be requested via [`channelModes`](#constructor-params); without both, the underlying SDK throws. See [LiveObjects State](/docs/ai-transport/features/live-objects). | `RealtimeObject` |


correction: object prop is not a root for LiveObjects on the channel, it merely gives access to the LiveObjects API for a channel.

VeskeR · 2026-06-19T17:25:29Z

 | tree | The complete conversation tree. Holds every known Run node and emits events on any change. Use `view` in most cases; reach for `tree` for low-level inspection. | <Table id='Tree'/> |
 | view | The default paginated, branch-aware view for rendering. Events scope to the visible messages. | <Table id='View'/> |
 | presence | The Ably presence object for the session's channel. Use it to see which clients are connected (`enter`, `leave`, `get`, `subscribe`). The session adds no semantics — it is the same instance the channel exposes — and presence operations implicitly attach, so they work without first awaiting [`connect()`](#connect). | `Ably.RealtimePresence` |
+| object | The Ably LiveObjects root for the session's channel. Use it to read and write shared `LiveMap` / `LiveCounter` state on the channel the session already uses. The session adds no semantics; it is the same instance the channel exposes. Operating on it requires the client to be constructed with the `LiveObjects` plugin from `ably/liveobjects` and the object modes to be requested via [`channelModes`](#constructor-params); without both, the underlying SDK throws. See [LiveObjects State](/docs/ai-transport/features/live-objects). | `RealtimeObject` |


ditto object is not root

VeskeR · 2026-06-19T17:27:15Z

+<Code>
+```javascript
+// On the agent: react whenever the user's state changes.
+const root = await session.object.get();


For the docs throughout: we no longer use root term in the public facing docs.
It is simply an object on a channel.
For example, and assignment like this should read const myObject = await channel.object.get();

Generic text references instead of On the agent, resolve the root once and let it react to every change should read On the agent, resolve the object on a channel once and let it react to every change

ah ok didn't know that, have updated now

VeskeR · 2026-06-19T17:33:06Z

+
+Shared state closes that gap. The user's current state lives on the session, the agent subscribes to it, and it reacts as the state changes instead of asking. State moves the other way too: the agent writes to the same object, and every connected client sees the update. This is what people mean by ambient state sync, the agent staying aware of what the user is doing without a round of questions. Both [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session) and [`AgentSession`](/docs/ai-transport/api/javascript/core/agent-session) expose that state directly as `session.object`, the channel's Ably [LiveObjects](/docs/liveobjects) root.
+
+Keep this to the state both sides actually need to share. The agent's private reasoning belongs on the server, and the back-and-forth of the conversation belongs in the message stream. `session.object` is the slice of state you choose to expose to the user, not a feed of everything the agent is doing.


I would tighten 3 paragraphs above to just a single one describing right away what LiveObjects State gives to AI gents. Skip "problem surface" from the first paragraph entirely. Reads a bit like an intro to a blog post. Other pages from "Features" don't do that, so I'd keep this aligned

have changed this now

owenpearson force-pushed the ait-liveobjects branch from 9573e31 to f9d30d3 Compare June 19, 2026 11:47

owenpearson added the review-app Create a Heroku review app label Jun 19, 2026

ably-ci temporarily deployed to ably-docs-ait-liveobjec-d8eiea June 19, 2026 11:49 Inactive

owenpearson requested a review from ttypic June 19, 2026 12:39

owenpearson marked this pull request as ready for review June 19, 2026 12:39