Getting started

This quickstart creates a complete agent with XSAF’s public mock adapters. It performs no network request and opens no listening socket.

Install XSAF

npm i @xsaf/agent

yarn add @xsaf/agent

pnpm add @xsaf/agent

bun add @xsaf/agent

XSAF is ESM-only. Node.js 20 or newer is the declared Node runtime.

Create a mock agent

src/agent.tsts

import { agent } from "@xsaf/agent";
import mockChannel from "@xsaf/agent/channel/mock";
import mockModel from "@xsaf/agent/model/mock";

const model = mockModel({
  response(request) {
    const prompt = request.messages.findLast((message) => message.role === "user")?.content;

    return { text: `Mock assistant received: ${prompt ?? ""}` };
  },
});

const channel = mockChannel();

const bot = agent({
  model,
  persona: "You are a deterministic test agent.",
  stream: false,
})
  .channel(channel)
  .serve({ path: "/mcp" });

await bot.start();

await channel.receive({
  sessionId: "demo",
  text: "hello xsaf",
});

console.log(channel.sent[0]?.payload);

await bot.stop();

The mock model is fully configured, so tests need no placeholder endpoint or credentials.

Run the file

node src/agent.ts

Expected output:

Mock assistant received: hello xsaf

Invoke through Hono

Every agent owns a Hono app. Use app.request() in tests or wrap bot.fetch(request) for your runtime’s HTTP server:

const response = await bot.app.request("http://localhost/invoke", {
  method: "POST",
  headers: {
    host: "localhost",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    sessionId: "http-demo",
    prompt: "hello Hono",
  }),
});

console.log(await response.json());

POST /invoke collects a streamed model result before returning JSON. Use direct invocation or the HTTP channel when chunk-by-chunk delivery is required.

Use a real model

Configure the bundled xsAI model explicitly:

import xsai from "@xsaf/agent/model/xsai";

const bot = agent({
  model: xsai({
    model: "your-provider/model",
    baseURL: process.env.MODEL_BASE_URL!,
    apiKey: process.env.MODEL_API_KEY!,
  }),
  persona: "You are a concise assistant.",
});

Provider behavior and model identifiers are determined by the xsAI-compatible endpoint. Keep credentials outside source control.

Getting started

Invoke through Hono

Use a real model

Next steps