Agents
An agent is a reusable base configuration that users build projects from. Every project in BasePeak.AI is created from an agent, which determines which capabilities, tools, and model the project starts with.
Admins manage agents at /admin/agents.
The default agent
One agent can be marked as the default agent. Non-admin users can only create new projects from the default agent. Admins can create projects from any agent.
To change the default agent, click Set default agent on the Agents page and select from the list.
Creating and deleting agents
- Create — Click the + button to create a new agent. You are taken directly to the agent editor to configure it.
- Delete — Use the row action menu on the Agents list. Deleting an agent does not delete projects already created from it.
Agent list
Besides the name, the agent list in the administration shows columns that help you find agents:
- Owner — the owners entered in the agent's Administration card (users and groups). If an agent has no entry, for example because an instance administrator created it, the column shows "—". If you may not read the user directory, you never see a name that looks like an email address: the username is shown instead, or the user's ID when neither is usable.
- Tags — the agent's tags (see Tags).
Both columns are filterable. The filters are kept in the page address, so you can bookmark or share a filtered list. Free-text search also matches tags.
With Teams switched on, a Teams column is added: it counts the teams the agent is granted to and shows "—" when there are none. Clicking the number opens the list of teams. Whoever manages all teams (instance administrators and the space:manage permission) sees every shared team by name and can click through to the team's settings; Personal teams appear only as a count. Everyone else sees by name only the teams they are a member of, and the rest as a count. The column can be filtered by team name and sorted by count. If the team data could not be loaded, the column shows a "?" instead of a number – which does not mean the agent is granted to no team.
Agent editor
Clicking an agent's row opens the editor, which is organised into the following sections.
Name and description
Set a human-readable name and optional description. These are visible to users when choosing which agent to base a project on.
Tags
Below the description you can attach tags to the agent, such as "Building authority" or "Draft". Press Enter or type a comma to add a tag. An agent can have up to 10 tags of at most 40 characters each; too many tags, or tags that are too long, are refused, not silently trimmed. Duplicates are detected ignoring case, and the first spelling is kept. While you type, the editor suggests tags already used on agents you can see.
On the users' Agents page, tags appear as chips above the lists. Selecting several narrows the list to agents that carry all selected tags; Reset filter clears the selection.
What a new agent starts with
Create Agent does not produce a blank agent. It starts on the same baseline as the built-in assistant: Workspace Files and Tasks always on, Date and Time and Search Knowledge on by default. Each is an ordinary row you can re-mode or remove.
Model
Select which language model the agent uses. Choosing Use system default means the agent inherits the platform default model configured on the Model Providers page.
Tools
This section configures which tools are available to projects created from this agent. Any tool not included here will not be available in those projects, so when configuring the default agent, include the full set of tools you want users to have access to.
A tool added from the catalog arrives On by default: on in new chats, and still the user's to switch off.
Each tool uses the same modes as capabilities, minus Off: for a tool, "not available" simply means it is not assigned, so remove it with the trash icon instead.
Tools that require OAuth can be pre-authenticated at the agent level. This is generally only recommended for single-user agents, since the credentials are shared with all users.
Capabilities
Capabilities control which built-in features are available to projects created from this agent. Each mode answers two questions: is the capability on when a chat or project starts, and may the user change it?
| Mode | On at start | User can change it | Meaning |
|---|---|---|---|
| Always on | yes | no | Active in every chat. Users cannot switch it off. |
| On by default | yes | yes | Active when a chat or project starts. Users can switch it off. |
| Off by default | no | yes | Offered but off. Users can switch it on themselves. |
| Off | no | no | Not available. Users never see it. |
The same four modes name availability throughout the editor — for tools and capabilities, and for the data-protection and model-routing options under Advanced.
The configurable capabilities are:
| Capability | Description |
|---|---|
| Search Knowledge | Allows the project creator to upload files that serve as a searchable knowledge set for the agent |
| Workspace Files | Allows the project creator and users to upload files to a shared workspace the agent can read and write |
| Tasks | Enables users to create tasks in the project |
| Threads | When disabled, users are limited to a single non-deletable thread in the project |
| Memory | Enables the agent to retain information across threads |
Actions
Actions are custom shortcuts that appear in the project interface. Each action has a name, a description shown to the user, a prompt that guides the agent, and an optional subset of the agent's tools to use. Actions let you surface common workflows as one-click prompts.
Knowledge
Attach knowledge sets directly to the agent. Knowledge attached here is available to all projects created from this agent.
This section needs the Search Knowledge capability. With it off the agent has no tool to search with, so anything added here would be stored and then never read — the section says so, and offers to switch the capability on. Knowledge that already exists stays visible either way, so it can still be detached.
Workspace Files
View and manage files in the agent's workspace.
Access control
Who may reach this agent. This is not a review surface — it is where access is granted, and it is edited in the Publish dialog alongside the agent's address, because those are one decision.
A new agent has no entries, and that means nobody: a user's agent list is built from these grants alone, so an agent with none appears in no user's list. The card says so until you add someone. Instance admins always reach any agent, as does anyone who already holds a project on it, so neither is listed here.
Grants and revocations apply immediately — Cancel in the Publish dialog discards only the address.
Per-agent administration
Who may administer an agent is separate from who may use it. The Administration card in the agent editor grants two roles to individual users or groups:
| Role | May |
|---|---|
| Editor | change the agent: settings, tools, knowledge, workspace files, environment variables, authorizations |
| Owner | everything an editor may, plus manage administrators, restrict administration and delete the agent. Copying needs the agent:create permission, or on a restricted agent the owner role instead. Publishing its knowledge needs the knowledgeset:publish permission, plus the owner role on a restricted agent |
Use Add administrator to search for users and groups and pick the Role. Administrator roles exist only for individual users and groups, not for "everyone" and not for plain email entries. Remove admin rights turns the person back into an ordinary User, who keeps chat access. To remove access entirely, delete the entry under Access control. Whoever creates an agent automatically becomes its owner.
Two changes reach beyond the single agent and so take more than a role: only someone with the global agent:update permission (or a super-admin) may set the default agent, and an editor may attach a standalone knowledge set only with agent:update or knowledgeset:manage. Someone who already is an editor or owner appears under Add administrator with that role; change it in the list.
Restricting administration
Without a restriction, global agent rights keep their effect: anyone holding the agent:update permission may change any agent as an editor. Turn on Restrict administration to the people listed here and only what is listed on this agent counts:
- Global agent rights (
agent:update,agent:delete) are no longer enough. Administrators holding them can neither open nor change the agent, and it is not listed for them. Direct requests answer "not found" (404). - Instance admins (super-admins) can still administer every agent. This is how you recover an agent whose owner has left the company.
- Restricting requires at least one living owner, meaning an existing user or an existing group. Super-admins are exempt.
- A restricted agent can be copied only by an owner, and the copy stays restricted. Publishing its knowledge set also needs an owner, and making it the default agent is reserved for super-admins.
Groups as owners
Owners and editors may be groups, including groups synced from the identity provider, such as Entra ID groups. Membership then follows the group: whoever joins gets the role, whoever leaves loses it.
The last owner
The last living owner of a restricted agent can be neither removed nor demoted (error 409). Deleting a user or group is likewise refused when it is the sole owner of a restricted agent; the error names the affected agents. Appoint another owner there first. Otherwise, deleting a user removes that user's agent roles.
Administration history
Owners see the Administration history in the agent editor: who granted, changed or revoked roles and who set or lifted the restriction, and when, including the creation of the agent. Super-admins and auditors (the user:read permission) can fetch the same entries via GET /api/audit-events?resourceType=agent&resourceID=<id>. This is not reachable with an API key.
API keys
Editors may mint keys with the scopes agent:update:<id> and agent:files-write:<id> for their agents. A key with agent:update:<id> acts at most with the role of its owner. The scope agent:update:* still requires the global agent:update permission. What counts is the owner's rights at the time of the request: their editor or owner role and, on unrestricted agents, the global agent:update permission. Once the owner has neither, the key no longer reaches the agent and can no longer be rotated. The same applies to workspace files written by a key with agent:files-write.
What is not protected
The restriction covers the agent and its routes, not standalone knowledge sets. Anyone holding the knowledgeset:manage permission can still read and change a knowledge set attached to the agent. The card warns about this when such a set is attached.
Who sees the console
People who hold only an owner or editor role see Agents in the admin console and land there from /admin.
Advanced
Allowed model providers
Restrict which configured model providers users may select when choosing a model for their project. If left empty, all configured providers are available.
Environment variables
Set key-value environment variables that are passed to all tools invoked by this agent and by projects created from it. Use this to supply API keys or configuration values that tools need at runtime.
Automatic model routing
Auto · Balanced picks, for each message, the cheapest model strong enough for its complexity; files mentioned in the message count toward it. On a chat with file protection, Auto treats every message as personal data. If no model cleared for personal data is then strong enough, it can go anonymized to a stronger model cleared for confidential data.
Auto · Balanced is only offered once an administrator has enabled it under Settings → Automatic model routing.
The anonymized hand-off happens only when Allow anonymized personal data on models cleared for confidential data is on in the agent editor under Advanced → Automatic model routing, and file protection is active for the chat. While file protection is off for the agent, the option cannot be switched on, though one already on can still be switched off.
When file protection replaced anything in a request — detected personal data or a file name — the request counts as personal data, whoever picked the model. With the option on it may reach models cleared for confidential data; without it, only models cleared for personal data. Auto · Privacy-first ignores the option: in chats with file protection it only routes to models cleared for personal data. The option helps Auto · Balanced and manual model choice. If no model in the project may receive the request, Auto refuses the turn.
What a model is cleared for also applies to image generation, image editing, transcription and text-to-speech: the text prompt and the text to be spoken are checked like a chat message. Uploaded images and audio cannot be classified; a model not cleared for personal data receives them only when enforcement is set to warn. Where enforcement would reroute, these requests are refused instead.
File Shield also anonymizes what the platform adds to the system instructions: workspace file names, stored memories, other context tools' output, and project and thread prompts. A workspace file name is replaced as a whole as soon as the PII service detects personal data in it; other file names stay as they are. Only the agent's own prompt and the platform's fixed directives reach the model as written, so keep personal data out of the prompt.
Detection is not perfect. Anything the PII service misses is sent as written. Tasks that need the real values, such as checking an IBAN, only see placeholders.