Skip to content

Universal Agent ​

Enterprise feature

The Universal Agent is part of bbv AI Hub Enterprise. Running it needs a bbv AI Hub Enterprise License; see LICENSES.md.

The Universal Agent works the way people expect a modern assistant to work. Instead of following a fixed sequence of steps, it looks at each message and decides for itself what it needs: search your company's knowledge, read a file the user attached, recall what it remembers about the user, or answer straight away. It keeps going, one tool after another, until it can answer.

Every other agent on the platform follows a fixed workflow, so an admin picks the right one per use case and users have to know which assistant to ask. A Universal Agent profile is configured once with the knowledge it may search, and users ask it anything.

When to reach for this agent

Use the Universal Agent as a general assistant that combines your knowledge, the user's attachments and memory in one conversation. When a use case needs a guaranteed, auditable sequence of steps — always retrieving from the same collections, checking grounding before answering, escalating to an expert — use the dedicated blueprints such as the Document Intelligence Assistant. They stay the predictable option.

What it does ​

  1. Prepare the conversation. The agent's built-in instructions on using its tools, then your profile's own instructions, are put at the front of the conversation, and the history is trimmed to the input budget.
  2. Decide and use tools. The model chooses which tools to call, the platform runs them and hands the results back, and the model decides again. It can call several independent tools in one round.
  3. Answer. When the model has what it needs, its reply streams to the user with citations to the documents it used.

Nothing is loaded into the prompt in advance: a question that needs no lookup is answered directly, and one that needs three lookups gets three.

The tools ​

ToolWhat it doesOffered when
Search our knowledgeSearches the knowledge collections the profile allows, reranks the results and returns the best sections with ids to cite. The user's own # references are offered too. Only collections the asking user may read are ever searched.The profile lists collections, or allows every collection the user can read.
Read attached filesReads the files attached to the conversation. The model sees which files are attached and reads the ones it needs; a file too long to read whole returns the sections most relevant to what the model is looking for.The user attached a document (images reach the model directly).
Recall memorySearches what is remembered about the user and the organisation: preferences, facts and decisions from earlier conversations.User or organisation memory is enabled on the profile.
Code sandboxRuns commands and reads and writes files in the user's own code sandbox, in a folder per conversation that holds the conversation's attached files. A file the agent shows the user, such as a chart or a spreadsheet, is attached to the answer and stays downloadable.The user switched on Code Interpreter in the chat.
My filesLists and reads the user's own files in My Files: their uploads, chat attachments and files agents made for them. Read-only.The user switched on My Files in the chat.
Read linked web pagesReads the web pages the user linked in the message or attached with #, and only those: a call naming any other address is refused, so an instruction hidden in a page or file cannot send the conversation elsewhere. See Linked web pages.Read Linked Web Pages is on in the profile and the message links a page.
Knowledge documentsLists the documents of the knowledge collections by path, finds every document whose text contains an exact term or pattern, ranks the documents by meaning to find those written in other words or another language, and reads a whole document a part at a time. Unlike the knowledge search, it finds every match, not the most similar passages. It never leaves the profile's collections or its document path filter.Work on Whole Documents is on in the profile.
Extract a tableCollects records from many documents into one table, each row naming its file, as the Knowledge Extraction Agent does. The model first checks which documents a selection covers; the user sees the table directly, with its summary, and the model describes it. Asks the user to confirm every new extraction in a request form.Work on Whole Documents is on in the profile.

More tools follow as the platform adds them: web search and image generation each add their tool to this agent.

Every tool call shows in the chat: the knowledge search and the files appear as sources, each call as a collapsible block with what the tool returned, and the agent trace records each step.

Staying within the model's context ​

Long conversations with many tool results can outgrow what the model can read. Before each decision, the agent checks the size and, when needed, condenses the oldest material first: earlier tool results are summarised to what matters for the question, then the conversation before the question becomes one summary. The chat shows a short status when this happens. The current question and the latest results are never summarised; only when the latest results alone are too large are they cut to fit, marked as cut. When even the question and the tools' descriptions do not fit, the agent answers without its tools.

Limits and approvals ​

A profile bounds how many decisions and tool calls one answer may take. At the limit, the agent answers with what it has found and says that it stopped early. Any tool can be set to need the user's approval before it runs — every time, once per answer, or once per conversation. The approval question shows the call's input exactly as the model wrote it; a long command scrolls in its own box.

