# Artifacts

Your agent writes the artifacts it creates to LiveObjects on the conversation's Ably channel. Every subscribed client receives each change in realtime, and a client that joins late receives the current state of the artifact.

An artifact is the reusable output that the agent creates in response to the user's prompt, such as a table of results, a document, a set of slides, or a pull request.

## How artifacts work 

The agent writes the artifact state to [LiveObjects](https://ably.com/docs/liveobjects.md) on the same [Ably channel](https://ably.com/docs/channels.md) as the [conversation](https://ably.com/docs/ai-transport/conversation.md). When the agent changes one part of the artifact, such as one row of a table, every subscribed client receives that change in realtime. A client that attaches the channel, including after a reload or when the user joins late, receives the current artifact state, and then each change as the agent or a user makes it.

## Where an artifact lives 

An artifact lives in three places:

| Place | What it holds | How long it lasts |
| --- | --- | --- |
| LiveObjects on the channel | The artifact state that subscribed clients show and edit | Until the channel's [object retention period](https://ably.com/docs/liveobjects/storage.md#default-persistence) passes with no update |
| Your database or blob storage | The durable copy of the artifact | For as long as you keep it |
| The conversation | A reference to the artifact, such as its id and title | For as long as you keep the conversation |

A reference keeps the conversation small. A response can say "I updated the table" and carry the table's id, and the client shows the table from its artifact state. The reference can be a part of the response, such as a `data-artifact` part with the Vercel [adaptor](https://ably.com/docs/ai-transport/api/javascript/agent-adaptor.md), or [its own message](https://ably.com/docs/ai-transport/conversation.md#own-messages) that the agent publishes on the channel.

You are responsible for keeping the [durable copy](https://ably.com/docs/ai-transport/artifacts/live-artifact-state.md#save) in your database. When the object retention period passes with no update, the [channel object](https://ably.com/docs/liveobjects/concepts/objects.md#channel-object) is empty, and you can restore the artifact from your database.



This agent code writes one row to a `table` map that the agent created earlier, with its [HTTP client](https://ably.com/docs/pub-sub/api/javascript/rest/rest-client.md):

<Code>

### Javascript

```
// httpClient comes from createHttpClient with the LiveObjects plugin.
await httpClient.channels.get(channelName).object.publish({
  path: 'table',
  mapSet: { key: row.id, value: { json: row } },
});
```
</Code>

This client code runs in a React component inside the `ChannelProvider` for the conversation's channel, and subscribes to the table:

<Code>

### Javascript

```
import { useObject } from '@ably/pubsub-device/liveobjects/react';

const { value: table } = useObject((object) => object.get('table'));
```
</Code>

The agent and the client each need [LiveObjects enabled](https://ably.com/docs/ai-transport/artifacts/live-artifact-state.md#enable): the `LiveObjects` plugin on each Ably client, the object [channel modes](https://ably.com/docs/channels/options.md#modes) on the client's channel and the object [capabilities](https://ably.com/docs/ai-transport/setup/authentication.md#capabilities) on the key and the token.

## Keep large payloads out of messages 

Every message has a [maximum size](https://ably.com/docs/platform/pricing/limits.md#message) that your Ably package sets. A message that carries a whole document or a large tool result can go over that size and fail to publish.

With LiveObjects, the agent builds an artifact from small operations, one key at a time. Each operation must fit in one message, and the artifact can grow larger than one message through many operations. All the objects on a channel share an [aggregate size limit](https://ably.com/docs/liveobjects/storage.md#limits).

You can put very large or binary output, such as files, images, or a repository, in blob storage. The channel then carries a URL or an id that points to the stored output, in a message or in a key of the artifact.

## Conversation or state? 

The conversation holds what the user and the agent said, in order. Artifact state holds the current value of what the user and the agent both act on. If the agent published an artifact as conversation messages, each edit would repeat the whole artifact, and a client that joins late would receive every version before the current one. If a client that joins late needs only the current value of something, it belongs in artifact state.

| Put it in | Examples |
| --- | --- |
| The conversation | Prompts, responses, tool calls and their results, a reference to the artifact |
| Live artifact state | The table, the document, the order of the slides |
| [Awareness](https://ably.com/docs/ai-transport/awareness.md) | The agent's status and progress, who is on the channel |
| Your database only | Past versions of the artifact |

## Read next 

- [Live artifact state](https://ably.com/docs/ai-transport/artifacts/live-artifact-state.md): Build a table the agent fills in row by row, show it on every device, and let users edit it.

Related pages:

- [Awareness](https://ably.com/docs/ai-transport/awareness.md): what the agent and the user are doing now
- [Conversation](https://ably.com/docs/ai-transport/conversation.md): the log of prompts and responses
- [LiveObjects](https://ably.com/docs/liveobjects.md): the objects API that artifacts use

## Related Topics

- [Live artifact state](https://ably.com/docs/ai-transport/artifacts/live-artifact-state.md): Build an artifact, such as a table of results, that users see the agent fill in. The agent writes it to LiveObjects on the channel over HTTP, and your database keeps the durable copy.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/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.