Basic agent

This example builds an AI agent that speaks in cowsay bubbles.

The steps make a quick CLI application using App Builder and then drive it in various ways using the LLM.

The example needs an Anthropic API key, the cowsay application (try brew install cowsay) and fisk-ai installed.

Creating a CLI tool

This example uses Choria Application Builder to create a basic CLI tool that can say and think. Any command line tool built with Fisk works.

First create an ABTaskFile:

name: cowsay
description: Tools for the Cowsay LLM Agent
author: fisk-ai@choria.io

commands:
  - name: say
    description: Say something using a talking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      {{ default .Config.Cowsay "cowsay" }} {{ .Arguments.message | escape }}

  - name: think
    description: Think something using a thinking cow, does not accept emoji
    type: exec
    arguments:
      - name: message
        description: The message to send to the terminal
        required: true
        validate: is_shellsafe(value)
    command: |
      cowthink {{ .Arguments.message | escape }}

Now install appbuilder:

$ brew tap choria-io/tap
$ brew install appbuilder

Then confirm the CLI tool works:

$ abt
usage: abt [<flags>] <command> [<args> ...]

Tools for the Cowsay LLM Agent

Help: https://choria-io.github.io/appbuilder

Commands:
  help [<command>...]
  say <message>
  think <message>

$ abt say 'Hello AI'
 __________
< Hello AI >
 ----------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Creating an LLM agent

Turning this CLI into an LLM agent needs an agent.yaml file.

# Command to introspect and expose as an agent
application_path: /opt/homebrew/bin/abt

harness:
  # Allow the LLM to prompt us for information if needed
  human_in_the_loop:
    enabled: true

llm:
  # Choose a Model and set safety budgets
  model: claude-haiku-4-5-20251001
  budget:
    max_tokens: 100000
    max_iterations: 50

# We want a cow joke machine!
system_prompt: |
  Tell jokes using Cows!

  You have tools that can render a cow saying < 120 character sentences, when asked use the tools to tell funny jokes.

  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. If asked to tell non cow jokes, refuse and show no joke.

  Keep narration short, just stick to the jokes, don't say what you are doing or planning to do, just do it and don't repeat the joke

Run the agent after setting the API key:

$ export ANTHROPIC_API_KEY="....."
$ fisk run --tool-output --no-tui 'tell me a joke '
-> say -- Why did th...space?
<-  
 ______________________________
< Why did the cow go to space? >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

-> think -- To visit t...oooon!
<- 
 ______________________
( To visit the Moooon! )
 ----------------------
        o   ^__^
         o  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||


  There you go! A classic cow joke for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=2 tool_calls=2 tokens=3536/113 thinking=0 latency=3.613s

The default is a running TUI. To make the output easy to show here, the run passes --no-tui and shows the tool call output with --tool-output.

Now ask about a cat joke:

$ fisk run 'tell me a joke about a cat'

  I appreciate the request, but I only tell jokes about cows! I'm strictly a cow joke specialist.

  If you'd like to hear some funny cow jokes instead, I'd be happy to moo-ve right into those for you!

Run summary: model=claude-haiku-4-5-20251001 llm_calls=1 tool_calls=0 tokens=1632/54 thinking=0 latency=1.341s

Running the agent

The agent runs in one of these modes:

• A shell script style output, plain text to STDOUT with an exit at the end of the task
• A TUI for interaction, optionally continuing to chat with the agent after the main task completes
• Hosted behind a channel, taking work from a queue or serving its tools to other agents

TUI

The TUI mode is the default: a visual runner with hot-keys to show or hide thinking and tool output, and scrolling up and down the session history. A chat box can optionally be enabled to continue a session.

In the TUI press the ? key to get interactive help.

Chat after turn

In the TUI mode the chat bar opens once the prompt is processed, instead of exiting, for follow up questions related to the session. Every full-screen run works this way; --no-tui answers one prompt and exits, since it has no bar to open.

Type a follow-up and press Enter to send it; Ctrl-D ends the session, Ctrl-C aborts it. Up/Down recall this session’s earlier follow-ups. Alt-Enter (Option-Enter) moves to the next line rather than send. Ctrl-L empties the transcript on screen and leaves the conversation and any half-typed follow-up alone, where /clear does the opposite and drops the conversation while leaving the scrollback.

Shell mode

The TUI is turned off with --no-tui, and the system falls back to a simple terminal output format suitable for scripting.

