Agent Blueprints & Profiles

The Swiss AI Hub platform separates agent definitions from their configurations. This lets administrators create multiple customized versions of the same agent type without requiring code changes.

Key Concepts

Agent Blueprint

An Agent Blueprint is a template that defines what an agent can do:

• The workflow steps it follows (what actions it takes)
• The types of inputs it accepts (text, files, images)
• The configuration options available (model selection, parameters)
• The events it produces (what it outputs)

Blueprints are created by developers and appear automatically in the platform when agents come online. You cannot modify a blueprint through the UI. Think of blueprints as read-only templates.

Agent Profile

An Agent Profile is a configured instance of a blueprint:

• Has a unique identifier (agent ID)
• Has a custom name, description, and icon
• Uses specific settings from the blueprint's options
• Can be assigned specific permissions

You can create multiple profiles from the same blueprint. Each profile operates independently with its own configuration. For example, from a "RAG Agent" blueprint, you could create:

• "HR Policy Agent" profile configured to search the HR document collection
• "Legal FAQ Agent" profile configured to search legal documents
• "IT Support Agent" profile configured to search IT knowledge base

Each profile is a separate agent that users can interact with.

Managing Blueprints

Viewing Available Blueprints

Navigate to Admin > Agents > Blueprints to see the agent templates available to your tenant.

The list is not the full set the platform runs. A tenant is granted a standard blueprint set when it is created, and blueprints outside it are absent from this list rather than shown and refused. A sysadmin grants a further blueprint per tenant in the tenant editor — no redeploy, and it appears here immediately. See Access control for how the ceiling is derived.

Each blueprint displays:

• Name: The blueprint identifier
• Description: What the agent does
• Status: Whether any instances are currently online
• Configuration Form: The settings available for profiles

Blueprint Status

Blueprints show online/offline status based on whether any running agent instances have registered recently. An offline blueprint means no agents of that type are currently running, but you can still create and configure profiles. Those profiles will become active when the agent service starts.

Managing Profiles

Creating a New Profile

1. Navigate to the blueprint you want to use
2. Click Create Profile
3. Pick a starting point. Blueprints ship with profile templates — ready-made configurations for common use cases. Selecting one prefills every field, leaving you to review and adjust. Skip this step to start from a blank form.
4. Fill in the required fields:
   • Agent ID: A unique identifier (lowercase letters, numbers, underscores, hyphens)
   • Name: Display name in the selected languages
   • Description: What this specific profile does
   • Icon: Visual identifier
5. Configure the agent-specific settings (model, parameters, etc.)
6. Click Save

Templates are curated per blueprint, not per tenant: a blueprint you can see offers every template it ships. Browse them all under the Templates tab.

The profile becomes available immediately. Users with appropriate permissions can start interacting with it.

Editing a Profile

1. Navigate to Admin > Agents > Profiles
2. Find and select the profile
3. Click Edit
4. Modify the configuration
5. Click Save

Changes take effect for new conversations. Existing active conversations continue with the previous configuration until they complete.

Deleting a Profile

1. Navigate to the profile
2. Click Delete
3. Confirm the deletion

Deleting a profile removes its configuration. Historical conversation data with that profile is preserved for audit purposes. The blueprint remains available for creating new profiles.

Configuration Options

The settings available for each profile depend on the blueprint. Common configuration options include:

Model Selection

Choose which language model the agent uses. Options depend on which models are available through your LiteLLM configuration.

Task LLM

Optional second model for the agent's auxiliary work — short classification and rewriting tasks such as turning a follow-up question into a standalone one, the relevance and context-sufficiency guards, request routing, and generating the conversation title and follow-up suggestions. Pointing them at a smaller, cheaper model reduces cost and latency without affecting answer quality. The exact set of steps depends on the blueprint and is listed in the tooltip next to the Enable Task LLM checkbox.

Only the model is selectable: temperature, breadth of word choice (top_p), and timeout are inherited from Model Selection, and log probabilities are always off for these steps. Leave the whole section disabled and every step runs on the main model.

The knowledge-grounded answer the user reads is always generated by the main model. The one user-facing exception is the reply to a meta question about the agent itself ("what can you do?"), which the task model also handles.

Memory Model

Optional model for user-memory extraction, found inside the User Memory section next to the storage toggle. When a conversation ends, the platform reads it back to distil durable facts about the user and to reconcile them against what it already knows — dropping duplicates, replacing what has been superseded. That work is short and mechanical, so a smaller model is usually enough, and it is worth choosing one: extraction is several model calls per stored conversation, which makes it a meaningful share of an agent's spend.

Leave the Enable Memory model checkbox off and extraction runs on the platform-wide default configured at deployment. Existing profiles are unaffected. Ticking the checkbox reveals the picker already set to that same default, so it is a starting point to move away from rather than an empty field — saving it unchanged keeps the model the platform would have used anyway. The picker only appears while user-memory storage is enabled, since nothing extracts otherwise. If the agent stores memory from conversations containing images, choose a vision-capable model.

