Sai HTTP API

https://api.sai.simular.ai

curl https://api.sai.simular.ai/v1/agents/auth \
  -H "Authorization: Bearer sapi_your_api_key_here"

{ "ok": true, "userId": "abc123", "authType": "apiKey" }

import type { UIMessage } from "ai";

/**
 * Sai's custom data parts, keyed by the part name without its `data-`
 * prefix. Each is streamed as { type: "data-<key>", data, id? } and shows
 * up under that `type` in message.parts.
 *
 * Declared as a `type` (not `interface`) so it satisfies the AI SDK's
 * `UIDataTypes` (Record<string, unknown>) constraint on UIMessage.
 */
export type SaiDataParts = {
  /**
   * Informational status line. One arrives right after `start`, and one
   * carries the result of a message the server handled as a command.
   */
  status: {
    text: string;
  };
  /** Progress line from a running tool. */
  progress: {
    text: string;
    /** Tool that emitted the line, or "tool" when it can't be identified. */
    tool: string;
  };
  /**
   * The agent needs permission to continue. Resolve it with
   * POST /v1/agents/approve using `approvalId`; the stream stays open
   * and the agent resumes once you respond.
   */
  "approval-request": {
    approvalId: string;
    title: string;
    /** Why the approval is needed; "" when the agent gave no reason. */
    description: string;
    /** The agent's approval category. */
    approvalType:
      | "exec"
      | "action"
      | "browser_action"
      | "desktop_action"
      | "api_call"
      | "service_connect"
      | "service_auth"
      | "user_input"
      | "choice";
    /**
     * True for requests needing browser or form interaction — an OAuth
     * connection (`service_connect`, `service_auth`) or a credential form
     * (`user_input`). POST /approve can't resolve these; send the user to
     * the desktop app.
     */
    isLinkOnly: boolean;
    /** Whether "always" is an allowed response (non-dangerous `exec` only). */
    allowAlways: boolean;
  };
}

/** A fully-typed Sai message. No custom metadata, hence `never`. */
export type SaiUIMessage = UIMessage<never, SaiDataParts>;

const res = await fetch("https://api.sai.simular.ai/v1/agents/message", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    machineId: "m_1a2b",
    message: "list my unread emails",
  }),
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  const frames = buffer.split("\n\n");
  buffer = frames.pop() ?? ""; // keep the trailing partial frame

  for (const frame of frames) {
    const line = frame.split("\n").find((l) => l.startsWith("data:"));
    if (!line) continue; // ": keepalive" comment lines have no data:
    const payload = line.slice(5).trim();
    if (payload === "[DONE]") return;

    const event = JSON.parse(payload);
    switch (event.type) {
      case "text-delta":
        process.stdout.write(event.delta);
        break;
      case "data-status":
        console.error("·", event.data.text);
        break;
      case "data-approval-request":
        if (event.data.isLinkOnly) console.error("Finish this in the desktop app.");
        else await approve(event.data.approvalId); // POST /v1/agents/approve
        break;
      case "finish": // terminal — the turn succeeded
        console.error(`\n[${event.finishReason}]`);
        break;
      case "error": // terminal — the turn failed
        console.error(`\n[error] ${event.errorText}`);
        process.exitCode = 1;
        break;
    }
  }
}

import { readUIMessageStream, type InferUIMessageChunk } from "ai";
import type { SaiUIMessage } from "./sai";

// SSE response body -> ReadableStream of typed UI message chunks.
function toChunks(res: Response) {
  let buffer = "";
  return res.body!
    .pipeThrough(new TextDecoderStream())
    .pipeThrough(
      new TransformStream<string, InferUIMessageChunk<SaiUIMessage>>({
        transform(text, controller) {
          buffer += text;
          const frames = buffer.split("\n\n");
          buffer = frames.pop() ?? "";
          for (const frame of frames) {
            const line = frame.split("\n").find((l) => l.startsWith("data:"));
            if (!line) continue;
            const payload = line.slice(5).trim();
            if (payload && payload !== "[DONE]") {
              controller.enqueue(JSON.parse(payload));
            }
          }
        },
      }),
    );
}

const res = await fetch("https://api.sai.simular.ai/v1/agents/message", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ machineId: "m_1a2b", message: "list my unread emails" }),
});

for await (const message of readUIMessageStream<SaiUIMessage>({
  stream: toChunks(res),
})) {
  for (const part of message.parts) {
    // part.type and part.data are fully narrowed from SaiDataParts.
    if (part.type === "text") render(part.text);
    else if (part.type === "data-status") console.error(part.data.text);
    else if (part.type === "data-progress")
      console.error(`[${part.data.tool}] ${part.data.text}`);
    else if (part.type === "data-approval-request" && !part.data.isLinkOnly)
      void approve(part.data.approvalId);
  }
}

"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import type { SaiUIMessage } from "./sai";

const transport = new DefaultChatTransport<SaiUIMessage>({
  api: "https://api.sai.simular.ai/v1/agents/message",
  headers: { Authorization: `Bearer ${apiKey}` },
  // Map the outgoing body to what /v1/agents/message expects.
  prepareSendMessagesRequest({ messages }) {
    const last = messages[messages.length - 1];
    const message = last.parts
      .filter((p) => p.type === "text")
      .map((p) => p.text)
      .join("");
    return { body: { machineId: "m_1a2b", message } };
  },
});

export function Chat() {
  const { messages, sendMessage, status } = useChat<SaiUIMessage>({ transport });

  return (
    <>
      {messages.map((m) => (
        <div key={m.id}>
          {m.parts.map((part, i) => {
            switch (part.type) {
              case "text":
                return <span key={i}>{part.text}</span>;
              case "data-status":
              case "data-progress":
                return <em key={i}>{part.data.text}</em>;
              case "data-approval-request":
                return part.data.isLinkOnly ? (
                  <em key={i}>Finish “{part.data.title}” in the desktop app</em>
                ) : (
                  <button
                    key={i}
                    onClick={() => approve(part.data.approvalId, "yes")}
                  >
                    Approve: {part.data.title}
                  </button>
                );
              default:
                return null;
            }
          })}
        </div>
      ))}

      <button
        disabled={status !== "ready"}
        onClick={() => sendMessage({ text: "list my unread emails" })}
      >
        Send
      </button>
    </>
  );
}