User guide

Agents

An agent is a named set of instructions, with its own tools and its own procedures. This is what one is made of and how to make one.

An agent is a named assistant with instructions of its own, a decision about what it may call, and — if you want them — procedures that belong to it alone. Start a chat with one and you get that behaviour instead of the default.

The case for making one is not novelty. It is that an assistant told how this particular job is done gets it right without being reminded, and an assistant told what it may not touch cannot get it wrong at all.

The Agents menu

Everything to do with agents starts from Agents in the menu bar. It lists the agents you have defined, then the built-in App Admin, then New Agent….

Three things worth knowing about that menu:

It rebuilds itself each time you open it, so an agent you have just added, renamed or removed is there without a restart.
With nothing defined it says (no agents defined) rather than showing a blank menu.
The one you have marked as your default is labelled (default).
App Admin is shipped rather than stored, so selecting it opens a notice rather than a form. There is nothing to edit.

Making one

Agents ▸ New Agent… opens the form. Two fields matter and the rest can wait.

Name: — what the agent is called in the menu, and how you start a chat with it.
Instructions (system prompt): — ordinary prose telling it how this job is done. Be concrete, say what to do rather than what to be, and include the exceptions: the cases where your procedure does not apply are usually the reason it gets applied wrongly.

A checkbox below them, Use this agent by default for new chats, decides whether new conversations start with it. OK saves.

An agent’s editor, open over a conversation. Two rows of tabs read Browser, Web permissions, Variables, Chat setup, General, Advanced, Tools, Approval and Skills, with General selected. Below them a Name field reading “Ticket desk”, and an Instructions (system prompt) box reading: work the Larkspur helpdesk queue; read a ticket before you answer about it, and say how long the requester has been waiting; never close a ticket without being asked to. A checkbox reads “Use this agent by default for new chats”, above OK and Cancel. — A saved agent, opened from the menu. The two fields that matter are the name and the instructions; everything else has a working default. The same form, empty, is what New Agent… opens.

The whole procedure, in order: open Agents in the menu bar; choose New Agent…; type a name; type the instructions; look at the Tools and Skills tabs; come back to General; press OK; open the Agents menu again and the agent is in it. This recording has no sound.

The tabs

The form carries nine, and you can ignore most of them for a first agent. The two that change what an agent is, rather than how it is configured, are these.

Tools — what it may call

Tool access: offers three settings: All tools, No tools, or Selected tools, with a tree of everything available beneath it.

This is the most under-used control in the application. An agent that only ever reads a queue and drafts replies does not need everything, and narrowing it is both a safety decision and a quality one — an assistant offered fewer wrong options picks the right one more often.

The agent’s editor on its Tools tab, over a conversation. A row reading “Tool access:” offers three choices — All tools, No tools, and Selected tools — with All tools chosen. Below it a tree headed “App” lists the application’s own tools with a checkbox beside each. — The Tools tab. Choosing Selected tools makes the tree beneath it live.

Skills — the procedures it carries

A skill written here belongs to this agent alone. Use it when the procedure is the agent: an agent you made for handling support queues should carry the triage procedure, and a general chat should not be told about it at all, not even as a line in a list.

The tab also lists the skills this agent inherits — yours, a plugin’s, the application’s — marked with where each came from and shown read-only. Skills is the article about all of that.

The agent’s editor on its Skills tab, over a conversation. A line reads “Skills only this agent’s chats can use, on top of the app’s.” The list shows one skill belonging to the agent, escalation, marked [always, announce]; then a divider reading “also available here”, under which larkspur-triage [127.0.0.1, announce] and reply-tone [always, full] are each marked “from you, app-wide”. Buttons read Add…, Edit… and Remove, above OK and Cancel. — The Skills tab. The first entry belongs to this agent; the ones under *also available here* are inherited, and each says where it came from and whether it applies everywhere or only on a matching page.

The rest

Advanced — the settings you reach for rarely.
Approval — what this agent may do without being asked. What that means is Approvals and permissions.
Browser and Web permissions — which pages its browser opens with, and what it may do on which sites. Site permissions are per agent as well as per site, which is why they are here.
Variables — values its instructions can refer to.
Chat setup — how a conversation with it starts.

Deleting an agent deletes its skills. If any of them are worth keeping, copy them out first, or move the procedure into your own skills where it is not tied to one agent’s life. Skills says where they live on disk.

What an agent does not change

An agent shapes behaviour and narrows capability. It does not widen anything: an agent cannot reach a site you have not granted, cannot call an operation the page does not publish, and cannot approve its own way past a confirmation. The instructions are a statement about how to work, not a permission.

Back to all user-guide articles.