The model’s prose is markdown: both the final answer and any mid-conversation updates. When stdout is a terminal it is rendered for readability with a style matched to the terminal background; when stdout is piped or redirected, the raw markdown is written so the result stays free of ANSI escape codes. Rendering can also be disabled with --no-color, or the standard NO_COLOR environment variable.

Output is separated by kind. Only the final answer goes to stdout; everything else goes to stderr: the commands being run, mid-conversation updates, a final run summary (LLM calls, tool calls, tokens, latency), and, with --thinking, the model’s reasoning (each line prefixed with a thought bubble). This keeps stdout safe to pipe into other tools.

One-shot runs

The common use case gives a system_prompt that describes the goals and approach (think of it as a one-file SKILL) and a user prompt that provides the question to solve.

The LLM runs through the prompt and, once it reaches the end of its turn, finishes processing, and the session cannot continue later. This resembles a shell utility.

HTTP debugging

As a debug or learning aid, all the HTTP requests can be logged to http-debug.log using the --http-debug flag.

Model settings

The agent.yaml sets which model runs the agent, the budget a run may spend, and whether the model exposes its reasoning. The Basic agent example shows these together. The full set of configuration fields is in the configuration reference.

Model

llm.model selects the model and is required. It accepts any model identifier the Anthropic API accepts:

llm:
  model: claude-sonnet-5

Larger models reason better on complex, long-horizon tasks; smaller models like Haiku are faster and cheaper for narrow ones. When the agent exposes ten or more tools it relies on the model’s server-side tool search, which recent models support and older ones (Claude Opus 4.1 and earlier and local models) do not. Set llm.no_tool_search to send every tool directly on an endpoint that does not implement tool search; when a large tool set cannot use it the run warns that all tools are being sent directly. The configuration reference lists the known models and their trade-offs.

Budget

llm.budget limits the agent loop so it cannot run without end:

llm:
  budget:
    max_tokens: 500000
    max_iterations: 50
    call_timeout: 120s

The two caps have different scopes. max_iterations applies to a single turn, and every turn of a conversation gets the same allowance. max_tokens applies to the whole conversation, so every turn draws on one allowance. Start a new conversation to get a fresh one.

When a turn reaches the iteration cap, it stops, says so, and you can carry on with another prompt. When a conversation reaches its token cap, it is finished: the next prompt is refused before it runs. Start a new conversation, or raise llm.budget.max_tokens on the machine running the agent.

max_tokens counts tokens, not money. It adds up the uncached input, the output, and both prompt-cache tiers. A cache read counts the same as an uncached input token here even though it costs a fraction as much, so two conversations with the same token count can cost very different amounts. Set this value against your own usage rather than treating it as a spending limit.

Thinking

Extended thinking lets the model expose its reasoning before it answers. Some providers call this reasoning rather than thinking; it is the same setting.

llm:
  thinking:
    enabled: true

Reasoning is never displayed unless asked for. --thinking (or THINKING=1) shows it, on fisk run and on fisk session show --transcript.

thinking=N on the run summary and in the TUI status bar reports the tokens spent reasoning, shown whether or not reasoning is displayed. It is part of the output half of tokens=in/out, not extra.

Terminal UI

These harness settings govern the full-screen UI for an agent, independent of the per-run --no-tui flag:

harness:
  no_tui: true
  no_bell: true

• no_tui is a persistent off switch: the agent always uses the line-by-line output, even on an interactive terminal, and the command line cannot turn the UI back on. Use --no-tui instead for a one-off run.
• no_bell silences the terminal bell. By default the full-screen UI rings the bell each time a run blocks on an approval gate or an ask_human_* prompt, so a waiting run is noticed even when unattended.

Both are negative switches and have no effect in the line UI.

Tool selection

Run the fisk info command to verify what tools the agent has access to:

$ fisk info
╭───────────────────┬────────┬───────────────────────────────────────────────────────┬──────╮
│ TOOL              │ SOURCE │ DESCRIPTION                                           │ TAGS │
├───────────────────┼────────┼───────────────────────────────────────────────────────┼──────┤
│ say               │ local  │ Say something using the configured command            │      │
│ think             │ local  │ Think something using a cow                           │      │
│ ask_human_confirm │ local  │ Ask the human operator a yes/no question at the te... │      │
│ ask_human_select  │ local  │ Ask the human operator to choose one option from a... │      │
│ ask_human_input   │ local  │ Ask the human operator to type a free-text value a... │      │
╰───────────────────┴────────┴───────────────────────────────────────────────────────┴──────╯

