AI Agent¶
Overview¶
An AI Agent in iPassion AI Portal is a custom model preset that wraps a base model with a tailored system prompt, bound tools, knowledge bases, and specific parameters. Agents let administrators create purpose-built AI assistants without writing code — each agent appears as a selectable model in the chat interface.
Example AI Agents¶
| Agent Name | Purpose | Base Model | Linked Knowledge Base |
|---|---|---|---|
| IT Support Assistant | Resolve IT-related issues for employees | GPT-4.1 mini | IT Systems Handbook |
| HR Assistant | Answer HR policy and benefits questions | Gemini 2.5 Flash | HR Policy |
| Customer Support Assistant | Answer customer questions about products and services | GPT-4.1 mini | Customer Service Handbook |
| Document Drafting Assistant | Help draft official documents and memos | Claude Sonnet 4 | Finance & Procurement Regulations |
| Onboarding Assistant | Guide new employees through onboarding procedures and resources | Gemini 2.5 Flash | Onboarding Guide |
Creating an Agent¶
Steps¶
- Navigate to Workspace > Models
- Click + Create
- Configure the agent using the sections below
- Click Save
The new agent will appear in the model selector for users who have access.
Configuration¶
Basic Information¶
| Field | Description | Example |
|---|---|---|
| Avatar | Upload an image (supports GIF and WebP for animated avatars) | Company logo or department icon |
| Name | Display name shown in the model selector | "IT Support Assistant" |
| Model ID | Unique identifier (auto-generated from name, editable) | it-support-assistant |
| Base Model | The underlying AI model the agent uses | GPT-4.1 mini, Claude Sonnet 4, Gemini 2.5 Flash |
| Description | Short description shown below the agent name | "Answers IT questions and troubleshoots issues for employees" |
| Tags | Categorization labels for filtering and organization | it, support, internal |
| Visibility | Public (all users) or Private (restricted access) | Public |
System Prompt¶
The system prompt defines the agent's personality, role, and behavioral rules. It supports dynamic variables that are automatically replaced at runtime:
| Variable | Replaced With |
|---|---|
{{ USER_NAME }} |
The current user's display name |
{{ CURRENT_DATE }} |
Today's date |
{{ CURRENT_TIME }} |
Current time |
{{ USER_GROUPS }} |
Groups the current user belongs to |
Example System Prompt¶
You are the IT Support Assistant for iPassion Co., Ltd.
Today is {{ CURRENT_DATE }}. You are speaking with {{ USER_NAME }}.
Your role is to answer questions and provide guidance on information technology
for employees.
Rules:
- Always respond clearly and professionally
- Reference the IT Systems Handbook as your primary source
- If the handbook doesn't cover the topic, advise contacting the IT helpdesk
- Do not answer questions unrelated to IT
- Provide clear, step-by-step answers that are easy to understand
- When citing information from the knowledge base, include the source document name
Capabilities¶
Configure what the agent can do:
| Capability | Description |
|---|---|
| Knowledge | Bind one or more Knowledge Bases. Choose retrieval mode: Focused (RAG-based, retrieves relevant chunks) or Full Context (injects entire documents) |
| Tools | Bind specific tools the agent can call: Calculator, Code Interpreter, Web Search, Terminal, and any custom tools |
| Skills & Filters | Attach Skills (custom function pipelines) and Filters (input/output processors) to extend agent behavior |
| Vision | Enable image understanding so the agent can analyze uploaded images |
| File Upload | Allow users to upload files in conversations with this agent |
| TTS Voice | Select a specific text-to-speech voice for the agent's audio responses |
| Citation Display | Show source citations from Knowledge Base results inline in responses |
Advanced Parameters¶
Fine-tune model behavior with advanced settings:
| Parameter | Description |
|---|---|
| Stop Sequences | Token sequences that cause the model to stop generating |
| Temperature | Controls randomness (0 = deterministic, higher = more creative) |
| Top P | Nucleus sampling threshold for token selection |
| Max Tokens | Maximum number of tokens in the response |
| Frequency Penalty | Reduces repetition of frequently used tokens |
| Top K | Limits token selection to the K most likely candidates |
Access Control¶
Visibility Settings¶
- Public: The agent appears in the model selector for all users
- Private: The agent is restricted to specific users or groups
Group-Based Restrictions¶
Administrators can restrict agent access to specific user groups. For example, an HR Assistant may be limited to the HR Department group, while an IT Support Assistant is available to all departments.
Hiding an Agent¶
Agents can be hidden from the model selector without deleting them. This is useful for:
- Agents under maintenance or revision
- Seasonal agents that are only needed at certain times
- Testing agents not yet ready for general use
Hidden agents retain all their configuration and can be unhidden at any time.
Management Actions¶
Right-click an agent or use the action menu to access these operations:
| Action | Description |
|---|---|
| Edit | Open the agent configuration for modification |
| Hide | Remove from the model selector without deleting |
| Clone | Create a copy of the agent with all settings |
| Copy Link | Copy a direct link to start a chat with this agent |
| Export (JSON) | Download the agent configuration as a JSON file for backup or transfer |
| Share | Share the agent with the Open WebUI community hub |
| Delete | Permanently remove the agent (requires confirmation) |
Global Defaults (Admin)¶
Administrators can configure system-wide defaults that apply to all agents and models:
| Setting | Description |
|---|---|
| Default Model Metadata | Set default system prompt, knowledge bases, tools, and capabilities that apply when no agent-specific values are set |
| Default Model Parameters | Set default temperature, top P, max tokens, and other generation parameters |
These defaults act as a baseline — individual agent configurations override them.
Selected and Pinned Models¶
Administrators can manage model visibility and convenience:
- Selected Models: Pre-select which models and agents appear for new chats. Unselected models are hidden from the model selector for regular users.
- Pinned Models: Pin frequently used agents to pre-fill sidebar shortcuts, giving users quick one-click access to key agents.
Using an Agent (For Users)¶
Steps¶
- On the Chat page, click the model selector at the top
- Browse or search for available agents (agents display their custom avatar and description)
- Select the desired agent
- Start chatting — the agent responds according to its system prompt, tools, and linked Knowledge Bases
- If the agent has Knowledge Bases bound, it will automatically search them when relevant
- If the agent has tools enabled, it can perform actions like calculations, web searches, or code execution
Reference
For more technical details, see the Open WebUI — Models (Workspace) documentation.