AI SDK Interop

Stratus ships an @usestratus/sdk/ai-sdk entrypoint for applications that already use the AI SDK message and streaming shapes. It converts messages in both directions, streams Stratus events as AI SDK UI message chunks, exposes Stratus tools as AI SDK tool sets, and wraps a Stratus agent in a chat route response.

Use this entrypoint when your frontend speaks AI SDK UI messages but you want Stratus to own the agent loop: tools, approvals, handoffs, subagents, guardrails, sessions, tracing, and Azure model support.

Chat route

For a Next.js App Router endpoint, pass incoming AI SDK UI messages to createStratusChatResponse().

app/api/chat/route.ts

import { z } from "zod";
import { Agent, createModel, tool } from "@usestratus/sdk";
import {
  type AISDKUIMessage,
  createStratusChatResponse,
} from "@usestratus/sdk/ai-sdk";

const model = createModel();

const getWeather = tool({
  name: "get_weather",
  description: "Get the current weather for a city",
  parameters: z.object({ city: z.string() }),
  execute: async (_context, { city }) => `72F and sunny in ${city}`,
});

const agent = new Agent({
  name: "weather_assistant",
  instructions: "You are a concise weather assistant.",
  model,
  tools: [getWeather],
});

export async function POST(req: Request): Promise<Response> {
  const { messages }: { messages: AISDKUIMessage[] } = await req.json();

  return createStratusChatResponse({
    agent,
    messages,
  });
}

The response is a Server-Sent Events stream with the x-vercel-ai-ui-message-stream: v1 header. Text deltas, tool input, tool output, approval events, finish events, and raw Stratus stream events are emitted as AI SDK-compatible chunks.

Message conversion

Use fromAISDKMessages() when you need to call lower-level Stratus APIs directly.

convert-messages.ts

import { fromAISDKMessages } from "@usestratus/sdk/ai-sdk";
import { run } from "@usestratus/sdk/core";

const chatMessages = fromAISDKMessages(messages);
const result = await run(agent, chatMessages);

Use toAISDKUIMessages() to render saved Stratus history or a RunResult back into AI SDK UI messages.

to-ui-messages.ts

import { toAISDKUIMessages } from "@usestratus/sdk/ai-sdk";

const uiMessages = toAISDKUIMessages(session.save());

User file parts are converted to Stratus content parts. Image files become image_url parts; other files become file parts. Custom data-* UI parts are ignored unless you provide convertDataPart.

const chatMessages = fromAISDKMessages(messages, {
  convertDataPart: (part) =>
    part.type === "data-note"
      ? { type: "text", text: String(part.value ?? "") }
      : undefined,
});

Sessions

AI SDK message history can become a Stratus session snapshot.

session-from-ui.ts

import {
  resumeSessionFromAISDKMessages,
  toSessionSnapshotFromAISDKMessages,
} from "@usestratus/sdk/ai-sdk";

const snapshot = toSessionSnapshotFromAISDKMessages(messages, {
  id: "chat_123",
});

const session = resumeSessionFromAISDKMessages(messages, {
  model,
  instructions: "Continue the conversation.",
});

resumeSessionFromAISDKMessages() removes system messages from the saved snapshot and applies your session config instructions, so the session keeps durable conversation state without duplicating system prompts.

Tool approvals

When a Stratus run pauses for human approval, convert pending tool calls into AI SDK approval requests.

approvals.ts

import {
  approvalsFromAISDKMessages,
  resumeStratusChatResponse,
  toAISDKToolApprovalRequests,
} from "@usestratus/sdk/ai-sdk";
import { resumeRun } from "@usestratus/sdk/core";

const approvalRequests = toAISDKToolApprovalRequests(interrupted);
const approvals = approvalsFromAISDKMessages(
  messages,
  interrupted.pendingToolCalls,
);

const resumed = await resumeRun(interrupted, approvals);

For chat routes, resumeStratusChatResponse() reads approval responses from the AI SDK messages and returns another UI message stream response:

resume-route.ts

import {
  type AISDKUIMessage,
  resumeStratusChatResponse,
} from "@usestratus/sdk/ai-sdk";

export async function POST(req: Request): Promise<Response> {
  const { interruptedRunId, messages } = await req.json() as {
    interruptedRunId: string;
    messages: AISDKUIMessage[];
  };

  const interrupted = await loadInterruptedRun(interruptedRunId);

  return resumeStratusChatResponse({
    interrupted,
    messages,
  });
}

AI SDK tool parts with approval-responded, output-denied, or approval metadata are converted into Stratus ToolApproval objects.