Prompt:

  Tell short jokes using Cows!
...

The output shows the say and think tools and some Human in the Loop tools. When the configuration sets a model, fisk info also prints a Model section first, listing the resolved model and provider, whether thinking is enabled, and how tool search will behave, so you can confirm the backend and feature gates without starting a run.

Application tags

The application can declare that the LLM never gets the think tool:

  - name: think
    description: Think something using a cow
    type: exec
    tags: [ ai:deny ]
    # ...

Adding the ai:deny tag to a command means Fisk AI never exposes that tool to the LLM. fisk info confirms the LLM only gets the say tool now.

Agent configuration

The agent.yaml can also include only certain tools:

include:
  tools:
    - ^say

Or exclude certain tools specifically:

exclude:
  tools:
    - ^think

This uses regular expressions over the tool name, and both can be used together. For example, include ^cow but exclude ^cow_think.

A tool’s name is its command path joined with underscores, so a nested command like cow think becomes the tool cow_think. Grouping commands and hidden commands are skipped and never become tools.

Tools can also be included or excluded by tag:

exclude:
  tags:
    - scope:system

This excludes any command that has the scope:system tag.

Global flags

A wrapped binary often has application-level global flags that apply to every subcommand. nats, for example, has --context to select a stored connection profile, alongside sensitive globals such as --user and --password. By default none of these are exposed to the model. global_flags is an allowlist of the globals you want the model to be able to set per command:

global_flags:
  - context

Each named global becomes an argument on every leaf command tool, so the model can run nats stream ls against a chosen context without you hard-wiring one. Names are the long flag name, with or without the leading dashes, and are validated against the binary’s real global flags at load; a name matching none is an error. Hidden and framework flags (like --help) cannot be exposed, and a global that clashes with a command’s own flag or argument is skipped for that command. A global the application marks required is always exposed, whether or not it is listed, since the command cannot run without it.

Run fisk info to see which globals a binary exposes; it lists the application’s global flags and marks the ones you have allowlisted.

Command tags

Fisk commands can carry tags, set in their fisk definition (or, for App Builder applications, in YAML). Tags can be referenced by the include/exclude rules to select commands by group, and the ai: prefix is reserved for the tags fisk interprets. The full vocabulary is listed under Command tags in the Reference guide; the tags that control how a command is exposed to the model are:

The behavior tags (ai:read_only, ai:destructive, ai:additive, ai:idempotent) describe what a command does rather than controlling it. They reach the model and, over MCP, the client; they gate nothing.

A tag under the ai: prefix that fisk does not recognize does nothing, so it is reported as a warning at startup and by fisk info.

ai:deny is the reliable way to keep a command the agent should never call out of reach, since it applies before any include/exclude rule. ai:no_defer keeps the handful of commands the model needs on most requests immediately available rather than discoverable only through tool search.

ai:confirm gates a command behind the operator’s explicit permission. When the model calls a command tagged ai:confirm, fisk pauses before running it and prompts the operator at the terminal, showing the resolved command line with its arguments, and offers three choices: run it once, run it and stop asking for that command for the rest of the conversation, or decline. Declining returns an authoritative result to the model (the command is not run and the model is told the decision is final), so it stops rather than working around the refusal. An “allow for the conversation” answer is remembered by command, regardless of its arguments: once you bless stream rm, every later stream rm call runs without asking again, so reserve that choice for a command you trust the agent to repeat.

The conversation records the answer, so continuing it honors the answer rather than asking again, and fisk session show lists what it holds. They are dropped by /clear and by a --force resume across a changed configuration, and a resume with no terminal attached declines a gated command rather than honoring one. The prompt is rendered on stderr (so a piped final answer stays clean), the displayed command line is stripped of terminal control sequences so model-supplied argument values cannot spoof what you see, and it denies by default: no interactive terminal, or a prompt that cannot be shown, declines rather than runs. An interrupt or an end-of-input at the prompt ends the run rather than declining, since the operator did not answer; the conversation stays continuable and asks again. Unlike human_in_the_loop, the tag is always active: there is no configuration flag to enable it.

