Skip to content

Zak/ait 1214 docs impovements #3498

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zknill merged 2 commits into from
Jul 28, 2026
Merged

Zak/ait 1214 docs impovements #3498

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dce4411
Fix Vercel tool-calling docs for static tool-call encoding
zknill Jul 27, 2026
3260f2c
Consolidate AI Transport concepts and restyle docs
zknill Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 41 additions & 9 deletions .claude/skills/write-docs/SKILL.md
View file
Open in desktop

Large diffs are not rendered by default.

26 changes: 1 addition & 25 deletions src/data/nav/aitransport.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,38 +73,14 @@ export default {
name: 'Sessions',
link: '/docs/ai-transport/concepts/sessions',
},
{
name: 'Connections',
link: '/docs/ai-transport/concepts/connections',
},
{
name: 'Runs',
link: '/docs/ai-transport/concepts/runs',
},
{
name: 'Steps',
link: '/docs/ai-transport/concepts/steps',
},
{
name: 'Invocations',
link: '/docs/ai-transport/concepts/invocations',
},
{
name: 'Codecs',
link: '/docs/ai-transport/concepts/codecs',
},
{
name: 'Conversation tree',
link: '/docs/ai-transport/concepts/conversation-tree',
},
{
name: 'Authentication',
link: '/docs/ai-transport/concepts/authentication',
},
{
name: 'Infrastructure',
link: '/docs/ai-transport/concepts/infrastructure',
},
],
},
{
Expand Down Expand Up @@ -176,7 +152,7 @@ export default {
link: '/docs/ai-transport/features/interruption-and-steering',
},
{
name: 'LiveObjects State',
name: 'LiveObjects state',
link: '/docs/ai-transport/features/liveobjects',
},
{
Expand Down
22 changes: 11 additions & 11 deletions src/pages/docs/ai-transport/api/errors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,21 +36,21 @@ The `ErrorInfo` type is exported from `ably`. AI Transport surfaces it as the re
| ----- | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 40000 | BadRequest | 400 | The request was malformed or missing required fields. | Check the request payload and ensure all required fields are present. |
| 40003 | InvalidArgument | 400 | An argument passed to a session or run method was invalid. | Verify the arguments match the expected types and constraints. |
| 40160 | InsufficientCapability | 401 | The Ably channel rejected a publish for a capability reason. The token does not permit the operation. | Add the missing capability to the token. See [authentication](/docs/ai-transport/concepts/authentication). |
| 40160 | InsufficientCapability | 401 | The Ably channel rejected a publish for a capability reason. The token does not permit the operation. | Add the missing capability to the [token](/docs/ai-transport/getting-started/authentication). |

### Session and run errors <a id="session-run"/>

| Code | Name | HTTP status | Description | Recovery |
| ------ | ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 104000 | EncoderRecoveryFailed | 500 | The encoder failed to recover after a publish error. One or more `updateMessage` calls could not recover a failed append pipeline. | End the Run with reason `'error'` and start a new one. The client sees the partial response up to the failure point. |
| 104001 | SessionSubscriptionError | 500 | A session-level channel subscription callback threw unexpectedly. | Check the subscription callback for unhandled exceptions. Inspect the underlying error for details. |
| 104002 | CancelListenerError | 500 | The cancel listener or `onCancel` hook threw while processing a cancel message. | Check the `onCancel` hook for unhandled exceptions. The Run may not respond to subsequent cancels. |
| 104003 | RunLifecycleError | 500 | A publish within a Run failed (lifecycle event, message, or codec event). | Check channel permissions and connection state. Surface the error to the calling HTTP handler so the client's pending send fails. |
| 104000 | EncoderRecoveryFailed | 500 | The encoder failed to recover after a publish error. One or more `updateMessage` calls could not recover a failed append pipeline. | End the run with reason `'error'` and start a new one. The client sees the partial response up to the failure point. |
| 104001 | SessionSubscriptionError | 500 | A session-level subscription callback threw unexpectedly. | Check the subscription callback for unhandled exceptions. Inspect the underlying error for details. |
| 104002 | CancelListenerError | 500 | The cancel listener or `onCancel` hook threw while processing a cancel message. | Check the `onCancel` hook for unhandled exceptions. The run may not respond to subsequent cancels. |
| 104003 | RunLifecycleError | 500 | A publish within a run failed (lifecycle event, message, or codec event). | Check channel permissions and connection state. Surface the error to the calling HTTP handler so the client's pending send fails. |
| 104004 | SessionClosed | 400 | An operation was attempted on a session that has already been closed. | Create a new session. Do not reuse a closed session. |
| 104005 | SessionSendFailed | 500 | A send failed: either the core's channel publish failed, or the Vercel chat transport's agent-invocation POST failed (network error or non-2xx response). | Check the API endpoint URL, network connectivity, and authentication. Inspect the underlying error for details. |
| 104006 | ChannelContinuityLost | 500 | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events. | Surfaced via the session's `on('error')` on both the client and the agent. End active Runs; subsequent operations can resume once the channel reattaches. |
| 104006 | ChannelContinuityLost | 500 | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events. | Surfaced via the session's `on('error')` on both the client and the agent. End active runs; subsequent operations can resume once the channel reattaches. |
| 104007 | ChannelNotReady | 400 | An operation was attempted but the channel is not in a usable state (not `ATTACHED` or `ATTACHING`). | Wait for the channel to attach before retrying, or inspect channel state and connection state for the underlying cause. |
| 104008 | StreamError | 500 | An error occurred while piping a response stream to the channel. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream. | Inspect `cause` for the provider error. End the Run with reason `'error'`. The error is also returned on `StreamResult.error` from `Run.pipe`. |
| 104008 | StreamError | 500 | An error occurred while piping a response stream to the session. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream. | Inspect `cause` for the provider error. End the run with reason `'error'`. The error is also returned on `StreamResult.error` from `Run.pipe`. |

### Auth and channel errors <a id="platform"/>

Expand All @@ -62,9 +62,9 @@ Auth and channel errors come from the Ably platform, not AI Transport. The most
| 40300 | Forbidden. | The token is valid but not authorised for this resource. |
| 80000 | Channel attach failed. | Check the channel name and capability. |
| 90000 | Internal channel error. | Retry the operation. If the error persists, contact support. |
| 93002 | `Can only update/delete/append messages on channels with mutableMessages enabled`. The namespace lacks the `mutableMessages` rule, so AI Transport cannot append stream tokens. This is the most common AI Transport setup failure. | Enable the **Message annotations, updates, deletes, and appends** rule on the namespace. See [Configure the channel rule](/docs/ai-transport/getting-started/channel-rules). |
| 93002 | `Can only update/delete/append messages on channels with mutableMessages enabled`. The namespace lacks the `mutableMessages` rule, so AI Transport cannot append stream tokens. This is the most common AI Transport setup failure. | Enable the **Message annotations, updates, deletes, and appends** [rule on the namespace](/docs/ai-transport/getting-started/channel-rules). |

The full Ably error code list lives at [Ably error codes](/docs/platform/errors/codes).
The [Ably error codes](/docs/platform/errors/codes) page lists every code the platform returns.

## Match an ErrorInfo against a code <a id="error-info-is"/>

Expand All @@ -86,7 +86,7 @@ session.on('error', (error) => {

## Example <a id="example"/>

Handle session-level and run-level errors separately. Both the client and the agent subscribe to session errors with `session.on('error')`. The agent additionally uses the run runtime's `onError` for per-Run failures.
Handle session-level and run-level errors separately. Both the client and the agent subscribe to session errors with `session.on('error')`. The agent additionally uses the run runtime's `onError` for per-run failures.

<Code>
```javascript
Expand Down Expand Up @@ -116,7 +116,7 @@ const run = agentSession.createRun(invocation, {
},
});

// End a Run with reason 'error' when piping fails.
// End a run with reason 'error' when piping fails.
try {
const result = await run.pipe(llmStream);
await run.end({ reason: result.reason });
Expand Down
16 changes: 7 additions & 9 deletions src/pages/docs/ai-transport/api/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
title: "API reference"
meta_description: "API reference for Ably AI Transport. Sessions, codec, React hooks, Vercel integration, and errors."
meta_keywords: "API reference, AI Transport, ClientSession, AgentSession, codec, React hooks, Vercel, errors, Ably"
intro: "Reference for every public API surface in the @ably/ai-transport package. The SDK is organised into four entry points so you only import what you need."
intro: "Reference for every public API in the @ably/ai-transport package. The SDK is organised into four entry points so you only import what you need."
redirect_from:
- /docs/ai-transport/api-reference
---

This reference covers every public API surface in the `@ably/ai-transport` package. The SDK is organised into four entry points so you only import what you need.
This reference covers every public API in the `@ably/ai-transport` package. The SDK is organised into four entry points so you only import what you need.

## Quick example <a id="quick-example"/>

Expand All @@ -29,8 +29,6 @@ await session.connect();
```
</Code>

See the individual reference pages for the full API.

## Entry points <a id="entry-points"/>

| Entry point | Import path | Contents |
Expand All @@ -52,13 +50,13 @@ The Vercel entry points re-export the core factories with the codec pre-bound. I
{[
{
title: 'ClientSession',
description: 'Subscribe to a channel, build a conversation tree, send messages, and cancel Runs from the client.',
description: 'Subscribe to a session, build a conversation tree, send messages, and cancel runs from the client.',
image: 'icon-product-pubsub',
link: '/docs/ai-transport/api/javascript/core/client-session',
},
{
title: 'AgentSession',
description: 'Manage Run lifecycles, publish lifecycle events, and pipe streamed assistant output from the server.',
description: 'Manage run lifecycles, publish lifecycle events, and pipe streamed assistant output from the server.',
image: 'icon-product-pubsub',
link: '/docs/ai-transport/api/javascript/core/agent-session',
},
Expand Down Expand Up @@ -89,7 +87,7 @@ The Vercel entry points re-export the core factories with the codec pre-bound. I
},
{
title: 'vercelRunOutcome',
description: 'Map a Vercel streamText finishReason and pipe result to a VercelRunOutcome for Run.suspend / Run.end.',
description: 'Map a Vercel streamText finishReason and pipe result to a VercelRunOutcome for run.suspend / run.end.',
image: 'icon-tech-vercel',
link: '/docs/ai-transport/api/javascript/vercel/run-outcome',
},
Expand Down Expand Up @@ -128,13 +126,13 @@ The Vercel entry points re-export the core factories with the codec pre-bound. I
},
{
title: 'useMessagesWithSeed',
description: 'Reconcile a persisted conversation seed with the live channel and render the composed conversation.',
description: 'Reconcile a persisted conversation seed with the live session and render the composed conversation.',
image: 'icon-tech-react',
link: '/docs/ai-transport/api/react/core/use-messages-with-seed',
},
{
title: 'useTree',
description: 'Stable structural query callbacks for inspecting Runs outside the visible branch.',
description: 'Stable structural query callbacks for inspecting runs outside the visible branch.',
image: 'icon-tech-react',
link: '/docs/ai-transport/api/react/core/use-tree',
},
Expand Down
Loading