Agent Chats SDK

​

Set up your destination

1. Open Library → Agent Chats → Set up Agent Chats in the destination workspace. Ask an administrator if Agent Chats is unavailable.
2. Create an application, such as Support assistant, with a stable key, such as support-agent.
3. Set its access policy, content capture, redaction, retention, and allowed environments before sending customer data.
4. Create an ingest credential. Save the secret when it appears. BuildBetter shows it once.

​

Start with HTTP

• Header X-BuildBetter-Agent-Key: your ingest secret.
• Header Content-Type: application/json.
• Body agentKey: your application’s stable key.
• Body externalSessionId: your conversation ID.
• Body events: messages or feedback with stable event IDs, sequences, and timestamps.

​

Node SDK preview

import { BuildBetterAI } from "@buildbetter/ai";

const buildbetter = new BuildBetterAI({
  apiKey: process.env.BUILDBETTER_AGENT_SECRET!,
  agent: "support-agent",
  apiUrl: "https://api.buildbetter.app",
});

const session = {
  sessionId: "production:account_17:chat_123",
  startedAt: "2026-09-08T18:00:00.000Z",
  user: {
    id: "account_17:user_42",
    name: "Avery Chen",
    username: "avery",
    email: "avery@example.com",
    companyId: "account_17",
  },
  context: {
    productArea: "reporting",
    surface: "dashboard-assistant",
    routeTemplate: "/dashboards/:id",
    environment: "production",
  },
};

await buildbetter.capture({
  ...session,
  status: "open",
  messages: [
    {
      id: "user_1",
      role: "user",
      sequence: 1,
      createdAt: "2026-09-08T18:00:00.000Z",
      content: "Why is this report blank?",
    },
    {
      id: "assistant_1",
      role: "assistant",
      sequence: 3,
      createdAt: "2026-09-08T18:00:03.000Z",
      content: "I could not find the report.",
      final: true,
    },
  ],
});

​

Add thumbs-up, thumbs-down, or written feedback

await buildbetter.feedback({
  ...session,
  messageId: "assistant_1",
  messageSequence: 3,
  occurredAt: "2026-09-08T18:00:10.000Z",
  revision: 1,
  rating: "negative",
  labels: ["incorrect", "missing-context"],
  comment: "The report exists. You used the wrong dashboard.",
});

​

Vercel AI SDK preview

import { generateText } from "ai";
import { withBuildBetter } from "@buildbetter/ai/vercel";

// providerModel is a model from your configured AI SDK provider.
const model = withBuildBetter(providerModel, {
  client: buildbetter,
  ...session,
  onError: () => console.warn("BuildBetter capture failed"),
});

await generateText({
  model,
  prompt: "Why is this report blank?",
});

​

Delivery and retries

• Persist message IDs, sequences, revisions, and timestamps before sending. Reuse them for retries.
• Increase revision when an existing event changes. Keep its sequence and type unchanged.
• With the SDK, send new messages with explicit odd sequences. Do not mix raw HTTP event numbering with SDK numbering in one session.
• Send status: "ended" or "abandoned" when the conversation ends. Include at least one event, such as a replay of the final message.
• Await delivery before the process exits. Use a durable server queue when delivery must survive request or process failures.
• Direct SDK methods throw on failure. They do not provide a durable queue or automatic retries. Retry transient failures with bounded backoff and stable event data.
• The SDK batches requests and truncates oversized visible text. The HTTP limits are 500 events, 2 MiB per request, and 256 KiB per event.

​

Confirm the integration

1. Send a synthetic conversation with a unique session ID and a known surface.
2. Confirm the session appears in Library → Agent Chats in the intended workspace.
3. Send negative feedback on its assistant response. Confirm the rating and message link.
4. Retry the unchanged payload. Confirm the API reports deduplicated events instead of a second conversation.
5. Check access with an account outside the application’s allowed users.