The same gate can be extended to other tags with the harness.confirm_tags configuration key: any tag listed there gates its commands exactly as ai:confirm does, which lets an operator require confirmation for a tag the application already uses (for example ai:destructive, or an application’s own impact:rw) without editing the application. It is additive to the always-on ai:confirm tag and matching is exact rather than a regex. A confirm_tags entry that matches no loaded command is reported as a warning at startup, since a typo would otherwise leave a command ungated. The approval prompt names the tag that gated the command, so you can tell why you are being asked. Run fisk info to see each command’s tags and which commands a run would gate. Like ai:confirm, a confirm_tags tag gates both the agent loop and MCP, where it is requested through elicitation.

Any other tags are free-form: they have no built-in meaning to fisk but can be matched by the tags field of an include or exclude rule.

All of a command’s tags, reserved and free-form alike, are also included in the tool description fisk sends the model, as a trailing Tags: ... line, in both the agent and over MCP. This lets your prompt reference them, for example “always use ask_human_confirm before running any command tagged impact:rw”. The human-facing fisk info listing keeps the plain description.

Session snapshots

Every run is a conversation, and every conversation is journaled. You do not turn this on. Leave a run and continue it later, in a fresh process or on another machine, using the id it prints when it ends.

Continuing a conversation

Ask something. fisk prints the id of the conversation when the run ends:

$ fisk run "report on the ORDERS stream"

Continue it by that id. No prompt is given, since the conversation is restored from the journal; passing one is an error:

$ fisk run --resume t-3f2a9c...

fisk reads the conversation back before it goes on, so you continue in context rather than from a blank screen.

Against an agent somewhere else, see remote agents, the journal is on the worker rather than here, so --resume takes the conversation token instead of the id. fisk session show on the worker prints it.

Chat sessions

Every full-screen run is a durable, resumable conversation.

Each turn is journaled, so the whole conversation survives leaving, a stop or a crash. Press Ctrl-D to leave the input bar when you are finished for now; the status bar reads ctrl-d done. This does not end the conversation. fisk prints how to continue it as it exits. Ctrl-C asks the current turn to stop at its next safe point. The conversation is kept either way.

Resuming reads the conversation back into the viewport before the input bar opens, so you continue in context rather than from a blank screen. Because the bar needs a real terminal, a conversation can only be continued in the full-screen UI, not with --no-tui or over a pipe, where a run answers one prompt. A conversation has no “completed” state; remove it with session rm once it is no longer needed.

Stopping

The first Ctrl-C, or a SIGTERM, asks the run to stop where the conversation can be continued: the current step finishes, the turn is journaled, and fisk prints how to continue it. A second gives up on the run and leaves.

Both keep the conversation. The difference is that the first lets the turn reach a safe point, so the work it had already done is recorded rather than lost part way.

Durability

A session is journaled event by event as the run proceeds: each model turn and each tool result is recorded as it happens.

• A clean suspend is exactly-once. Nothing runs after the last recorded event, so a resume never repeats a tool call or an LLM call.
• A crash resumes from the last recorded event, so at most one tool call is repeated. A tool whose side effect completed but whose result was not yet recorded runs again on resume, since fisk cannot make an external side effect idempotent. Already-recorded turns and results are never replayed.

Resume a session against the same agent configuration it started with. A session can be resumed from anywhere, including a machine that no longer has the original agent.yaml, so care is required: continuing a conversation against a different model, tool set, or system prompt can make the replayed transcript incoherent. fisk fingerprints the configuration when the conversation started and refuses to continue it when that no longer matches, naming what changed. --force overrides it, except for the provider: a session started against one llm.provider can never be resumed against another. A session that already completed cannot be resumed.

Managing sessions

A suspended or completed session is kept until it is removed. List, inspect, and remove sessions with the session subcommands:

fisk session ls
fisk session show <id>
fisk session show <id> --transcript
fisk session rm <id>

session ls lists each session with its status, model, and prompt. session show prints a session’s counters and status; --transcript shows the full conversation (prompt, thinking, narration, tool calls, and tool output). On an interactive terminal --transcript opens the full-screen viewer with thinking and tool output folded, which z and Z expand; --no-tui/NO_TUI prints it as line output instead. session rm deletes a session.

Answering a deferred tool call

A tool can report that its answer arrives later rather than now. The run then suspends, releasing the process, and resumes once the answer exists. session show lists what such a session is waiting on under Waiting on, giving the tool_use id, the tool, and whatever the tool said it is waiting for.

