Vercel AI SDK

@relayapp/vercel-ai turns a Vercel AI SDK backend into a Relay agent: it receives signed message.received webhooks and forwards streamText(...) output to Relay, which commits one canonical message. The plugin is a thin binding of the public HTTPS contract; every raw request it makes is documented in this site and remains available directly. Prerequisites: an agent and its Agent Token (Create and connect an agent) and a registered webhook with its signing secret (Webhooks).

The plugin lives in the public relaymessenger/relayapp workspace under integrations/vercel-ai and publishes to npm with the next relayapp release.

Quickstart

app/api/relay/route.ts

import { createRelay } from "@relayapp/vercel-ai";
import { streamText } from "ai";

const relay = createRelay({
  token: process.env.RELAY_AGENT_TOKEN!,
  webhookSecret: process.env.RELAY_WEBHOOK_SECRET!,
});

export const POST = relay.webhook(async ({ message, typing, reply }) => {
  await typing(true, "Thinking…");
  const result = streamText({
    model: "anthropic/claude-sonnet-5",
    prompt: message.parts.find((p) => p.type === "text")?.text ?? "",
  });
  await reply.stream(result.toUIMessageStreamResponse());
});

Mount the handler as the POST route your webhook registration points at. The handler works in any WinterCG runtime: Next.js route handlers, Cloudflare Workers, or behind a one-line Express or Hono adapter.

What the plugin enforces

Each row is a contract from these docs that the plugin implements for you.

Contract	Plugin behavior
Signature verification	Standard Webhooks HMAC over the exact raw body; unsigned or stale requests get `401`
At-least-once delivery	Per-instance `event_id` dedup window, recorded once your handler succeeds, so a failed handler gets its redelivery
Idempotent sends	Reply helpers derive `Idempotency-Key` values from the event id and call order; Relay replays the original send on any retry, from any instance
Group invocations	`invocation_id` from the event threads into every reply and typing call
Streaming	`reply.stream(...)` forwards the UI message stream to `POST /v1/messages?stream=true`; Relay commits exactly one message
Event compatibility	Unknown event types acknowledge `200` so new Relay events never break your route

Configuration

Option	Description	Default
`token`	Agent Token used for every send	required
`webhookSecret`	Signing secret from webhook registration	required for `webhook()`
`baseUrl`	API origin	`https://api.relayapp.im`
`toleranceSeconds`	Allowed `webhook-timestamp` skew	`300`
`onError`	Receives background handler failures	log-and-drop

On serverless platforms that support work after the response, pass the platform’s waitUntil as the second handler argument to acknowledge 202 immediately and keep generating: relay.webhook(handler) returns a function of (request, { waitUntil }). A thrown handler error returns 500, so Relay redelivers the event and the derived idempotency keys make the retry safe.

Handler context

Field	Contents
`message`	The full stored message with ordered `parts[]`
`event`	The complete event envelope
`invocationId`	Present for group deliveries; already threaded into helpers
`reply.text` / `reply.parts` / `reply.stream`	Idempotent sends bound to the conversation
`typing(started?, label?)`	Ephemeral typing indicator with an optional status line
`client`	The underlying `RelayClient` for anything beyond the helpers

Next steps

Streaming for the one-canonical-message contract behind reply.stream
Message components to send buttons, selects, and cards from reply.parts
Webhooks for registration, verification, and secret rotation
Text your coding agent for the local-computer integrations

Overview

Get started

Messages

Message components

Conversations

Webhooks & events

Reference

Vercel AI SDK

Quickstart

What the plugin enforces

Configuration

Handler context

Next steps

​Quickstart

​What the plugin enforces

​Configuration

​Handler context

​Next steps

Quickstart

What the plugin enforces

Configuration

Handler context

Next steps