Awareness

Awareness is the live state of the agent and the user. For example, the agent is thinking, the agent is on step three of five, the user has the conversation open, or the user has left. Awareness uses the same Ably channel as the conversation, using built-in Ably channel features like LiveObjects and Presence.

How awareness works

Awareness features allow your agent and user to keep each other informed with live updating state.

When the agent changes states, for example from thinking to building, the old status no longer matters. Awareness features are based on giving the client the most recent data. Live subscribed clients are updated, and clients who join late get the most recent values automatically.

Pick a feature

Three Ably features carry awareness on the channel: LiveObjects, ephemeral messages, and presence. Each one suits a different job:

• LiveObjects holds structured state, such as the agent's plan and progress. A client that joins late receives the whole state when its channel attaches.
• Ephemeral messages carry frequent signals that matter only at the moment they are sent, and are only received by currently connected live subscribers, such as a status line while a tool call is in progress.
• Presence holds the set of agents and users on the channel, with the state of each member.

The agent can check whether the user is still on the channel with presence or occupancy. Occupancy counts the connections that receive the channel's messages, so the user's client does not have to enter presence. If the user has left, the agent can send a push notification to the user's devices.

Share user context

The client typically sends the prompt to the agent in an HTTP request. That request can easily carry additional context about the user: the page they are viewing, the settings they've selected, and more. Sending this kind of data in the HTTP request to an agent is the most common pattern.

If required, your application can write this data to Ably channel features. You can store state in LiveObjects so that it's always available to the agent without needing to store it in your database.

This client code example writes a user's "selected row" to LiveObjects state:

const root = await channel.object.get();
await root.set('selectedRowId', rowId);

This agent code reads the selected row with its HTTP client at the start of a step:

// The HTTP client has the LiveObjects plugin.
const selectedRowId = await httpClient.channels.get(channelName).object.get({ path: 'selectedRowId' });

When the agent stops

Each feature leaves different state behind when the agent crashes or its process ends without cleaning up. Any state left in LiveObjects remains there after the agent disconnects. So a plan that is half-completed will remain as the agent last wrote it. Presence is different: Ably removes the agent's presence member entry about 15 seconds after its connection drops, and every subscribed client will then see the agent leave Presence.

Pages in this section