The answer travels on a request carrying the conversation’s token, described in Answering after the run ended. The tool is never called again: it already started the work, which is why it deferred.

No tool that ships with fisk defers; the mechanism is for tools a Go program registers through agent.Options.CustomTools.

These commands read the file backend under --state-dir by default. To inspect sessions in a configured backend, a jetstream stream or a file directory named in the config, pass that config with --config:

fisk session ls --config agent.yaml
fisk session show <id> --config agent.yaml

Where a session is journaled is configurable through harness.sessions, which mirrors the shape of harness.memory. Two backends ship: file (the default) and jetstream Version0.0.3. The block is optional; leaving it out keeps the file backend under the XDG state directory.

fisk info shows a Sessions section with the resolved backend and, for the jetstream backend, the stream and NATS context, so you can confirm where sessions are stored without starting a run.

File backend

The file backend keeps each session as a JSON-lines journal under a directory. Sessions are stored under the XDG state directory, $XDG_STATE_HOME/fisk-ai/runs, defaulting to ~/.local/state/fisk-ai/runs. Set options.directory to move it off the default XDG path:

harness:
  sessions:
    backend: file
    options:
      directory: /var/lib/fisk-ai/runs

--state-dir overrides options.directory for a single run or session command, so the flag always wins over the configured path. It applies only to the file backend: combining it with a non-file backend is an error rather than a silently ignored flag.

JetStream backend

The jetstream backend keeps sessions as messages on a NATS JetStream stream instead of on disk, so a run suspended on one machine resumes on another over a broker. It uses the connection from the configured nats_context, the same one memory and remote tools use, and binds to a stream that must already exist: the agent never creates it, so you own the stream’s retention policy.

nats_context: production

harness:
  sessions:
    backend: jetstream
    options:
      stream: FISK_SESSIONS

Create the stream first, subscribed to one wildcard subject and keeping a single message per subject so each run record is write-once:

nats --context production stream add FISK_SESSIONS \
  --subjects 'fisk.sessions.>' --max-msgs-per-subject=1 \
  --discard=new --discard-per-subject

The stream keeps messages forever by default, which suits sessions; do not set a max age or they would silently expire. The subject prefix (fisk.sessions above) is yours to choose; the backend derives it from the stream’s single wildcard subject when it binds, so it is not set in the config. The backend fails at run start, rather than degrading silently, if the stream does not exist or its configuration does not match this shape. Sessions are never namespaced by identity, so a run started by one agent is found by another reading the same stream; keep separate environments in separate streams.

Remote agents

--nats-context points a terminal at an agent somebody else is running rather than starting one in this process:

$ fisk run --nats-context production "how many streams are there"

identity in the configuration names which agent to talk to, and you must set it. A default or a name derived from the application binary is shared by every agent built the same way, so the run could reach any of them.

The worker calls the model, runs the tools and writes the journal. Flags that describe that work are refused rather than ignored: --api-key, --base-url, --trace, --http-debug, --verbose, --state-dir and --no-telemetry. Setting one of these through an environment variable is ignored without an error, since you did not type it.

MCP client

mcp_clients imports the tools of third-party MCP servers into an agent run, alongside the wrapped application’s commands, the built-ins and any remote tools. Each entry names one server and selects a transport by which of command and url it sets: command starts the server as a child process and speaks stdio to it, url reaches an already-running server over streamable HTTP. Setting both is an error, and so is setting neither. Stdio and streamable HTTP are the only transports, and an endpoint that speaks the older HTTP+SSE transport is not supported.

mcp_clients:
  - name: filesystem
    alias: fs
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /srv/data
    env:
      FS_STATE_DIR: ${HOME}/.cache/fs-mcp
    timeout: 30s
    include:
      tools:
        - ^read_
    exclude:
      tools:
        - ^read_media_

  - name: docs
    url: https://mcp.example.net/mcp
    headers:
      Authorization: Bearer ${DOCS_TOKEN}
    timeout: 15s

Every field is described in the configuration reference.

Two entries sharing a name is an error when the file is parsed, and so is two entries whose effective alias is the same, since that alias prefixes every tool they both expose.

Naming

Every imported tool is named <alias>_<tool>, always, where the alias defaults to the server name. remote_tools prefixes only on a clash. MCP servers use short generic tool names such as search and read, where a clash is the common case, and a name derived only from its own server does not move when another server’s tool list does.

