sammy-sdk-client

Zero-dependency JavaScript client for the Sammy AI agent runtime. Works in any framework — React, Vue, Svelte, vanilla — and in any modern JavaScript runtime (browser, Node 18+, edge).

sammy-sdk-client is the framework-agnostic transport layer. It speaks to the chat endpoint your server exposes (typically backed by sammy-sdk's createSammyRouteHandler) and handles JSON requests, conversation IDs, and SSE streaming.

For React-specific helpers see sammy-sdk-react. For a drop-in chat widget see sammy-sdk-ui.

Install

npm install sammy-sdk-client

You'll also need a chat endpoint on your backend. The fastest way is createSammyRouteHandler from sammy-sdk:

// app/api/chat/route.ts (Next.js App Router)
import { Sammy, createSammyRouteHandler } from "sammy-sdk";
const sammy = new Sammy();
export const POST = createSammyRouteHandler(sammy);

Usage

import { SammyClient } from "sammy-sdk-client";

const client = new SammyClient({
  endpoint: "/api/chat",
  // Optional: custom headers (object or async function)
  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }),
});

// One-shot request/response (returns the full ChatResponse)
const reply = await client.chat("List all open deals");
console.log(reply.message);

// Streaming
const stream = client.stream("Summarise this week's pipeline");
stream
  .on("text", (chunk) => process.stdout.write(chunk))
  .on("tool_call", (call) => console.log("calling tool:", call.name))
  .on("tool_result", (r) => console.log("tool", r.name, "->", r.result.success))
  .on("agent_handoff", (h) => console.log("handed off to:", h.targetAgent))
  .on("done", (final) => console.log("\ntools used:", final.toolsUsed.length))
  .on("error", (err) => console.error(err));

Conversations

client.conversation(id?) gives you a scoped object that re-uses the same conversationId across calls — useful for chat threads.

const thread = client.conversation();
await thread.send("hi");
await thread.send("what did I just say?");

API surface

• new SammyClient(config)
• client.chat(message, options?) — Promise<ChatResponse> (one-shot JSON; the server must speak JSON for this path — createSammyRouteHandler does)
• client.stream(message, options?) — SammyStream (event emitter)
• client.conversation(id?) — convenience scope for a single conversation

SammyStream events:

| Event | Handler argument | |---|---| | text | string chunk to append to the assistant message | | tool_call | ToolCallEvent — { id, name, params } | | tool_result | ToolResultEvent — { id, name, result: { success, data?, error? } } | | agent_handoff | AgentHandoffEvent — { fromAgent, targetAgent, reason } (multi-agent only) | | done | the full ChatResponse | | error | a real Error instance |

All exported types — SammyClientConfig, ChatOptions, ChatResponse, SammyStream, ToolCallEvent, ToolResultEvent, ToolResult, ToolCallResult, AgentHandoffEvent, Attachment — are exported from the package root.

License

MIT