Get started with the Core SDK

import { after } from 'next/server';
import { streamText, convertToModelMessages } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import * as Ably from 'ably';
import { createAgentSession, Invocation } from '@ably/ai-transport';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });

export async function POST(req) {
  const invocation = Invocation.fromJSON(await req.json());

  const session = createAgentSession({
    client: ably,
    channelName: invocation.sessionName,
    codec: UIMessageCodec,
  });

  await session.connect();

  const run = session.createRun(invocation, { signal: req.signal });

  after(async () => {
    try {
      // Rebuild the conversation from run.view before run.start(): draining pages
      // in this run's triggering input (otherwise run.start() awaits it live).
      while (run.view.hasOlder()) {
        await run.view.loadOlder();
      }
      const conversation = run.view.getMessages().map(({ message }) => message);

      await run.start();

      const result = streamText({
        model: anthropic('claude-sonnet-4-20250514'),
        system: 'You are a helpful assistant.',
        messages: await convertToModelMessages(conversation),
        abortSignal: run.abortSignal,
      });

      const { reason } = await run.pipe(result.toUIMessageStream());
      await run.end({ reason });
    } catch (err) {
      await run.end({ reason: 'error' });
      throw err;
    } finally {
      session.close();
    }
  });

  return Response.json({ runId: run.runId, invocationId: run.invocationId });
}

'use client';

import { useState } from 'react';
import { useClientSession, useView } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

async function wakeAgent(run) {
  const res = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(run.toInvocation().toJSON()),
  });
  return res.json();
}

export function Chat() {
  const [input, setInput] = useState('');

  const { session } = useClientSession();
  const view = useView({ limit: 30 });
  const { messages, runOf } = view;

  // `'active'`, `'suspended'`, and `'error'` keep the Stop button visible
  // so a stuck Run can still be cancelled; `'complete'` and `'cancelled'`
  // are terminal.
  const latestRun = runOf(messages.at(-1)?.codecMessageId ?? '');
  const isStreaming =
    latestRun !== undefined &&
    latestRun.status !== 'complete' &&
    latestRun.status !== 'cancelled';

  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!input.trim()) return;
    const text = input;
    setInput('');
    const run = await view.send(UIMessageCodec.createUserMessage({
      id: crypto.randomUUID(),
      role: 'user',
      parts: [{ type: 'text', text }],
    }));
    await wakeAgent(run);
  };

  const stop = async () => {
    if (latestRun) await session.cancel(latestRun.runId);
  };

  return (
    <div>
      {view.hasOlder && (
        <button type="button" onClick={() => view.loadOlder()}>Load older messages</button>
      )}
      {messages.map(({ codecMessageId, message }) => (
        <div key={codecMessageId}>
          <strong>{message.role}:</strong>{' '}
          {message.parts.map((part, i) =>
            part.type === 'text' ? <span key={i}>{part.text}</span> : null,
          )}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={(e) => setInput(e.target.value)} placeholder="Type a message..." />
        {isStreaming ? (
          <button type="button" onClick={stop}>Stop</button>
        ) : (
          <button type="submit">Send</button>
        )}
      </form>
    </div>
  );
}

'use client';

import { useEffect, useState } from 'react';
import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { ClientSessionProvider } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';
import { Chat } from './chat';

function Providers({ children }) {
  const [client, setClient] = useState(null);

  useEffect(() => {
    const ably = new Ably.Realtime({ authUrl: '/api/auth/token', clientId: 'user' });
    setClient(ably);
    return () => ably.close();
  }, []);

  if (!client) return null;
  return <AblyProvider client={client}>{children}</AblyProvider>;
}

export default function Page() {
  const channelName = 'conversations:my-chat-session';
  return (
    <Providers>
      <ClientSessionProvider channelName={channelName} codec={UIMessageCodec}>
        <Chat />
      </ClientSessionProvider>
    </Providers>
  );
}