A collision against a local tool, a remote tool or another server’s is still possible. At the start of a run it fails the run, naming the tools that collided. fisk info reports it and carries on. A tool arriving while a run is under way whose name is taken is left out and reported, and the run continues.

Variable references

env, headers and url values hold any number of ${VAR} references, each replaced by the value of that environment variable, so a credential lives in the variable rather than in the file. A value mixes literal text with references freely, as in Bearer ${DOCS_TOKEN} and ${HOME}/cache. A $NAME without braces is literal text and references nothing. command and args are literal throughout.

References resolve when a session connects, not when the file is parsed. Parsing checks their syntax and reads no variable, so a host holding none of the credentials still runs fisk info and fisk mcp against the file. A variable that is not set fails the connect, naming the variable and the server.

Some services authenticate in the endpoint rather than in a header, by query parameter as in https://mcp.example.net/mcp/?apiKey=${DOCS_TOKEN}, or by a path segment as in https://mcp.zapier.com/api/mcp/s/${ZAPIER_KEY}/mcp. url takes references for that reason.

What is printed

Whatever a url’s references resolved to is replaced by REDACTED wherever it appears in an error or warning about that server, the endpoint an SDK or HTTP error quotes included, as long as the resolved value is at least eight characters. A shorter one is never searched for, since replacing a string that short would blank the digits and words it matches all through an unrelated message. Every endpoint printed anywhere is also redacted on its structure: the userinfo before the host, the value of every query parameter, and the fragment. The scheme, host, port, path and parameter names stay, so an operator recognizes the entry from their own file, and a reference is shown as written so it names the variable rather than its value.

A stdio entry prints its command line, and each argument goes through the same URL redaction, so an npx -y mcp-remote https://host/sse?key=... bridge does not print its key.

Timeouts

timeout covers everything that happens for one server before the run starts, and it is applied twice: once around starting or reaching the server and the initialize handshake, and again around listing its tools. An entry that is slow at both steps takes up to twice the configured value, 60s at the default, before the run gives up on it. Unset it defaults to 30s.

Servers are connected one after another and listed one after another, so an entry that answers slowly or not at all delays every entry behind it by up to its own timeout. The timeout keeps that delay finite rather than preventing it: three entries that answer the handshake and then never return a tool list hold the run for 90 seconds at the default before it is refused.

A call to an imported tool is limited by harness.tool_timeout, like every other tool.

Trust posture

An imported MCP tool is never confirm-gated. ai:confirm and harness.confirm_tags reach the wrapped application’s commands, and the server applies no gate on its side either, so a call the model makes to an imported tool runs unapproved at both ends. include and exclude are therefore the only control an operator has over what a third party’s server can do in a run.

An imported MCP tool is never served on. Neither fisk mcp nor the a2a tool endpoint advertises one to its own clients, whatever expose.agent.tools selects: serving it would re-advertise a third party’s tool under this agent’s identity, and a client cannot tell which of the tools it is offered came from where.

A stdio server is a program of someone else’s choosing running as the operator’s user. It gets this process’s environment with the credential variables removed, the same scrub a command tool’s subprocess gets, and the entry’s env applied on top.

Failures and a moving tool set

A server that cannot be started, reached or listed fails the run, since the prompt may depend on tools that are not there. A tool the run cannot use, one with no description or a schema whose root is not an object, is skipped with a reason and the run continues on the rest.

A server can tell a live session that its tool list changed. The run re-lists that server, applies the entry’s filters and names the survivors, and the model sees the new set on its next call. A tool batch already dispatched runs against the set it was dispatched with, and no other server’s tools move.

Seeing what a server offers

fisk info connects every configured server and prints an MCP clients section: where each is reached and over which transport, how long it took to answer, how many tools it advertised, how many the filters kept, the name each was imported under, and any tool left out with the reason. Discovery there is best-effort, so a server that is down is reported rather than failing the command. Its imported tools appear in the tool table with the alias in the Source column.

fisk serve connects the configured servers once at startup and shares those sessions across every run it hosts, so a long-lived worker is not starting and stopping a stdio child around each job. A server that cannot be reached stops the worker from starting, and the startup banner names the servers every hosted run imports from. Those runs share the server’s working directory, its authentication and its rate limits.

Human in the loop

When enabled, fisk gives the model built-in tools to ask the operator a question at the terminal and wait for the answer. They are off by default and only available when running the agent:

