Changelog

v1.8.0

Workflow orchestration for parallel agent runs

Stratus now includes first-class workflows for tasks where the orchestration should live in code: audits, migration sweeps, research fan-out, and verification loops.

import { runWorkflow, workflow, workflowTask } from "@usestratus/sdk/core";

const auditWorkflow = workflow({
  name: "parallel-audit",
  run: async (ctx, files: string[]) => {
    const findings = await ctx.phase(
      "review files",
      files.map((file) =>
        workflowTask({
          id: file,
          agent: reviewer,
          input: `Audit ${file}`,
        }),
      ),
      { concurrency: 8, failFast: false },
    );

    const report = await ctx.synthesize(
      synthesizer,
      findings.map((finding) => finding.output).join("\n\n"),
    );

    return report.output;
  },
});

const result = await runWorkflow(auditWorkflow, files);

Includes workflow(), workflowTask(), runWorkflow(), streamWorkflow(), workflow progress events, bounded concurrency, AbortSignal cancellation, usage/cost aggregation, failFast: false phases, and resumeFrom snapshots.

v1.7.0

Framework interop: AI SDK and Effect entrypoints

New: `@usestratus/sdk/ai-sdk`

Use Stratus agents in AI SDK-style chat applications without giving up the Stratus run loop.

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

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

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

Includes helpers for AI SDK UI/model message conversion, session snapshots, approval responses, UI message streams, tool set adapters, language model adapters, and OpenAI Agents-style stream events.

The SDK repo also includes bun run smoke:real-ai-sdk, a real-key smoke suite covering chat route streaming, tool approval/resume, the language model adapter, and OpenAI Agents-style stream projection. It uses OPENAI_API_KEY by default and switches to Azure createModel({ store: false }) when Azure env vars are present.

Updated: multimodal file IDs

ImageContentPart.image_url now accepts { file_id: string } as well as { url: string }, matching the Azure/OpenAI Responses image input shape. File parts continue to support { file_id: string }.

New: `@usestratus/sdk/effect`

Use Effect services, layers, and typed errors with Stratus tools and models.

import { Effect } from "effect";
import { effectTool, runEffect } from "@usestratus/sdk/effect";

const search = effectTool({
  name: "search",
  description: "Search documents",
  parameters: SearchParams,
  execute: (_context, params) => searchProgram(params),
});

const result = await Effect.runPromise(runEffect(agent, "Search the docs"));

Includes effectTool(), effectModel(), runEffect(), resumeRunEffect(), streamEffect(), and StratusEffectError.

v1.6.0

Azure-first agent parity: sandbox agents, MCP HTTP, and Azure Monitor tracing

New: `SandboxAgent`

Use a confined local workspace with built-in tools for file and command tasks:

import { SandboxAgent, run } from "@usestratus/sdk/core";

const agent = new SandboxAgent({
  name: "workspace-agent",
  model,
  sandbox: { root: "/tmp/stratus-workspace" },
});

const result = await run(agent, "Create README.md");

New: MCP Streamable HTTP and Azure auth

McpClient now supports stdio and Streamable HTTP transports, async headers, tool filtering, cached tool discovery, and name prefixes.

import { McpClient, azureMcpHeaders } from "@usestratus/sdk/core";

const client = new McpClient({
  transport: "streamable-http",
  url: "https://mcp.example.com",
  headers: azureMcpHeaders(tokenProvider),
  toolFilter: ["search"],
  namePrefix: "docs__",
});

New: Trace processors and Azure Monitor exporter

Register processors to export completed traces. The built-in Azure Monitor exporter sends stratus.trace and stratus.span events to Application Insights.

addTraceProcessor(createAzureMonitorTraceExporter());

Azure Responses updates

AzureResponsesModelConfig.defaultHeaders adds extra headers to every Responses API request.
Background Responses requests force store: true, matching Azure's requirement for background mode.
previous_response_id is preserved when background mode forces storage.

Typecheck and tooling

SDK typecheck now passes across source, tests, and examples.
Added ESLint and Prettier scripts for repo-wide checks and formatting.

v1.5.0

DX improvements: testing, createModel, validation, debug mode

New: `@usestratus/sdk/testing` entrypoint

Ship test utilities as a separate import so they stay out of production bundles.

import {
  createMockModel,
  textResponse,
  toolCallResponse,
} from "@usestratus/sdk/testing";

const model = createMockModel([
  toolCallResponse([{ name: "search", args: { q: "test" } }]),
  textResponse("Found 3 results"),
]);

const agent = new Agent({ name: "test", model, tools: [searchTool] });
const result = await run(agent, "Search for test");

createMockModel accepts { capture: true } to record every ModelRequest for assertions.

