Agents

An agent is an LLM loop you declare in the BRICKS Buttress server config. It runs inside the server process, uses local functions, MCP servers, and opt-in device tools as its tools, and keeps its conversation history in session files on disk. The primary consumer is automation: a local function or daemon calls context.agents.run(...) to add multi-step reasoning to a server-side workflow. An interactive CLI drives and inspects the same agents.

Agents are experimental. The [[agents]] and [agents_options] config keys, the /agents endpoints, the SSE event shape, and the context.agents API may change between releases without a deprecation window. The server prints this notice at startup. Pin your bricks-buttress version if you build on it, and re-read this page after upgrading.

Define an agent

Agents are off until the config declares at least one [[agents]] table:

[[agents]]
name = "ops-assistant"                            # unique; also the session scope key
model = "buttress/ggml-org/gpt-oss-20b-GGUF"      # provider/model-id, split on the FIRST slash
system_prompt = "You are an ops automation agent. Use the provided tools."
# system_prompt_file = "./prompts/ops.md"         # or a file; not both
tools = ["get-server-status", "restart-service"]  # local function names
# local_devices = false                           # opt in to the built-in device tools
# codemode = false                                # opt in to the codemode tool
max_turns = 30
# max_tokens_per_run = 200000
# temperature = 0.2                               # unrecognized keys pass through to generation

[agents.mcp_servers.github]                       # optional MCP servers
url = "https://api.githubcopilot.com/mcp/"
# optional = true

Key	Type	Default	Description
`name`	string	—	Required. Unique across the config, and the scope key for the agent’s sessions. Letters, digits, `-`, and `_`, up to 64 characters
`model`	string	—	Required. `provider/model-id`, split on the first slash. See Models
`system_prompt`	string	—	Inline system prompt
`system_prompt_file`	string	—	Path to a system prompt file; relative paths resolve against the config file, and `~` expands to the home directory. Mutually exclusive with `system_prompt`
`tools`	string[]	`[]`	Local function names, listed explicitly — there is no wildcard. See Tools
`local_devices`	boolean	`false`	Add the two built-in device tools. See Local devices
`codemode`	boolean	`false`	Add the `codemode` tool. See Codemode
`max_turns`	integer	`30`	Assistant↔tool round-trips per run
`max_tokens_per_run`	integer	unlimited	Per-run token budget
`[agents.mcp_servers.<name>]`	table	`{}`	MCP servers to add as tools. See MCP servers

Any key not listed above passes through to generation, so temperature, top_p, and friends work as written. Agent definitions are validated at startup, not on first run: an unknown buttress/ model, a missing prompt file, a malformed tool name, or a duplicate agent name stops the server with an error rather than silently dropping the agent.

Global options

[agents_options] applies to every agent:

[agents_options]
# sessions_dir = "./.buttress-agent/sessions"
# session_max_age = "30d"
# session_max_count = 500
# max_depth = 2
# allow_unauthenticated = false

Key	Type	Default	Description
`sessions_dir`	string	`"./.buttress-agent/sessions"`	Where session files live. Relative paths resolve against the config file, and `~` expands to the home directory
`session_max_age`	number or string	`"30d"`	Retention sweep by age, in ms or as a duration string. `0` disables
`session_max_count`	integer	`500`	Retention sweep by count, per agent. `0` disables
`max_depth`	integer	`2`	Cap on chained agent invocations — function → agent → function → agent
`allow_unauthenticated`	boolean	`false`	Serve `/agents` on an unbound server. See Security

Models

model is provider/model-id, split on the first slash — so the model id itself may contain slashes. buttress/<repo_id> targets a model this server already hosts. The id must match the repo_id of a configured ggml-llm or mlx-llm [[generators]] entry, and the server checks that at startup. Traffic reaches the generator through an in-process loopback — no socket, and no extra configuration. Enabling [openai_compat] is not required; that key still governs only the external HTTP route.

[[generators]]
type = "ggml-llm"

[generators.model]
repo_id = "ggml-org/gpt-oss-20b-GGUF"