harness:
  human_in_the_loop:
    enabled: true

Enabling it offers these tools:

• ask_human_confirm - a yes/no question. Returns {"confirmed": true} or {"confirmed": false}
• ask_human_select - choose one of a list of options the model provides. Returns {"selected": "<option>"}, or {"selected": null} if no choice was made
• ask_human_input - a free-text value, optionally pre-filled with a default the operator can accept or edit. Returns {"value": "<text>"}, or {"value": null} if none was given

Optional communication from the agent

The model decides when to call the HITL tools, shaped through the prompt. They suit decisions the model should not make alone: confirming a destructive action, choosing between options that depend on operator intent, or supplying a value it cannot derive. The question is rendered on the terminal (stderr, so a piped final answer stays clean), and the model-supplied text is stripped of terminal control sequences first so it cannot spoof what is shown. Each tool denies by default: with no terminal attached the call returns a negative answer (no confirmation, no selection, no value) and a reason rather than hanging on a prompt no one can answer, and they are never exposed over MCP, where there is no operator. Tool calls within a turn run one at a time, so a prompt has the terminal to itself.

If you interrupt a question, or close the input, fisk does not treat that as a reply. The run stops there and the conversation is kept, and when you continue it the same question is asked again. No answer is recorded, so a run you interrupt never carries a decision you did not make.

Required tool use confirmations

These mechanisms put a human in the loop:

• human_in_the_loop (a configuration flag) lets the model ask its own question through a fisk-provided ask_human_* tool, with no application command involved. The human answers a question the model chose to ask.
• ai:confirm (a command tag) lets the application author gate an ordinary, non-interactive command so the operator must approve it before it runs. The human is a checkpoint on a command the model wanted to run anyway; nothing about the command itself changes.

Reach for human_in_the_loop when the model should decide when to check in; reach for ai:confirm when a normal command should run only with the operator’s say-so, typically something destructive or irreversible. Command tags covers the tag in full.

Memory

Memory gives the model a small key/value store that persists across runs, so it can keep durable notes (a layout it worked out, a convention, the outcome of an investigation) and pick them up next time rather than rediscovering them. It is opt-in and agent-mode only; like the human-in-the-loop tools it is never exposed over MCP.

Enable it under harness.memory. The backend field selects where memories are kept; it defaults to file, so the minimal configuration is just:

harness:
  memory:
    enabled: true

When enabled the model is offered four tools: memory_list (keys and their descriptions), memory_read (one memory by key), memory_write (save a memory with a key, a one-line description, and a body), and memory_delete. A key uses letters, digits and ., _, = or - (no slashes or spaces), which keeps it valid both as a filename and as a NATS KV key. memory_write creates by default and refuses to overwrite an existing key unless called with overwrite: true, so the model does not silently clobber a note; the create still fails cleanly if two writers race for the same new key.

read_only: true serves memory_list and memory_read and withholds the other two, for a run that should use what earlier runs saved without changing it. The store itself is unaffected, so anything else writing to it still does.

At the start of a run the stored keys and descriptions are injected into the system prompt as an index so the model knows what it has saved; memory_list is the live view during the run. Turn the index off with no_index: true.

A memory body is capped at 64 KB and a store holds at most 1024 entries. Both limits are shared by every backend, and a write that would exceed them fails cleanly. The on-disk format is shared too, so a value written by one backend migrates to another unchanged.

fisk info shows a Memory section with the resolved backend and, for the jetstream backend, the bucket, NATS context and key prefix, so you can confirm where memory is stored without starting a run.

Two backends ship today: file (the default) and jetstream Version0.0.3.

File backend

The file backend keeps each memory as a markdown file named for its key under the configured directory, which defaults to memory/<identity>.

harness:
  memory:
    enabled: true
    backend: file
    options:
      directory: memory

A relative directory, including that default, resolves under the store base when a deployment sets one and against the working directory otherwise; an absolute directory is used as-is. The identity is the agent’s name, set with the identity configuration field and defaulting to the application binary’s base name; the configuration reference covers it in detail. Point two agents at the same directory and they share a memory; leave the default and each agent keeps its own.

JetStream backend

The jetstream backend keeps memories in a NATS JetStream KV bucket instead of on disk, so a fleet of agents can share durable memory over a broker. It uses the connection from the configured nats_context, the same one remote tools use, and binds to a bucket that must already exist: the agent never creates it, so you own the bucket’s durability policy.