What it does not do ​

  • It is not a fixed workflow. The model decides which tools to use, so two similar questions may take different paths. For a guaranteed sequence, use the dedicated blueprints.
  • It does not replace the Document Intelligence Assistant's retrieval. Its knowledge search is simpler: each database is searched with the embedding model it was indexed with and the results are reranked together, without the Document Intelligence Assistant's per-retriever tuning or grounding check.
  • It never reads what the user may not. Collections the asking user cannot read are not offered, even when the profile lists them or the profile allows "every collection".
  • Its code sandbox is shared hardware. Each user's sandbox home is separate, but all users share one container, so it is not a hard boundary between users; see Coding.
  • No tools from external systems yet. MCP tool servers and handing off to other agents are planned follow-ups; use the MCP Tool Agent for those today.

Setting it up ​

  1. Grant the blueprint. The Universal Agent is not part of a new tenant's default set; a sysadmin grants it (see Access control).
  2. Create a profile. In Admin > Agents > Blueprints, select Universal Agent and click Create Profile. Give it an Agent ID, a name, a description and an icon.
  3. Write the instructions. Describe what this assistant is for and how it should answer. They are added after the built-in instructions on using tools, so you do not need to explain the tools.
  4. Choose the knowledge. Under Knowledge Tool, either list the databases and collections it may search, or turn on Every Collection the User Can Read.
  5. Choose the model. Pick a chat model that supports tool calls. The Task LLM condenses long conversations and writes titles and follow-up questions, so a smaller model is fine there.
  6. Review the limits and approvals under Tools, then save.

Configuration reference ​

Behaviour ​

FieldDefaultDescription
Instructions(empty)What this assistant is for and how it should answer, added after the built-in instructions.
Maximum Input TokensModel window (85%)The input budget. The conversation is trimmed and, inside the tool loop, condensed to fit it. Optional. Unticked by default: the agent fills about 85% of the selected chat model's input window, which is shown in the checkbox label and the disabled field (e.g. "(78,050)" for gemma on Infomaniak) and follows the model when you switch models. The 15% margin allows for differences between the token counter and the model's tokenizer. Tick Set your own input limit to set a lower limit and cut cost: minimum 1,024, maximum that same 85% figure, which the hint under the field names next to the model's full window; a higher value is blocked in the form and rejected by the API. Profiles that stored a limit above that figure have it unset automatically when the platform is upgraded.

Knowledge Tool ​

FieldDefaultDescription
Every Collection the User Can ReadOffOffer every knowledge collection the asking user may read, instead of the listed ones.
Collections—Databases the model may search, each whole or narrowed to some of its collections.

Under Knowledge Search, Sections per Database and the Reranking Model set how the search ranks what it finds.

Tools ​

FieldDefaultDescription
Maximum Decisions10How often the model may choose tools before it must answer.
Maximum Tool Calls20How many tool calls one answer may make in total.
Disable ToolsOffTurn on to withhold some tools; the Disabled Tools picker appears only while it is on.
Disabled Tools—Tools this profile never offers, while Disable Tools is on.
Approvals—Tools whose calls the user must approve first: every call, once per answer, or once per conversation.

Knowledge Documents ​

FieldDefaultDescription
Work on Whole DocumentsOffOffer the document tools and table extraction. Profiles saved before these tools existed keep them off.
Document Path Filter(empty)Only documents whose path matches this pattern, e.g. invoices/**. It limits the document tools, not the search.

Table Extraction ​

FieldDefaultDescription
Extraction Modelmain modelThe model that reads each document and extracts its rows.
Most Documents per Table1000Above it, the user is only asked to narrow the request.
Longest Fully Read Document500000Longer documents (in characters) are read in their relevant parts, marked as such.
Model Calls at Once4Extraction calls one agent instance makes at the same time.

Extraction behaves as in the Knowledge Extraction Agent: one answer extracts every selected document, the chat shows the first 100 rows and the whole table is a CSV file attached to the answer (a download link through the API). A selection of more than 100 documents first gets a sample, and the model asks the user before it extracts them all; an answer that showed a sample extracts nothing more, so the user always confirms after seeing it.

Before a new extraction runs, the user confirms it in the same request form as the Knowledge Extraction Agent's, in three parts filled in from the model's call: Location, Filter Condition and Values to extract. It asks no keywords, since the model has searched already. In OpenWebUI it is a dialog; every other client shows it as a chat message, which the next message answers. A location the user writes is matched against the folders, files and years in scope. A yes runs the extraction, a no tells the model the user declined, and any other reply, or a written location that names nothing in scope, goes back to the model, whose corrected extraction then runs without a second form. Confirming a sample is not asked again.

The form replaces the yes/no approval, so Extract a table needs no approval by default (never); a profile that sets one asks for it as well. The Workplace Assistant template keeps the document tools off: it is the general everyday assistant, its users rarely need a table across many documents, and fewer tools keep its choice of tool reliable.

Memory and attached-file settings are the same as on the other chat agents; see Memory.

Built with ❤️ in Switzerland 🇨🇭