Ettore Di Giacinto
9e6d6520bd
The capabilities, role grants and pairing that a connector binding
stores now decide what a sender can make the agent do.
Authorize is one pure function: the capability must be in the owner's
ceiling for the binding and the sender must be on the allowlist. A
sensitive capability then needs a paired sender; roles never count for
it. Any other capability needs a pairing or a role that the owner
granted and that the kind lists. The default is no.
Each message gets a grant for its sender. A message that joins a
running turn narrows it to what both senders may do. The tool builder
offers a gated tool only for a held capability, and the tool checks
again when the model calls it, so a call that gets through is refused
with the reason. Today this covers propose_change (memory and profile
kinds), revert_change, the trigger tools, and files sent to the bot. A
chat worker gets the grant with the start request.
The capability gate that the trigger features ask is now answered by
Authorize, and the application sets it. Other features can add a
global switch with AddCapabilitySwitch.
Every use records an allow or deny row (time, binding, sender IDs,
roles, capability, result; no text or codes). GET
/api/chats/connectors/{id}/access returns the effective permissions
per kind of sender and the latest rows, for an add-on settings page.
A binding saved before this change has no capabilities, so its senders
lose these features until the owner enables them.
Assisted-by: Claude:claude-sonnet-5-5 go swag
2.8 KiB
+++ disableToc = false title = "Build your first agent" weight = 7 icon = "smart_toy" +++
A saved agent is a set of instructions and exact lists of what a chat may use. It ships inside LocalAI and is on by default. If LocalAI runs and a model is installed, you have everything you need.
Before you start: install a tool-calling model
An agent that uses tools needs a model that can call them. Open Models, install a model that lists tool calling, and check that it answers a plain chat first.
Make the agent
- Open Agents in the sidebar.
- Choose New agent. Give it a name and the instructions it should always follow, for example:
Answer in French. Cite the file you used. - Leave the lists empty for an agent that only talks. Add an MCP server of the model, an add-on, a collection or a skill to give it more. An empty list grants nothing: an agent never has more than you put in it.
- Optional: in Files, choose One folder and pick a folder, for example
/Projects/Acme, with Can read or Can read and change. Chats with the agent then see only that folder and their own chat folder, not the rest of your files. See One folder for an agent. - Save it.
Talk to it
On the Agents page, choose Chat on the agent's row and write a message. The chat uses the agent's model when it has one. If you remove something the agent lists, for example by deleting a collection, the chat still starts without it and tells the model what is missing.
Let it work by itself
Open Triggers and make a schedule, for example weekdays 09:00, with the agent and a prompt. Each run is an ordinary chat of yours, and the result arrives in your Inbox. Add a Telegram connector to talk to the agent from your phone.
If your agent will not run
- No model. An agent without a model needs one when you start the chat. A trigger or a connector needs an agent that names a model.
- A tool is missing. The chat lists what was unavailable at the start of the turn. Check that the MCP server is configured on the model, the add-on is enabled, and the collection or skill still exists.
- A server of the model is unreachable. An MCP server that does not answer makes its tools time out. Open the model's
mcp:configuration and test the server. - Folder missing. The agent's folder was deleted, or it was imported without a folder that exists here. The agent does not start until you restore the folder from the Trash or choose another one in Files.
- A trigger did not start. Open it on the Triggers page: it shows why a run was skipped or failed.