nats_context: production

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory

Create the bucket first, without a TTL so memories do not silently expire and with a max value size that fits a full entry (the 64 KB body cap plus the small frontmatter header stored with it), up to 1024 entries:

nats --context production kv add agent-memory --history=1 --max-value-size=69600

The backend fails at run start, rather than degrading silently, if the bucket does not exist, has a TTL set, or caps values below that full-entry size.

By default each agent’s keys are namespaced under a prefix equal to its identity (stored as <identity>.<key>), mirroring the file backend’s per-identity directory so two agents pointed at one bucket do not collide. Set options.prefix to a shared value for agents that deliberately share memory, or to "" for a flat, unprefixed keyspace:

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory
      prefix: fleet-shared   # agents with the same prefix share memory; "" is flat

Read-before-update

The jetstream backend adds a safety guard the file backend cannot: an overwrite must follow a read of the current value, and is refused if the memory was not read or has changed since it was read. The model then reads the current value and retries. This is the same read-before-edit discipline that keeps an editor from clobbering a file it has not seen.

The read counts for the whole conversation rather than one turn. A memory read on Monday and edited on Friday in the same conversation is overwritten without a fresh read, as long as nothing else wrote to it in between; if something did, the write is refused and the model reads again before retrying. One conversation’s reads never authorize another’s overwrite.

The check uses the KV entry’s revision, which makes it an atomic compare-and-swap: when two agents share a bucket and both try to update the same memory, the second write is rejected rather than silently overwriting the first. The file backend’s last-writer-wins overwrite would quietly drop that change, so a shared or concurrent deployment wants this backend.

The guard is on by default. Set no_require_read_before_update: true to allow blind overwrites, matching the file backend’s behavior:

harness:
  memory:
    enabled: true
    backend: jetstream
    options:
      bucket: agent-memory
      no_require_read_before_update: true

We can use memory to ensure our agent never repeats jokes; change thesystem_prompt as follows:

harness:
  memory:
    enabled: true

system_prompt: |
  Tell short jokes using Cows!

  You have tools that can render a cow saying short sentences, when asked 
  use the tools to tell funny jokes.
  
  You tell cow jokes, no other kinds of jokes, strictly jokes about cows. 
  If asked to tell non cow jokes, refuse and show no joke.

  Do not use emoji, keep general narration short, just stick to the jokes

  Save the jokes you told to a single memory file with all the past jokes 
  and make sure you dont repeat jokes you previously told.

  Finish your turn by making a funny quip related to the joke or cows or similar

We will get a new joke every time - be ready to get some awful jokes after a while :)

Safety

When Fisk AI runs a command in a CLI tool it passes a slice of arguments to the exec system call. No shell is involved that can be escaped or influenced.

App Builder is often involved and calls shell scripts, so App Builder commands need to be written defensively.

• Use type hints on arguments for ints, floats and so on
• Use is_shellsafe(value) on string input arguments
• Use escaping when passing arguments to commands, for example {{ .Arguments.message | escape }}
• Tag commands with the various helper tags so the harness understands the intent
• Mark every mandatory argument as required

Fisk AI has no tools that can interact with arbitrary files on the system. The only way it interacts with the system is through the supplied tools or the Memory feature.

Every command the agent runs gets the same protections:

• Its output combines stdout and stderr, preserving order, and is capped at 64 KiB so a chatty command cannot flood the model’s context
• The ANTHROPIC_API_KEY is stripped from its environment, so a tool can never read the agent’s own credentials
• LLMFORMAT=1 is set, signalling fisk applications to render output suited to an LLM rather than a terminal

Local LLMs

Local LLM hosting tools like ollama, LM Studio and others support exposing an Anthropic-compatible API. Fisk AI can communicate with those tools.

To support a large number of tools, Fisk AI uses the Tool Search Tool, which these local runners do not support. When targeting a locally hosted model, the total tool count may need to stay around 15.

I set these environment variables before invoking fisk to access my local Anthropic API instead of reaching to the internet.

$ export ANTHROPIC_BASE_URL=http://localhost:1234
$ export ANTHROPIC_API_KEY=lmstudio

The base_url is validated only as a well-formed http or https URL naming a host, with no embedded userinfo credentials. Plain http is accepted for any host, since a local runner, a host gateway and a service on a private network all serve over it.