Streaming helpers

If you already have a Stratus stream, convert it to AI SDK chunks or a stream response.

streaming.ts

import {
  createAISDKUIMessageStreamResponse,
  toAISDKUIMessageStream,
} from "@usestratus/sdk/ai-sdk";
import { stream } from "@usestratus/sdk/core";

const streamed = stream(agent, "Explain this result.");
const uiStream = toAISDKUIMessageStream(streamed.stream, {
  messageId: "msg_123",
});

return createAISDKUIMessageStreamResponse({ stream: uiStream });

toAISDKUIMessageChunks() is also available when you want the chunks as an async iterable instead of an SSE response.

AI SDK language model adapter

Use toAISDKLanguageModel() when you want a Stratus Model to satisfy the AI SDK language model interface.

language-model.ts

import { toAISDKLanguageModel } from "@usestratus/sdk/ai-sdk";

const languageModel = toAISDKLanguageModel(model, {
  provider: "stratus",
  modelId: "azure-gpt-5.2",
});

const generated = await languageModel.doGenerate({
  messages: [{ role: "user", content: "Reply in one sentence." }],
  maxOutputTokens: 256,
  reasoningEffort: "minimal",
});

This is useful for code that expects an AI SDK language model but should still route through your Stratus model implementation.

Tool set adapter

Convert Stratus function tools into an AI SDK-style tool set:

tool-set.ts

import { toAISDKToolSet } from "@usestratus/sdk/ai-sdk";

const tools = toAISDKToolSet([getWeather, lookupOrder], {
  userId: "user_123",
});

Hosted tools are not converted by toAISDKToolSet() because they are server-side model tools, not local function tools.

OpenAI Agents-style stream events

For consumers that expect OpenAI Agents-style stream event names, use toOpenAIAgentsStyleStreamEvents().

agents-style-events.ts

import { toOpenAIAgentsStyleStreamEvents } from "@usestratus/sdk/ai-sdk";

for await (const event of toOpenAIAgentsStyleStreamEvents(streamed.stream)) {
  console.log(event.type);
}

Raw Stratus stream events are preserved as raw_model_stream_event, while message output, tool calls, tool output, approvals, handoffs, and agent updates are projected into higher-level run item events.

Real API smoke scripts

The SDK repo includes real-key smoke scripts for the AI SDK interop surface:

OPENAI_API_KEY=sk-... bun run smoke:real-ai-sdk

The script runs:

Script	What it verifies
`examples/real-api/01-chat-response.ts`	`createStratusChatResponse()` produces an AI SDK UI message SSE stream
`examples/real-api/02-tool-approval.ts`	tool approval requests, AI SDK approval responses, and `resumeRun()`
`examples/real-api/03-model-adapter-and-agents-events.ts`	`toAISDKLanguageModel()` and OpenAI Agents-style stream event projection

By default the smoke helper uses OPENAI_API_KEY with the OpenAI Responses API, store: false, and gpt-5-nano. Override the model with STRATUS_REAL_MODEL or OPENAI_MODEL.

If AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT are present, the helper uses Stratus createModel({ store: false }) instead.

Exports

Export	Use
`fromAISDKMessages()`	Convert AI SDK UI/model messages to Stratus `ChatMessage[]`
`toAISDKUIMessages()`	Convert Stratus messages, snapshots, or results to AI SDK UI messages
`toSessionSnapshotFromAISDKMessages()`	Create a Stratus session snapshot from AI SDK messages
`resumeSessionFromAISDKMessages()`	Resume a Stratus session from AI SDK message history
`toAISDKUIMessage()`	Convert one `RunResult` or assistant message to a UI message
`toAISDKToolApprovalRequests()`	Convert pending tool calls to AI SDK approval request parts
`approvalsFromAISDKMessages()`	Read approval responses from AI SDK messages
`toAISDKUIMessageChunks()`	Convert Stratus stream events to AI SDK UI chunks
`toAISDKUIMessageStream()`	Convert Stratus stream events to a readable UI message chunk stream
`createAISDKUIMessageStreamResponse()`	Create an AI SDK UI message stream `Response`
`createStratusChatResponse()`	Run an agent and return an AI SDK UI message stream response
`resumeStratusChatResponse()`	Resume an interrupted run and return an AI SDK UI message stream response
`toAISDKToolSet()`	Convert Stratus function tools to an AI SDK tool set
`toAISDKLanguageModel()`	Wrap a Stratus `Model` as an AI SDK language model
`toOpenAIAgentsStyleStreamEvents()`	Project Stratus stream events into OpenAI Agents-style events

On this page