# Agents — the thing you build What an agent is: a provider, a model, a system prompt, the sampling and reasoning controls a model supports, and the tools it can call. Status: Shipped An **agent** is the unit you build and then talk to. It binds one of your providers and a model it serves to a system prompt, a handful of sampling controls, and the tools it is allowed to call. You make as many as you like, and each can sit on a different backend. ## Why it matters The provider decides _where_ the compute happens; the agent decides *how the model behaves* — its standing instructions, how adventurous its sampling is, whether it reasons before answering, and what it can reach through tools. Two agents on the same provider and model can behave nothing alike, because everything that shapes a turn lives on the agent. ## What you configure - **Name** — required, and unique within its workspace. - **Short description** — an optional one-line summary of what the agent is for. It never enters the agent's own prompt; it's there so other agents that manage or call this one can tell it apart at a glance. - **Provider & model** — pick one of your providers, then a model it serves from that provider's list. You choose the model from the catalog; you don't type a model id. The provider menu shows each provider's host under its name, so one named after a service but pointing elsewhere is plain to see. With no provider yet, the form offers **Create a provider** instead. - **What the model must handle** — tick _Image input_ or _Reasoning_ when the agent only works on a model that can. _Tool calling_ shows beside them while the agent has tools attached. The model list opens narrowed to the models that advertise all of them, and the requirement travels with an exported agent, so whoever imports it is offered a model that fits. - **System prompt** — the standing instructions for the agent. Multiline, optional. - **Welcoming message** — an optional opening message shown when a new conversation with the agent starts. - **Model tuning** — next to the model, an _Advanced_ expander holds Temperature, Max tokens, Frequency penalty, Presence penalty, Repetition penalty, and — for models that reason — a control to turn thinking on or off, choose an effort level, or set a token budget. Each control appears only when the chosen model advertises support for it, so the form won't show a knob the model would ignore, and the whole expander is hidden for models with nothing to tune. - **Turn, compaction & titling** — under _Additional settings_: how many tool rounds a turn may take and how much history the model sees (the _conversation loop_), when and how a long conversation is compacted, and whether this agent titles and summarises its own conversations. Each of these starts _inherited_ from your app-wide defaults and can be overridden just for this agent — see [Inheriting from your defaults](#inheriting-from-your-defaults) below. - **Constant overrides** — a section of its own after the tools, shown once the agent's workspace reaches a [constant](/docs/features/tools#constants-an-account-id-typed-once): this agent's own text for it, such as a different account with the same provider. It wins over the workspace's text and the global one, for the agent's model, its tools and its titles alike. Each constant is listed with its scope — _Global_ or the workspace's name — so a workspace constant and a global one of the same name are told apart. A conversation keeps the text its agent had when it began, so changing it later leaves earlier conversations as they were. An agent with the constants tools can set it too, with `constants-override_for_agent`, once you approve. - **Tools** — attach the tools this agent may call. **Add tools** opens a picker where you tick as many as you want and add them in one go. Some (a memory namespace, a fetch request, a conversation title tool) carry their own small setup form. Tools are listed by name, here and on the agent's page. Shown only when the model supports tool calls. An allowlist of agents this one may call can't close a loop — two agents allowed to call each other would spin a turn until its tool-round limit — so Save stays off while one would, naming the agents in call order. - **Workspace** — an optional grouping; agents you don't file land in a Default workspace. ![The agent form, where a provider, model, prompt, and tools become an agent](/images/agent_form.png) ## How it works Open **Agents**, create one, and fill in as much as you need — at minimum a name, a provider, and a model. The prompt and the sampling controls are optional and fall back to sensible defaults. Because the sampling and reasoning controls are gated on the selected model's declared capabilities, the form only surfaces the knobs that model actually honours. Attach tools last; from then on the model decides when to call them during a conversation. ## Inheriting from your defaults Most of what shapes a turn has an app-wide value you set once on the **Global settings** page — _Titles & summaries_, _Conversation loop_ and _Context compaction_, reached from **Settings → Workspaces** — and every agent inherits it until it decides to differ. Where an agent can override one, the form shows the value in force — the inherited number sits in the box, in italics behind a small ⤷ marker, with _Inherited from the global settings_ beneath it. Type over it to set the agent's own value, and the line becomes _Set here · would inherit 200 from the global settings_ with a **Reset** beside it that hands the field back — so you can see what letting go of an override restores before you do it. A workspace can carry its own overrides too, sitting between the global settings and the agent, so a whole workspace of agents can share a tuning without repeating it on each one. The order, most general to most specific, is: the global settings, then the workspace, then the agent. Each layer only fills in what the layer above left unset. A conversation then keeps the agent's settings as they stood when it started, so tuning an agent later doesn't rewrite the conversations you already had. One thing never cascades: the **provider and model**. There is no fallback model — every agent binds its own, on purpose, so a turn always runs on a backend you chose rather than one inherited by accident. ## Good to know If you later swap or remove the provider, an agent keeps the model id it was built with rather than silently dropping it — it just flags that the id is no longer in the provider's list. Re-pick a model from the new provider to clear the warning. The conversation page and the editor also warn when the chosen model can't read a conversation's images or call its selected tools, so a capability mismatch is visible rather than a silent drop. To start a new agent from an existing one, use **Copy** on the agent's page: it opens the create form pre-filled with a duplicate (its name suffixed "(copy)"), so you can adjust the name — which isn't checked for uniqueness until you save — before anything is written. **Export** beside it saves the agent, with its provider, tools and the agents it calls, as one `.bylm.json` file; long-press agents on the list to tick several and export them together. See [Sharing](/docs/features/sharing). While Save is off, a line above it says so, and **Show** scrolls to the first field that needs fixing. Leaving the form with unsaved edits asks _Discard changes?_ first, and a save that fails says why instead of leaving the form. An agent a newer version of BYLM wrote parts of — a tool or a prompt syntax this version can't read — still runs with what this version understands, but the form names those parts and won't save it: update the app to change it, or remove the unreadable tools. If the agent's provider was deleted, or can't run on this device, the model section says so under its field. More in [Features](/docs/features): [Providers — bring your own LLM](/docs/features/providers) · [On-device models — run fully offline](/docs/features/embedded-models) · [Tools — giving an agent more than the model knows](/docs/features/tools) · [Workspaces — keep your work in scopes](/docs/features/workspaces) · [Conversations — how a turn runs](/docs/features/conversations) · [Attachments — images and files in a message](/docs/features/attachments) · [Context management — what the model still sees](/docs/features/context-management) · [Background turns — replies that keep running](/docs/features/background-turns) · [Local-first & private by design](/docs/features/local-first) · [Sync — your data across your devices](/docs/features/sync) · [Sharing — move agents, tools and providers as a file](/docs/features/sharing) · [Marketplace — find and publish shared agents, tools and providers](/docs/features/marketplace) · [Running a Couchbase Edge Server](/docs/features/couchbase-edge-server) · [Spell checking — catch typos while you write](/docs/features/spell-check) --- [Bring Your LM](/) · [Docs](/docs/features) · [Marketplace](/marketplace) [Articles](/articles) · [Releases](/releases) · [Bundle Format](/marketplace/bundle-format) · [Marketplace Terms](/terms) · [App Privacy](/privacy) · [Website Privacy](/website-privacy) · [Open Source](/open-source) · [llms.txt](/llms.txt)