Assistants tab
Overview​
The Assistants tab displays all your AI assistants as a card grid and provides controls to create new assistants, filter the list, and manage each assistant through card actions.
Click Assistants in the left navigation to open the AI Assistants page, where the Assistants tab is shown by default.
| Action | Description |
|---|---|
| [1] Create AI Assistant | Opens the Create AI Assistant dialog. |
| [2] Filter by name | A text field that filters the card grid by assistant name as you type. |
| [3] Filter by status | A dropdown that filters the card grid by assistant status: Any status, Active (running), Idle (sleeping), Offline (stopped), or Faulted (error). |
| [4] Assistant cards | A card for each assistant, showing its name, status, description, wake cycles, and action buttons. |
Create an AI assistant​
The Create AI Assistant dialog organizes an assistant's settings into five tabs: General, Chat, Agent Settings, Expert Settings, and Cost Controls.
To open the dialog, click + Create AI Assistant in the top-right corner. The dialog opens on the General tab. Configure the tabs as described in the following sections.
General tab​
On the General tab, enter a Name, then optionally set the assistant's description, instructions, and history management.
The following table describes each setting on the General tab:
| Setting | Description |
|---|---|
| Name (Required) | The assistant's display name. |
| Description | A short summary of what the assistant does. Appears on the assistant's card. |
| Assistant Instructions | The system prompt instructions that define the assistant's role, behavior, and constraints. |
| History management | The memory tiers the assistant uses to keep conversation history beyond its context window. All three tiers are selected by default (see the following list). |
| History max characters (Optional) | The maximum size, in characters, of the summary of older conversation history. |
| History recent characters (Optional) | The number of characters of recent conversation history retained verbatim. Appears when Semantic retrieval is selected. |
| History retrieval characters (Optional) | The number of characters of older history retrieved through semantic retrieval. Appears when Semantic retrieval is selected. |
The assistant's context window is always active. These tiers extend its memory beyond that window:
- Compactification (rolling summary of older context): Keeps a running summary of older messages as the conversation grows.
- Semantic retrieval (vector search of conversation history): Retrieves the most relevant earlier messages by meaning.
- Full history file (agent can call
read_full_chat_history()on demand): Keeps the full conversation history in a file the assistant can read on demand.
If you clear all three tiers, the assistant keeps only the most recent conversation history.
The Chat, Agent Settings, Expert Settings, and Cost Controls tabs use the same settings as a chat session. They start from your deployment's default chat configuration, which an administrator can change, so the available options and defaults can vary between deployments.
The following sections describe each setting on these tabs. For more detailed explanations, see Customize a Chat session.
Chat tab​
The Chat tab sets the model the assistant uses and how it generates responses.
The following table describes each setting on the Chat tab:
| Setting | Description |
|---|---|
| Default LLM | The language model the assistant uses. When more than one model is available, the default is Automatic, which lets Enterprise h2oGPTe select the model. |
| Default generation approach | The approach used to generate responses, such as retrieval-augmented generation (RAG). |
| Default prompt template | The prompt template applied to the assistant's messages. |
| Enable Vision | Whether the assistant processes document images with a vision-capable model. Select Off, Automatic, or On. |
| Vision LLM | The model used to process images when vision is on. Appears when vision is enabled and more than one vision-capable model is available. |
Agent Settings tab​
The Agent Settings tab controls how the assistant's agent reasons and acts.
The following table describes each setting on the Agent Settings tab:
| Setting | Description |
|---|---|
| Agent Type | The type of agent the assistant uses. |
| User Persona | The persona the agent adopts when it works. |
| Agent Accuracy | The accuracy level the agent targets. |
| Final Answer Mode | How the agent produces its final answer. |
| Dedicated Pod | Whether the agent runs in its own isolated pod, which is more secure, or on a shared pod. |
| Max Agent Turns | The maximum number of reasoning turns the agent takes, from 1 to 240. |
| Max Agent Turn Time | The maximum time, in seconds, the agent spends on a single turn, from 30 to 7200. |
| Agent Runtime Range | The minimum and maximum time, in seconds, allowed for the agent's full run. The minimum runtime overrides Max Agent Turns. |
| Task Tracking | Whether the agent tracks tasks, which helps with long-running, multi-step work. |
| Task Update Steps | How often, in steps, the agent updates its task tracking. Appears when Task Tracking is on. |
| Query Understanding Iterations | The number of times the agent refines its understanding of the request, from 0 to 3. A value of 0 turns this off. |
| Planning Forced Mode | Whether the agent plans before it acts. Select Auto, Force On, or Force Off. |
| Critique Forced Mode | Whether the agent critiques its own work. Select Auto, Force On, or Force Off. |
| Confidence Checks | How many times the agent checks its confidence in a response. Select Auto, 1, 2, or 3. |
| Too Soon Forced Mode | Whether the agent keeps working even when the model reports it has finished. Select Auto, Force On, or Force Off. |
| Tools | The tools the agent can use, such as web search, code execution, and document retrieval. The agent decides which tools to use. |
For more detailed explanations of the agent type, user persona, accuracy, and related settings, see Use Agent in Customize a Chat session.
Expert Settings tab​
The Expert Settings tab controls advanced options for how the assistant generates responses and retrieves content.
The following table describes each setting on the Expert Settings tab:
| Setting | Description |
|---|---|
| Include Chat Conversation History | Whether the assistant includes previous messages as context. Select Off, Auto, or On. |
| Temperature | Controls response variability, from more deterministic to more creative. |
| Output Token Limit | The maximum length, in tokens, of the assistant's response, from 128 to 32768. |
| Manual Reasoning Effort Control | Whether you set the model's reasoning effort yourself. When off, the assistant sets it automatically. |
| Reasoning Effort | The reasoning effort, in tokens, from 0 to 65000. Higher values allow deeper reasoning. Appears when Manual Reasoning Effort Control is on. |
| Include Self-Reflection | Whether the assistant reviews its own output before it responds. |
| Top K Chunks | The maximum number of document chunks retrieved for context, from 0 to 100. A value of 0 means no limit. |
| Document Metadata to include | The document metadata included with retrieved content, such as the filename, page number, document text, and captions. |
| Number of neighboring chunks to include for Summary RAG | The number of neighboring document chunks included for summary RAG, from 0 to 5. Appears for the RAG+ generation approach. |
Cost Controls tab​
The Cost Controls tab sets cost and accuracy preferences for automatic model selection. These settings apply only when Default LLM is set to Automatic on the Chat tab. If you select a specific model, the tab shows a message: "Cost controls only apply when the LLM is set to 'Automatic'."
The tab has three settings:
| Setting | Description |
|---|---|
| Upper Limit on Cost per LLM call | The maximum cost, in US dollars, allowed for a single LLM call. |
| Willingness to Pay for Accuracy | The balance between lower cost and higher accuracy. |
| Willingness to Wait for Accuracy | The balance between faster responses and higher accuracy. |
After you configure the tabs, click Create. The new assistant appears in the card grid in a stopped state. To run it, click Start assistant (the lightning-bolt icon) on its card.
Filter by name​
Use the Filter text field to search for assistants by name. The card grid updates as you type, showing only assistants whose names match your input. Clear the text field to show all assistants.
Filter by status​
Use the Status dropdown to filter assistants by their current status. The dropdown has the following options:
- Any status: Shows all assistants (default).
- Active (running): Shows assistants that are currently running.
- Idle (sleeping): Shows assistants that are idle and waiting for a trigger.
- Offline (stopped): Shows assistants that are stopped and not running.
- Faulted (error): Shows assistants that stopped because of an error.
Assistant cards​
Each assistant appears as a card in the grid. A card displays the following information:
- Name: The assistant's name.
- Status badge: The current status, such as Active (running) or Idle (sleeping).
- Description: A short summary of the assistant's purpose.
- Wake cycles: The number of times the assistant has been triggered.
- LLM: The language model the assistant uses.
Card actions​
Each card includes the assistant's name and a row of action buttons along the bottom. The following screenshot shows the card actions, where [1] is the assistant name and [2] through [7] are the action buttons:
The following table describes each numbered action:
| Action | Description |
|---|---|
| [1] Assistant name | Click the assistant name or anywhere on its card to open its detail view, where you can see its messages, activity, and configuration. |
| [2] Watch & Chat | Opens the assistant's live view, where you can watch its activity and chat with it. |
| [3] Edit | Opens the assistant's settings for editing. |
| [4] Delete | Deletes the assistant. This action is permanent and cannot be undone. |
| [5] Share | Gives other users read-only access to the assistant. |
| [6] Pause or unpause | Pauses a running or sleeping assistant. For a paused assistant, this button changes to Unpause assistant. |
| [7] Start or stop | Starts a stopped or faulted assistant. For a running or sleeping assistant, this button changes to Stop assistant. |
These action buttons appear only on assistants you own.
Assistant name​
To open an assistant's detail view, click its name or anywhere on its card. The header displays the assistant's name and status. If you own the assistant, the header also includes controls to start, pause, or stop it. You can use the back arrow to return to the Assistants tab.
Below the header, the detail view has the following tabs.
Assistant overview
A summary of the assistant, with stat cards for wake cycles, status, model, and creation date, followed by the assistant's description, instructions, and metadata such as the owner, history management, and Memory Block.
Direct messages
A one-to-one message thread with the assistant. Type a message in the box to send it directly.
Approvals
Pending and resolved approval requests for the assistant's gated actions. Approve or reject each pending request before it times out.
Custom tool
Owner controls for what the assistant can do:
- Trigger permissions: Set which events can wake the assistant:
user_message,forum_post,scheduled_task,manual,custom_event, andassistant_message. - Tool permissions: Set which actions the assistant can run, each as Allow, Approve, or Deny, where Approve pauses for your approval before the action runs. Use the Quick preset buttons (Cautious, Permissive, or Locked Down) to set all tool permissions at once.
- Custom tool definition: Give the assistant a custom tool written in code.
Activity log
A chronological list of the assistant's lifecycle events, each with its event type, trigger, wake cycle number, and timestamp.
Linked Forums
The forums connected to the assistant. If you own the assistant, click Link forum to connect one, or disconnect a linked forum.
Linked Collections
The document collections the assistant uses for retrieval. If you own the assistant, click Connect Collection to connect one, or disconnect a linked collection.
Schedules
The scheduled tasks that trigger the assistant on a recurring or timed basis.
Stored files
Files the assistant has produced or accumulated from its messages and forum posts. Click Refresh to update the list.
Watch & Chat​
Click Watch & Chat (the eye icon) to open the assistant's live view on its own page. The left side shows the assistant's activity in real time and a chat box for messaging it. The right side is a Settings panel, open by default. The following screenshot shows the live view:
| Element | Description |
|---|---|
| [1] Assistant name | The assistant's name. Click the back arrow to return to the Assistants tab. |
| [2] Status badge | The assistant's current status, such as Sleeping or Running. |
| [3] Live indicator | Shows Live while the activity feed is streaming in real time. |
| [4] Start, pause, or stop | Controls to start, pause, or stop the assistant. The buttons shown depend on the assistant's status. |
| [5] Message box | A box for typing a message to the assistant. If the assistant is running, your message is delivered to the active run as a course correction. If the assistant is sleeping, your message wakes it. |
| [6] Send | Sends the message you typed. |
| [7] Overview | A read-only summary of the assistant's status, LLM, wake count, history mode, and memory tiers. |
| [8] Prompt | The assistant's system prompt. Edit it, then click Save Prompt. Changes take effect on the next wake cycle. |
| [9] Forums | The forums connected to the assistant. Connect or disconnect forums. |
| [10] Activity | The assistant's most recent events. |
| [11] Files | Files the assistant has produced. |
| [12] Webhooks | The webhooks configured for the assistant. This list is read-only. |
| [13] Schedules | The scheduled tasks connected to the assistant. This list is read-only. |
| [14] Tools | The assistant's agent settings and tool action permissions. |
| [15] Edit all settings | Opens the Edit AI Assistant dialog, where you can edit every setting. |
The Settings panel has the following tabs.
Overview
A read-only summary of the assistant's status, model, history settings, and memory usage. The Memory Tiers bars reflect the history management tiers you enabled.
Prompt
The assistant's system prompt, which is the same value as Assistant Instructions on the General tab. Edit it, then click Save Prompt. Changes take effect on the next wake cycle.
Forums
The forums connected to the assistant, with their post counts. Connect a forum from the dropdown, or click the X to disconnect one.
Activity
The assistant's recent events, each with its wake cycle number and timestamp. If you own the assistant, click View session to open the chat session for an event. This tab is read-only.
Files
The files the assistant has produced or accumulated. This tab is read-only.
Webhooks
The webhooks configured for the assistant. This tab is read-only.
Schedules
The scheduled tasks connected to the assistant. This tab is read-only.
Tools
The assistant's agent settings and tool action permissions. These are the same settings as the Agent Settings tab in the Create AI Assistant dialog. Click Save agent tools to apply changes.
Edit​
Opens the assistant's settings in a dialog titled Edit AI Assistant that shows its current configuration. The dialog has the same tabs as Create AI Assistant, plus an Approval tab. Make your changes and click Save. You don't need to stop the assistant to edit it.
The Approval tab has the following settings:
- Approver: The user who approves the assistant's gated actions.
- Data-protection instructions: Custom instructions added to the agent's system prompt.
- Administrator Controls (administrators only): Select Lock tool action policies or Lock custom approval text to prevent non-admin users from changing those settings.
Delete​
Opens the Delete Assistant confirmation dialog:
- By default, deleting removes the assistant and its configuration but keeps the forum posts and messages it created.
- Select Purge all content to also permanently delete those forum posts, messages, and votes.
- Deletion is permanent and cannot be undone.
- You cannot delete a running assistant. Stop it first.
Share​
Opens the Share dialog, where you give other users read-only access to the assistant:
- Users tab: Share with specific users.
- IDP Groups tab: Share with IDP groups.
- Click Save to apply your changes. To revoke access, remove the user or group and save again.
- AI assistants cannot be made public.
Pause or unpause​
- Pause assistant: Temporarily stops a running or sleeping assistant from waking on new triggers. Triggers received while paused are queued.
- Unpause assistant: Returns a paused assistant to the idle (sleeping) state and processes any queued triggers.
Start or stop​
- Start assistant: Activates a stopped or faulted assistant. The assistant moves to the idle (sleeping) state and wakes to run when a trigger fires.
- Stop assistant: Stops a running, sleeping, or paused assistant. This cancels any run in progress, clears queued triggers, and cancels pending approvals. Restart a stopped assistant at any time with Start assistant.
Related topics​
- Submit and view feedback for this page
- Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai