@orkestrate/sdk

@orkestrate/sdk

Publisher HTTP handler for Orkestrate.

What you get: secret check, session id, caller model (BYOM), JSON wire.
What you own: chat history — same as any AI SDK app. Use sessionId as your chat key.

Install

npm install @orkestrate/sdk ai

Primitives (any framework)

import { verifyRequest, parseRequest, buildModel, respond } from "@orkestrate/sdk";

async function handler(request: Request) {
  verifyRequest(request, process.env.ORKESTRATE_SECRET!);
  const { action, sessionId, message, modelConfig, messages } =
    await parseRequest(request);

  switch (action) {
    case "ping":
      return respond.ok();
    case "end_session":
      return respond.ok();
    case "start_session":
    case "send_message": {
      const model = buildModel(modelConfig!);
      const reply = await runAgent({
        message: message!,
        model,
        sessionId: sessionId!,
        messages: messages!,
      });
      return respond.reply(reply);
    }
  }
}

Usage with AI SDK (convenience)

Same primitives, but createOrkestrateHandler wires them for you:

// app/api/orkestrate/route.ts
import { createOrkestrateHandler } from "@orkestrate/sdk";
import { generateText } from "ai";

export const { GET, POST } = createOrkestrateHandler({
  secret: process.env.ORKESTRATE_SECRET!,

  async onTurn({ message, model, messages, callerId }) {
    // messages is the full conversation — gateway handles storage
    const result = await generateText({ model, messages });
    return { reply: result.text };
  },
});

Wire (gateway → you)

Header	When
Authorization: Bearer <secret>	always on POST
X-Orkestrate-Action	start_session | send_message | end_session | ping
X-Orkestrate-Session-Id	open / send / close
X-Orkestrate-Model	open / send — base64url JSON { provider, model, apiKey, baseURL? }
X-Orkestrate-Caller-Id	optional

Body open/send: { "message": "...", "messages": [{ role, content }, ...] }
Success: { "reply": "..." } or { "ok": true }

Session ids are minted by Orkestrate. You never invent them for this path.

Error codes

Code	HTTP	Meaning
UNAUTHORIZED	401	Bad or missing Authorization header
BAD_REQUEST	400	Missing header, invalid body, bad model config
MODEL_ERROR	400	buildModel rejected the config (e.g. unknown provider)
SESSION_NOT_FOUND	500	Session id does not exist
SESSION_EXPIRED	500	Session has expired (idle or hard TTL)
SESSION_STALE	500	Session data is stale
CONFLICT	500	Concurrent operation on the same session
LIMIT_EXCEEDED	500	Turn limit or rate limit hit
INTERNAL	500	onTurn threw or returned an empty reply

Notes

• ai peer dependency: npm install @orkestrate/sdk ai if you use createOrkestrateHandler or call generateText. If you only use the primitives, you can ignore the peer dep warning — ai is not required at runtime.
• Streaming: V1 is text-turn only. respond.reply sends one string. Streaming (streamText, SSE) is not yet supported.
• custom provider: Assumes an OpenAI-compatible API (OpenAI SDK shape). For Ollama, vLLM, etc. that serve an OpenAI-compatible /chat/completions.
• Package size: @orkestrate/sdk depends on @ai-sdk/openai, @ai-sdk/anthropic, and @ai-sdk/google regardless of which provider you use.

Not included (on purpose)

• Built-in chat store
• MCP server
• OAuth / dashboard

License

MIT