New: `createModel()` factory

Reads AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT from environment variables. Throws a StratusError with a specific message when a required value is missing.

import { createModel } from "@usestratus/sdk/azure";

const model = createModel(); // Responses API (default)
const model = createModel("chat-completions"); // explicit backend

New: `session.wait()`

One-call convenience that drains the stream and returns the result:

session.send("What's the weather?");
const result = await session.wait();

New: Agent construction validation

The Agent constructor now validates tools at construction time:

Duplicate tool names throw StratusError
timeout <= 0 throws StratusError
Empty description logs a console.warn

Use validateAgent(agent) for programmatic access to { errors, warnings }.

New: `{ debug: true }` mode

Log model calls, tool executions, and handoffs to stderr:

await run(agent, "Hello", { debug: true });
// [stratus:model] 2026-04-02T... request to assistant {"messages":2,"tools":1}
// [stratus:model] 2026-04-02T... response from assistant {"content":"Hi!"}

Also works on sessions: createSession({ model, debug: true }).

v1.4.0

Azure Responses API: compact, background tasks, CRUD, encrypted reasoning, MCP approval

New: Compact endpoint

Shrink a conversation's context window while preserving essential information:

const compacted = await model.compact({
  input: conversationItems,
});
const followUp = await model.getResponse({
  messages: [{ role: "user", content: "Continue" }],
  rawInputItems: compacted.output,
});

Also supports compact({ previousResponseId: "resp_..." }).

New: Background tasks

Run long-running requests asynchronously (designed for reasoning models like o3):

const bg = await model.createBackgroundResponse({ messages });
// Poll until done
let response = bg;
while (response.status !== "completed") {
  await new Promise((r) => setTimeout(r, 2000));
  response = await model.retrieveResponse(response.id);
}

Cancel with model.cancelResponse(id). Resume streaming with model.streamBackgroundResponse(id, { startingAfter }).

New: Retrieve, delete, list stored responses

const response = await model.retrieveResponse("resp_abc123");
const items = await model.listInputItems("resp_abc123");
await model.deleteResponse("resp_abc123");

New: Encrypted reasoning items

Preserve reasoning context across turns in stateless mode:

const result = await model.getResponse({
  messages: [{ role: "user", content: "Solve this" }],
  modelSettings: { include: ["reasoning.encrypted_content"] },
});
// Pass reasoning items back in next turn
const followUp = await model.getResponse({
  messages: [{ role: "user", content: "Continue" }],
  rawInputItems:
    result.outputItems?.filter((i) => i.type === "reasoning") ?? [],
});

New: MCP approval flow

Submit mcp_approval_response via rawInputItems when using remote MCP tools with approval:

const continued = await model.getResponse({
  messages,
  previousResponseId: result.responseId,
  rawInputItems: [
    {
      type: "mcp_approval_response",
      approve: true,
      approval_request_id: "mcpr_123",
    },
  ],
});

New: `rawInputItems` on ModelRequest

Append opaque items (compaction, encrypted reasoning, MCP approvals) to the Responses API input array.

New: `include` and `background` in ModelSettings

include: string[] — fields to include in response (e.g. ["reasoning.encrypted_content"])
background: boolean — run as async background task

v1.3.0

Azure feature parity: allowedTools, canUseTool, interrupt, audio, predicted output

allowedTools glob patterns on RunOptions to restrict available tools
canUseTool centralized permission callback
Graceful interrupt() on streaming runs
prediction (predicted output) in ModelSettings for Chat Completions
modalities and audio config for gpt-4o-audio models
dataSources for Azure On Your Data (RAG)

v1.2.0

Phase 6: Feature parity release

Tool timeout, isEnabled, handoff isEnabled/inputType/inputFilter
Run hooks (onAgentStart/End, onHandoff, onToolStart/End, onLlmStart/End)
Tool guardrails (input/output), guardrail results on RunResult
Error handlers for maxTurns, custom toolUseBehavior function
resetToolChoice, toolErrorFormatter, callModelInputFilter
fileSearchTool(), computerUseTool()
Hosted tool streaming events
toInputList() on RunResult

v1.1.0

Phase 5: Hosted tools and Responses API features

HostedTool type, AgentTool union, isHostedTool/isFunctionTool guards
Built-in tools: webSearchTool, codeInterpreterTool, mcpTool, imageGenerationTool
toolChoice fix for Responses API
previousResponseId/responseId tracking
AzureResponsesModelConfig.store

v1.0.0

Initial release

Agent + run() + stream() + tool() + structured output + handoffs + subagents + guardrails + hooks + tracing + sessions + cost tracking + AzureResponsesModel + AzureChatCompletionsModel.

On this page