agent() | XSAF

Import the agent factory from @xsaf/agent. Calling agent() creates an XsafAgent; every configuration method returns that same agent so configuration reads as one chain.

agent(config: AgentConfig): XsafAgent

agent() returns the same public object used for configuration, delegation, startup, invocation, and shutdown. Configuration performs no I/O and remains mutable until the agent is started or registered as a delegate.

Usage

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

const bot = agent({
  name: "research_agent",
  description: "Researches focused technical questions",
  persona: "Be concise and cite uncertainty.",
  model: xsai({
    model: "openai/gpt-4.1-mini",
    baseURL: "https://api.openai.com/v1/",
    apiKey: process.env.OPENAI_API_KEY!,
  }),
  maxSteps: 3,
  stream: true,
  reasoning: "low",
})
  .memory(memory)
  .sandbox(sandbox)
  .tool(searchTool)
  .channel(channel)
  .serve();

await bot.start();

Configuration is inert until .start() is called. Registering an agent with .delegate() seals that child automatically.

Configuration

interface AgentConfig {
  name?: string;
  description?: string;
  model: XsafModel;
  persona: string;
  maxSteps?: number;
  stream?: boolean;
  reasoning?: "none" | "low" | "high";
}

model is a configured dependency, so custom and mock models do not need placeholder URLs or credentials. persona must be nonblank. Names must use lowercase snake_case; descriptions must be nonblank when provided. maxSteps defaults to 3, stream to true, and reasoning to "none".

Use @xsaf/agent/model/mock for deterministic tests and @xsaf/agent/model/xsai for xsAI-compatible providers.

Fluent methods

Method	Purpose
`agent()`	Create an agent and define its model, persona, and identity.
`.tool()`	Register a validated, model-visible tool.
`.channel()`	Add an inbound and outbound messaging channel.
`.mcp()`	Connect tools, resources, and prompts from an MCP v2 server.
`.sandbox()`	Set the execution boundary for executable tools.
`.memory()`	Replace the session-history store.
`.delegate()`	Expose a sealed child agent as a model-visible tool.
`.serve()`	Mount XSAF’s MCP endpoint on the agent’s Hono app.
`.scheduler()`	Replace the scheduler driver.
`.schedule()`	Register recurring prompts or delegated work.
`.on()`	Subscribe to typed lifecycle and execution events.
`.approve()`	Register a privileged approval handler for sensitive tools.

Runtime methods

Method	Purpose
`.start()`	Seal configuration and initialize resources.
`.invoke()`	Run a prompt through the unified request path.
`.ask()`	Request validated structured output.
`.fetch()`	Handle a web-standard request through Hono.
`.stop()`	Close resources in reverse order.

The agent also exposes app, channels, name, and description. See API Reference for result types, driver contracts, configuration types, and events.