# Agent presence

Your users see when the agent is thinking, streaming, idle, or offline. AI Transport channels carry Ably Presence, so an agent self-reports its state and every client sees it in real time.

Agent presence gives session participants a real-time view of which agents are active and what they are doing. Agent presence uses Ably's native [Presence](https://ably.com/docs/presence-occupancy/presence.md?source=llms.txt) API on the AI Transport session channel. This works for a single orchestrator agent or a fleet of sub-agents, and conveys whether the agent is streaming, thinking, idle, or offline.

![Diagram showing presence-aware agent status updates](https://raw.githubusercontent.com/ably/docs/main/src/images/content/diagrams/ait-presence-aware.png)

<Aside data-type='note'>
Agent presence is not built into the AI Transport SDK. It uses the Ably Presence API alongside AI Transport.
</Aside>

## How it works 

The agent enters presence on the AI Transport session channel with status data. As the agent moves through its turn lifecycle (receiving a message, thinking, streaming, finishing), it updates its presence data. Every connected client receives these updates in real time.

<Code>

### Javascript

```
// Server: agent enters presence when it connects.
const channel = ably.channels.get(sessionChannelName);
await channel.presence.enter({ status: 'idle' });

app.post('/api/chat', async (req, res) => {
  const { turnId, clientId, messages } = req.body;
  const turn = transport.newTurn({ turnId, clientId });

  await channel.presence.update({ status: 'thinking' });

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    abortSignal: turn.abortSignal,
  });

  await channel.presence.update({ status: 'streaming' });
  await turn.streamResponse(result.toUIMessageStream());
  await channel.presence.update({ status: 'idle' });
  res.json({ ok: true });
});
```
</Code>

## Subscribe to agent status 

On the client, subscribe to presence events to track the agent's current state:

<Code>

### Javascript

```
const channel = ably.channels.get(sessionChannelName);

channel.presence.subscribe((member) => {
  if (member.clientId === 'agent') {
    console.log(`Agent is ${member.data.status}`);
  }
});

const members = await channel.presence.get();
const agent = members.find((m) => m.clientId === 'agent');
```
</Code>

## Combine presence with active turns 

For richer status indicators, combine presence data with `useActiveTurns`. Presence tells you the agent's self-reported state. Active turns tell you which turns are in progress:

<Code>

### Javascript

```
const activeTurns = useActiveTurns({ transport });
const agentStatus = useAgentPresence(channel); // your custom hook

const isStreaming = activeTurns.has('agent');
const isIdle = agentStatus === 'idle' && !isStreaming;
const isOffline = agentStatus === null;
```
</Code>

This is enough information for the UI to show a typing indicator while the agent thinks, a streaming animation while tokens arrive, and an offline badge when the agent disconnects.

## Edge cases and unhappy paths 

- An agent that exits without calling `presence.leave()` (for example, a crashed process) is automatically removed from presence after a timeout. The agent is treated as present until the timeout fires. Wire a graceful shutdown that calls `leave` for the best user experience.
- A serverless agent that comes up for one turn and tears down should enter and leave presence per turn; entering once and leaving once at the end is fine for a long-running agent.
- Presence updates do not guarantee strict ordering with channel messages. A `streaming` presence update sometimes arrives slightly after the first token. Drive the UI off active turns for token-level state and use presence for higher-level status.
- Multi-agent setups need unique `clientId` per agent. Two agents with the same `clientId` collide in the presence set.
- A client without `presence` capability cannot subscribe to updates. Capability scoping is part of [authentication](https://ably.com/docs/ai-transport/concepts/authentication.md?source=llms.txt).

## FAQ 

### Does presence cost a message? 

Presence enter, update, and leave each consume a message on the channel. See [the platform pricing](https://ably.com/docs/platform/pricing.md?source=llms.txt) for current rates.

### Can clients enter presence too? 

Yes. Presence is symmetric. A client that enters presence shows up alongside agents in the presence set. Use the `clientId` to distinguish.

### How long does presence persist after a disconnect? 
Until Ably's presence timeout fires (currently around 15 seconds). Active connections are not affected; this is for ungraceful disconnects.

### What is the difference between presence and `useActiveTurns`? 

Presence is self-reported by the agent. Active turns are observable from the channel by inspecting turn lifecycle events. Presence reports intent; active turns report fact. Both together produce richer status.

### Can I pause inference when no users are connected? 

Yes. Subscribe to presence and check whether any non-agent participants are present. If none, end the turn or short-circuit the LLM call. This is one of the cost-saving patterns presence enables.

## Related features 

- [Presence](https://ably.com/docs/presence-occupancy/presence.md?source=llms.txt): the Ably Presence API used for agent status.
- [Concurrent turns](https://ably.com/docs/ai-transport/features/concurrent-turns.md?source=llms.txt): tracking active turns across clients.
- [Multi-device sessions](https://ably.com/docs/ai-transport/features/multi-device.md?source=llms.txt): presence works across every connected device.

## Related Topics

- [Token streaming](https://ably.com/docs/ai-transport/features/token-streaming.md?source=llms.txt): Stream AI-generated tokens to clients in realtime using AI Transport, with support for message-per-response and message-per-token patterns.
- [Cancellation](https://ably.com/docs/ai-transport/features/cancellation.md?source=llms.txt): Cancel AI responses mid-stream with Ably AI Transport. Scoped cancel signals, server-side authorization, and graceful abort handling.
- [Reconnection and recovery](https://ably.com/docs/ai-transport/features/reconnection-and-recovery.md?source=llms.txt): AI Transport streams survive connection drops automatically. Clients reconnect and resume from where they left off with no lost tokens.
- [Multi-device sessions](https://ably.com/docs/ai-transport/features/multi-device.md?source=llms.txt): Share AI conversations across tabs, phones, and laptops with Ably AI Transport. All devices see the same session in real time.
- [History and replay](https://ably.com/docs/ai-transport/features/history.md?source=llms.txt): Load conversation history from Ably channels with AI Transport. Paginated history, gapless continuity, and scroll-back patterns.
- [Conversation branching](https://ably.com/docs/ai-transport/features/branching.md?source=llms.txt): Edit user messages, regenerate AI responses, and navigate branches with Ably AI Transport. The full history is preserved as a tree.
- [Interruption](https://ably.com/docs/ai-transport/features/interruption.md?source=llms.txt): Let users interrupt AI agents mid-stream with Ably AI Transport. Cancel-then-send and send-alongside patterns for responsive AI interactions.
- [Concurrent turns](https://ably.com/docs/ai-transport/features/concurrent-turns.md?source=llms.txt): Run multiple AI turns simultaneously with Ably AI Transport. Independent streams, scoped cancellation, and multi-agent support.
- [Tool calling](https://ably.com/docs/ai-transport/features/tool-calling.md?source=llms.txt): Stream tool invocations and results through Ably AI Transport. Server-executed and client-executed tools with persistent state.
- [Human-in-the-loop](https://ably.com/docs/ai-transport/features/human-in-the-loop.md?source=llms.txt): Add human approval gates to AI agent workflows with Ably AI Transport. Approve tool executions and provide input across devices.
- [Optimistic updates](https://ably.com/docs/ai-transport/features/optimistic-updates.md?source=llms.txt): User messages appear instantly in Ably AI Transport. Optimistic insertion with automatic reconciliation when the server confirms.
- [Push notifications](https://ably.com/docs/ai-transport/features/push-notifications.md?source=llms.txt): Notify users when AI agents complete background tasks with Ably Push Notifications. Reach users even when they're offline.
- [Chain of thought](https://ably.com/docs/ai-transport/features/chain-of-thought.md?source=llms.txt): Stream reasoning and thinking content alongside responses with Ably AI Transport. Display chain-of-thought in real time.
- [Double texting](https://ably.com/docs/ai-transport/features/double-texting.md?source=llms.txt): Handle users sending multiple messages while the AI is streaming with Ably AI Transport. Queue or run messages concurrently.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt?source=llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.