---
title: "agent()"
description: "Create and configure an XSAF agent with the fluent agent factory."
---

> Documentation Index
> Fetch the complete documentation index at: https://xsaf.ilha.build/llms.txt
> Use this file to discover all available pages before exploring further.

# agent()

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.

```ts
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

```ts
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()`](/xsaf/start) is called. Registering an agent with [`.delegate()`](/xsaf/delegate) seals that child automatically.

## Configuration

```ts
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()`](/xsaf/tool)           | Register a validated, model-visible tool.                    |
| [`.channel()`](/xsaf/channel)     | Add an inbound and outbound messaging channel.               |
| [`.mcp()`](/xsaf/mcp)             | Connect tools, resources, and prompts from an MCP v2 server. |
| [`.sandbox()`](/xsaf/sandbox)     | Set the execution boundary for executable tools.             |
| [`.memory()`](/xsaf/memory)       | Replace the session-history store.                           |
| [`.delegate()`](/xsaf/delegate)   | Expose a sealed child agent as a model-visible tool.         |
| [`.serve()`](/xsaf/serve)         | Mount XSAF's MCP endpoint on the agent's Hono app.           |
| [`.scheduler()`](/xsaf/scheduler) | Replace the scheduler driver.                                |
| [`.schedule()`](/xsaf/schedule)   | Register recurring prompts or delegated work.                |
| [`.on()`](/xsaf/on)               | Subscribe to typed lifecycle and execution events.           |
| [`.approve()`](/xsaf/approve)     | Register a privileged approval handler for sensitive tools.  |

## Runtime methods

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

The agent also exposes `app`, `channels`, `name`, and `description`. See [API Reference](/reference) for result types, driver contracts, configuration types, and events.

Source: https://xsaf.ilha.build/xsaf/index.mdx