[[agents]]
name = "ops-assistant"
model = "buttress/ggml-org/gpt-oss-20b-GGUF"

Any other prefix is a hosted provider — anthropic/…, openai/…, google/… — authenticated by that provider’s usual environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, …). Set it in [env] or in the process environment.

[env]
ANTHROPIC_API_KEY = "sk-ant-…"

[[agents]]
name = "reviewer"
model = "anthropic/claude-sonnet-5"

OAuth-based provider logins are not supported. A hosted provider needs an API key in the environment.

Tools

tools lists local function names explicitly. Each tool call runs through the normal functions executor, so a tool gets the same lazy reload, scratch directory, spawn tracking, and meta.timeout deadline it would get over HTTP or MCP — and the function’s meta.parameters JSON Schema is what the model sees. Aborting a run aborts its in-flight tool calls and the processes those calls spawned. A listed function that does not exist fails the run rather than letting a headless automation improvise around a missing capability.

MCP servers

[agents.mcp_servers.<name>] adds an MCP server’s tools alongside the local functions. Give each server exactly one of url (Streamable HTTP) or command (stdio):

[agents.mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
headers = { Authorization = "Bearer ghp_…" }

[agents.mcp_servers.local]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/srv/data"]
# env = { LOG_LEVEL = "debug" }
optional = true

MCP tools are exposed under server-qualified names — mcp__github__create_issue — so they cannot collide with local function names. Servers connect lazily on the first run that needs them, and a server that will not connect fails the run unless it is marked optional = true, in which case the agent runs without its tools. Set exposure to choose how a server’s tools reach the model, and tool_exposure to override it for single tools, keyed by exact tool name or a * pattern. An exact name wins over a pattern; among patterns, the first match wins.

[agents.mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
exposure = "codemode"
tool_exposure = { "delete_*" = "hidden" }

`exposure`	Effect
`direct`	Default. Each tool is declared to the model like a local function
`codemode`	Kept out of the model’s tool list. Codemode scripts search for the tools and call them. Requires `codemode = true` on the agent
`deferred`	Treated like `codemode`. Requires `codemode = true` on the agent
`hidden`	Unreachable, including from scripts

codemode or deferred on an agent without codemode = true stops the server at startup.

Local devices

local_devices = true gives one agent two built-in tools for reaching BRICKS devices on the LAN. They work independently of local functions and MCP servers — [functions] does not have to be enabled — and they are off until you opt in:

[[agents]]
name = "device-operator"
model = "anthropic/claude-sonnet-5"
local_devices = true

Do not add devices_scan or devtools to tools, which accepts local function names only. Changing local_devices takes effect on the next server start. devices_scan runs the same UDP and HTTP discovery as bricks devtools scan, on the Buttress host’s network rather than the caller’s, and also picks up local project previews relative to the config directory. Call it with {}, or narrow it:

Argument	Default	Description
`timeout`	`3000`	Discovery window in ms, 100–10000
`udpOnly`	`false`	Skip HTTP subnet probing
`verify`	`false`	Verify each discovered server over HTTP
`project`	`true`	Include local project previews
`port`	`19851`	DevTools port to probe

devtools drives one device through the Chrome DevTools Protocol. Every call takes an action and an address — a hostname or IP without the port, IPv6 in brackets — plus port (default 19851):

`action`	Arguments and result
`screenshot`	Returns the screen as an inline image
`tree`	`depth` — brick tree depth, default `3`, `-1` for the whole tree
`query`	`selector` — every matching brick
`tap`	`x`, `y` in BRICKS layout units, not pixels — read the tree first
`key`	`key`, such as `Enter`
`input`	`subspaceId`, `brickId`, `text`; an empty string clears the field
`console`	`duration` — capture window in ms, 0–10000, default `2000`; returns retained and new entries
`evaluate`	`expression`, optional `awaitPromise` — evaluates JavaScript on the device
`storage`	Returns a storage overview
`cdp`	`method` and optional `params` — any other supported CDP request

Scan first, then address a device from the results:

{ "action": "tree", "address": "192.168.1.42", "port": 19851 }

Pass passcode or a workspace DevTools accessToken when the device requires one; otherwise the connection uses the credential the device advertises for Chrome Inspect. Buttress never reads the host’s BRICKS CLI login and never mints tokens of its own. Each call opens and closes its own CDP connection, and a device accepts one inspector at a time — so issue calls sequentially, and keep other DevTools clients off the device while an agent is working. Aborting a run closes any open connection; a scan already in flight finishes its bounded sweep before reporting the abort.

local_devices = true grants network discovery and device control, including arbitrary JavaScript evaluation on any reachable device the agent can authenticate to. It is neither read-only nor a network sandbox. Tool arguments and results — passcodes, access tokens, console output, and device data among them — enter the model’s context and the persisted session transcripts. Only enable it for agents and callers you trust.

Codemode

codemode = true adds a codemode tool to one agent. With it, the model writes a short JavaScript program that calls the agent’s other tools — local functions, MCP tools, and the local device tools — instead of calling them one at a time. It can run calls in parallel, chain one result into the next call, or filter a large result down before it reaches the context. Only what the script outputs goes back to the model.

[[agents]]
name = "issue-triage"
model = "anthropic/claude-sonnet-5"
codemode = true

Scripts run in a QuickJS sandbox with no file system, network, or timers of their own. Every action goes through the agent’s tools, so a script can reach nothing the agent could not already call. Scripts can also:

Find and call MCP tools that are kept out of the model’s tool list with exposure = "codemode". See MCP servers
Run classifier models with the agent’s provider credentials
Keep small values for later scripts in the same session

Changing codemode takes effect on the next server start.

Small local models can write poor scripts. Turn codemode on for agents that run on capable models.

Run an agent

From a local function

This is the primary surface. Every configured agent is reachable through context.agents:

export const meta = {
  description: 'Ask the ops agent to investigate a service.',
  timeout: '10m',
}

export default async ({ service }: { service: string }, context: ButtressFunctionContext) => {
  const result = await context.agents.run('ops-assistant', {
    prompt: `Investigate the '${service}' service and fix it if needed.`,
  })
  return { conclusion: result.content, sessionId: result.sessionId }
}

Member	What it does
`agents.run(name, options)`	Run a prompt to completion → `AgentRunResult`. Options: `prompt`, `sessionId`, `fork`, `onEvent`, `onSession`
`agents.list()`	Configured agent names
`agents.sessions(name, { limit? })`	Newest-first session summaries

A run inherits the calling function’s lifetime and deadline: context.signal — the function’s meta.timeout expiring, or the caller disconnecting — aborts the run and its tool calls. Agent loops are slower than ordinary function calls, so raise meta.timeout, or move the work into a daemon, which has no deadline. Agent progress mirrors onto the function’s own SSE stream as agent events, so an SSE caller of the function sees the agent working without extra wiring. Every method throws when the server has no [[agents]] configured.

Over HTTP

Endpoint	Purpose
`GET /agents`	Configured agent names → `{ "agents": [...] }`
`POST /agents/<name>/run`	Run a prompt. Body is `{ prompt, sessionId?, fork? }`; the response is `{ "result": … }`
`POST /agents/<name>/run?stream=1`	The same call as SSE — `agent` progress events, then the result
`GET /agents/<name>/sessions`	Newest-first session summaries. `?limit=` caps the list
`GET /agents/<name>/sessions/<id>`	Full transcript → `{ "messages": [...] }`
`POST /agents/<name>/sessions/<id>/abort`	Abort the session’s active run → `{ "aborted": true \| false }`

curl -X POST http://localhost:2080/agents/ops-assistant/run \
  -H 'Authorization: Bearer <workspace-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Which services are unhealthy?"}'

A failed run returns AGENT_RUN_FAILED with the sessionId attached, so the transcript is still reachable. An aborted run answers 499; other failures answer 500. Unknown agents and sessions answer 404 NOT_FOUND. Streaming responses carry slimmed agent events: partial assistant messages and full tool results are omitted, because they would dwarf the stream. Fetch the transcript from the sessions endpoint when you need the complete record.

From the CLI

bricks-buttress agent is a streaming chat client for an agent on a running server. Point it at the same config the server uses and it finds the port and the local token itself:

bricks-buttress agent -c config.toml                                # list agents
bricks-buttress agent ops-assistant -c config.toml                  # chat
bricks-buttress agent ops-assistant --sessions -c config.toml       # list sessions
bricks-buttress agent ops-assistant --session <id> -c config.toml   # continue a session
bricks-buttress agent ops-assistant --fork <id> -c config.toml      # fork, then continue the fork

Option	Description
`-c, --config <path>`	Server config file — used to find the port and the local runtime token
`--url <url>`	Server base URL. Defaults to the config’s, else `http://127.0.0.1:2080`
`--token <token>`	Access token. Defaults to the config’s runtime token file
`--session <id>`	Continue an existing session
`--fork <id>`	Fork a session, then continue the fork
`--sessions`	List the agent’s sessions and exit

The chat streams text, thinking, and tool calls as they happen. In the chat, /exit quits, /new starts a fresh session, and Ctrl+C aborts the current run — a second Ctrl+C quits.

Run result

context.agents.run and POST /agents/<name>/run both resolve to:

Field	Description
`sessionId`	The session this run wrote to — pass it back to continue
`content`	The agent’s final answer
`reasoningContent`	The thinking text, when the model produced any
`usage`	`{ input, output, cacheRead, totalTurns }`, aggregated across the run
`stopReason`	Why the loop ended

stopReason is one of end_turn (the agent answered), max_turns, token_budget, aborted, or error. Treat anything but end_turn as an incomplete answer.

Sessions

Every run belongs to a session. Omit sessionId and the run starts a new one; pass it back to continue the conversation; add fork: true alongside it to branch into a fresh session that records its parent, leaving the original untouched. Sessions are JSONL files under sessions_dir, scoped by agent name, and written as the run streams — so a run that was aborted or timed out still leaves a continuable transcript. Runs on the same session queue behind each other; different sessions run in parallel. A retention sweep prunes sessions by age (session_max_age) and count (session_max_count, per agent).

Sessions are scoped by the agent’s name. Renaming an agent orphans its existing sessions — they stay on disk but the renamed agent will not list or continue them.

Security

/agents authenticates like the functions surface, not like the open inference endpoints:

A bound server requires a workspace access token. See workspace binding.
An unbound server rejects remote calls entirely, unless [agents_options] allow_unauthenticated = true.
Cross-site browser requests are always rejected.

At startup the server writes an ephemeral runtime token to a runtime-token file next to sessions_dir, with mode 0600. Same-host tools — the CLI above — read it and authenticate automatically, bound or not.

allow_unauthenticated = true lets anyone who can reach the port run every agent, and therefore every tool you gave it. Only do this on a trusted network.

Agent definitions are trusted input, exactly like the config file and function files. An agent is only as safe as the functions, MCP servers, and device access you hand it: a model is choosing when to call them, so give an agent the narrowest tool list that does its job. A bound server cannot mint workspace tokens for itself — the loopback to buttress/ models is authorized by an internal token instead, and never by workspace credentials.

Samples

The server package ships config/function-samples/run-agent.ts, a local function that drives a configured agent and returns its conclusion, session id, turn count, and stop reason. config/sample.toml carries a commented [[agents]] block. See local functions for the rest of the samples.

Overview

Guides

Changelog

Define an agent

Global options

Models

Tools

MCP servers

Local devices

Codemode

Run an agent

From a local function

Over HTTP

From the CLI

Run result

Sessions

Security

Samples

Next steps

Local functions

Configuration

​Define an agent

​Global options

​Models

​Tools

​MCP servers

​Local devices

​Codemode

​Run an agent

​From a local function

​Over HTTP

​From the CLI

​Run result

​Sessions

​Security

​Samples

​Next steps

Local functions

Configuration

Define an agent

Global options

Models

Tools

MCP servers

Local devices

Codemode

Run an agent

From a local function

Over HTTP

From the CLI

Run result

Sessions

Security

Samples

Next steps