The write itself always happens in the background, after the answer has been delivered, so the chosen model never affects how long the user waits. Two things stay deployment-wide: the embedding and reranking models, because memories written with one embedding model cannot be searched with another; and organization memory, which stores the text an agent hands it verbatim and runs no model at all.

Model parameters

The standard parameters under the model picker:

• Temperature and Breadth of word choice (top_p): optional. Each has an override checkbox that shows the selected model's recommended default in parentheses; unticked, the disabled field shows that default and the agent uses it. Ticking pre-fills the field with the default for you to adjust. Lower temperatures (0.0–0.3) give more focused, deterministic responses; higher ones (0.7–1.0) more creative, varied responses.
• Accept images: whether images in the conversation are passed to the model; disabled for models without image support.
• Maximum Input Tokens: unset, 85% of the chosen model's input window (a margin for token-count differences); a limit of your own is capped at that same figure.

Knowledge Base

For RAG-enabled agents, select which document collections the agent can search.

Restrict to the user's access

A profile's collections are checked once, against whoever saved the profile. Without further settings, everyone allowed to use the agent gets answers from all its collections, including ones they cannot open in the knowledge area. With Restrict to the user's access on, every run is narrowed to the collections the asking user may read, using the knowledge area's own rules. The setting is on for new profiles and off for profiles saved before it existed, so nothing changes unannounced. If nothing is left for a user, the agent says that no knowledge is available to them instead of answering as if the documents held no answer. Runs without a user, such as scheduled or mail-triggered ones, keep the profile's scope. The Document Intelligence, Company Knowledge and Document Navigation assistants offer it.

Shared chat settings

Every conversational agent (Instructed, Teachable, Document Intelligence, Company Knowledge, MCP Tool and Universal) brings the same building blocks, each with its own section in the form:

• User Memory and Organization Memory: what the agent recalls about the user and the organization, and whether it stores new facts. Recalled memories reach the model as part of its system instructions.
• Attached Files: a user can attach files in the chat and the agent reads them itself. A file that fits is read whole; a longer one is cut down to the sections most relevant to the question, and the answer says so. The embedding and reranking models that pick those sections are preset (embedding/bge-m3, reranker/bge) and rarely need a change.
• Knowledge Search: the reranking model used when a user points the chat at a collection with #, or when the model chooses to search one itself. It is preset to reranker/bge. Only collections the user may read are searched.
• Read Linked Web Pages: off by default. Turned on, the agent reads the web pages a message links or attaches with # and answers from them; its limits are links per message (5), seconds per page (15) and characters per page (20,000). Offered on the Instructed, Document Intelligence, Company Knowledge and Universal agents; the Web Page Assistant always reads links. See Linked web pages.
• Condense question and Task LLM: described above.

All of them cite what they read as sources in the chat. If a message alone, such as a very long pasted text, is larger than the model's context window, the agent replies that the input is too large instead of failing; the check uses the narrower of the answering model and the Task LLM.

Tool loop settings

Agents that let the model choose its own tools, such as the Universal Agent, add a Tools section:

Setting	What it does
Maximum Decisions	How often the model may choose tools before it must answer with what it has.
Maximum Tool Calls	How many tool calls one answer may make in total.
Disable Tools	Turn on to withhold some tools; the Disabled Tools picker appears only while it is on.
Disabled Tools	Tools of the blueprint this profile never offers, while Disable Tools is on.
Approvals	Per tool: never ask, ask for every call, ask once per answer, or ask once per conversation.

At either limit the model answers without tools and the chat says that it stopped early. A tool is also offered only while the chat toggle it needs (Code Interpreter or My Files) is on. See Agents overview.

System Prompt

Some agents allow customizing the system prompt to adjust behavior and personality.

Permissions

Access to profiles follows the platform's permission system:

• Blueprint access (aihub.admin.agent.{blueprint}): Create profiles from a specific blueprint. This is what a tenant is granted for each of its standard blueprints; it does not carry the profiles already built from them.
• Profile access (aihub.user.agent.{blueprint}.{profile_id}): Use a specific profile. A profile's own rule is added to the creating tenant's ceiling automatically, so a tenant reaches the profiles it builds.
• Wildcard access (aihub.user.agent.*.>): Access all agents (typically for administrators). Deployment-wide, not per tenant — profiles are not separated by tenant in storage, so grant it deliberately.

See the Access Management section for details on configuring permissions.

Best Practices

Naming Conventions

• Use descriptive profile names that indicate the purpose ("HR Policy Assistant" not "RAG Agent 1")
• Keep agent IDs short but meaningful (hr_policy, legal_faq)
• Include the target audience in descriptions ("For employees with HR questions")

Configuration Strategy

• Start with conservative settings (lower temperature, smaller context windows)
• Test with representative questions before deploying widely
• Create separate profiles for different use cases rather than one generic profile

Lifecycle Management

• Review profile usage periodically through audit logs
• Retire unused profiles to reduce confusion
• Document configuration choices for team knowledge sharing