# AI bot - Agents
**URL:** https://meta.discourse.org/t/ai-bot-agents/306099
**Category:** Site Management
**Tags:** how-to, ai, ai-bot
**Created:** [April 30, 2024, 6:26am UTC](https://meta.discourse.org/t/ai-bot-agents/306099 "2024-04-30T06:26:18Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [April 30, 2024, 6:26am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/1 "2024-04-30T06:26:19Z")
> 🔖 This guide explains how to set up and manage Agents for [Discourse AI - AI bot](https://meta.discourse.org/t/discourse-ai-ai-bot/266012).
>
> 🙋 Required user level: Administrator
The Discourse AI bot includes a flexible system for managing Agents. This guide covers:
- Interaction methods for AI Agents
- Configuration options
- Advanced settings
- Supported tools
- Customization possibilities
> 🔗 Learn about the AI bot and how to enable it [in this guide](https://meta.discourse.org/t/discourse-ai-ai-bot/266012?silent=true).
## What are agents?
Agents are a powerful feature that allows you to customize the behavior of the AI engine in your Discourse forum. They act as a ‘system message’ that guides the AI’s responses and interactions, helping to create a more personalized and engaging user experience.
#### Why use agents?
With agents, you can tailor the AI’s behavior to better fit the context and tone of your forum. Whether you want the AI to be more formal for a professional setting, more casual for a community forum, or even embody a specific character for a role-playing game, agents give you the flexibility to do so.
#### Group-specific access to agents
Moreover, you can set it up so that certain user groups have access to specific agents. This means you can have different AI behaviors for different sections of your forum, further enhancing the diversity and richness of your community’s interactions.
## Interacting with Agents
Agents can be interacted with in multiple ways:
1. Private message (PM)
2. Chat direct message (DM)
3. Chat channel mentions
4. Mention in a public topic via `@example_bot_username`
Administrators can control which interaction methods are allowed for each agent via four separate toggles:
- **Allow personal messages** : Allow users to start PMs with this agent (enabled by default)
- **Allow topic mentions** : Allow `@mention` in topics to trigger a response
- **Allow chat direct messages** : Allow chat DMs with this agent (requires chat plugin)
- **Allow chat channel mentions** : Allow `@mention` in chat channels (requires chat plugin)
## Configuration
To configure Agents, navigate to `discourse.example.com/admin/plugins/discourse-ai/ai-agents`.
Key configuration options include:
- **System prompt** : Steers the conversation
- **Vision support** : Enable for Vision powered LLMs, i.e- GPT-4 Turbo, Claude 3
- **Default model** : Required for mentionable agents and agents with force default LLM enabled
- **Allowed groups** : Define permissions using Discourse group security
- **Uploads** : Index text files for additional knowledge (using RAG - Retrieval-Augmented Generation)
- **Enabled tools** : Control access to specific tools
- **Execution mode** : Choose between “default” and “agentic” mode (agentic mode enables multi-turn tool use with configurable token limits and compression)
Here’s a look at a complete AI agent configuration screen:
### Advanced configuration options
The agent editor offers several advanced options:
- **Temperature** and **top\_p** (nucleus sampling): Control creativity vs. predictability
- **Max context posts** : Limit the number of posts supplied to the LLM for history - fewer posts will reduce costs, but cause the AI to “forget” about older content (not available in agentic mode)
- **Execution mode** : “Default” for single-pass responses, “Agentic” for multi-step tool use with:
- **Max turn tokens** : Token budget for agentic execution
- **Compression threshold** : Percentage threshold for context compression (20-99%)
- **Show thinking** : Display the AI’s reasoning process to users (enabled by default)
- **Require approval** : Require human approval before certain actions are executed
- **Force default LLM** : Prevent users from switching LLMs for this agent
- **Response format** : Configure structured output format
- **Examples** : Few-shot examples to guide the AI’s behavior (pairs of user/assistant messages)
- **Upload options** :
- **Chunk tokens** : Control document splitting
- **Chunk overlap tokens** : Set overlap between chunks
- **Search conversation chunks** : Number of document fragments added to user queries
- **Question consolidator LLM** : Choose the LLM for determining user questions
- **RAG LLM model** : Choose a specific LLM for RAG processing
### Prerequisites for upload support
To use upload support:
1. Enable the `ai_embeddings_enabled` setting
2. Configure an embedding model via `ai_embeddings_selected_model`
Discourse AI supports various embedding models. Hosted customers get free access to the [bge-large-en](https://huggingface.co/BAAI/bge-large-en-v1.5) model.
> ℹ Self-hosters or people wanting more choice can self host an embedding model or use models by Open AI, Google (Gemini), and more.
### Text splitting in Discourse AI
Discourse uses a Recursive Character Text Splitter to keep paragraphs, lines, and words together when splitting text. You can control text splitting using the `[[metadata YOUR METADATA HERE]]` separator:
```plaintext
[[metadata about cats]]
a long story about cats
[[metadata about dogs]]
a long story about dogs
```
This method prevents “chunk contamination” by ensuring only relevant data is included in each chunk.
## Debugging AI agents
To debug your agent:
1. Add users to the group specified in the `ai_bot_debugging_allowed_groups` setting
2. Users in this group will see an AI debugging button at the bottom of AI posts
3. Click the button to access the debugging UI modal
> ⚠ Remember: If you provide vague or unhelpful information to an LLM, it will have great difficulty converting it into useful information.
## Supported tools
Discourse AI supports various tools, including:
### Always available
- Categories
- Time
- Search
- Read
- Database Schema
- Search Settings
- Setting Context
- Random Picker
- Web Browser
- Search [Meta Discourse](https://meta.discourse.org/)
- JavaScript Evaluator
- Researcher
- Flag Post
- Close Topic
- Unlist Topic
- Lock Post
- Delete Topic
- Edit Post
- Edit Category
- Set Topic Timer
- Set Slow Mode
- Move Posts
- Grant Badge
### GitHub integration
- GitHub File Content
- GitHub Pull Request Diff
- GitHub Search Files
These three tools are always available. Additionally:
- **GitHub Search Code** requires the `ai_bot_github_access_token` setting to be filled
### Conditional tools
- **Tags** and **Edit Tags** : Available when tagging is enabled on your site
- **Image generation** (Image, Create Image, Edit Image): Requires a [custom image generation tool](https://meta.discourse.org/t/ai-bot-custom-tool-guide/314103) to be configured via the admin UI
- **Google search** : Requires the `ai_google_custom_search_api_key` and `ai_google_custom_search_cx` settings to be filled
- **Artifacts** (Create Artifact, Update Artifact, Read Artifact): Available when `ai_artifact_security` is set to lax, hybrid, or strict
- **Assign** : Available when the Assign plugin is installed
- **Mark as Solved** : Available when the Solved plugin is installed
Some tools require additional configuration or API keys.
## Custom tool support
You can create your own tools using [custom tool support](https://meta.discourse.org/t/ai-bot-custom-tool-guide/314103).
## Customizing system agents
1. Create a new agent
2. Copy and paste the system prompt from the agent you wish to customize
3. Modify as needed
4. Optionally disable the original system agent to avoid duplication
### Customizing search
To customize search for a new agent:
1. Create a new agent
2. Add the “search” tool
3. Configure search options, including:
- Base search query
- Maximum number of search results
- Include private topics option
This allows you to delegate search permissions, increase the number of results, or restrict search to specific sections of your site.
> Last edited by @dax 2026-03-13T17:21:31Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [May 6, 2024, 1:48am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/2 "2024-05-06T01:48:58Z")
A post was split to a new topic: [Can I provide an image generator function to Discourse AI](https://meta.discourse.org/t/can-i-provide-an-image-generator-function-to-discourse-ai/306858)
---
### Author:  [@MachineScholar](https://meta.discourse.org/u/MachineScholar)
#### Post date: [September 1, 2024, 8:32pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/3 "2024-09-01T20:32:13Z")
> [@Discourse](#):
>
> Read
What exactly does the Read tool do?
Also, [mentions on posts are currently broken per this bug report](https://meta.discourse.org/t/job-exception-undefined-method-scheduled-for-nil-error-when-mentioning-ai-persona-in-post/324214).
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [September 2, 2024, 5:10am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/4 "2024-09-02T05:10:10Z")
> **[\[Untitled AI bot PM\]](https://meta.discourse.org/discourse-ai/ai-bot/shared-ai-conversations/9BOft0FUJA_OwyVwuTlAcA)**
>
> sam: What does the ReadTool in discourse/discourse-ai
In a nutshell it allows the LLM the ability to read topics and posts on your forum.
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [September 2, 2024, 6:22am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/5 "2024-09-02T06:22:37Z")
Basically it reads a topic/post when url, name or ID is given and otherwise, or still, it uses embeds and what, when, why and how depends model itself, prompting etc?
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [September 2, 2024, 6:33am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/8 "2024-09-02T06:33:57Z")
Oh sorry was replying to a different post 🙂
It uses topic ID or topic ID + Post Number to find the raw markdown for a topic/post with some guards for max length.
Does not depend on embedding.
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [September 3, 2024, 9:13pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/9 "2024-09-03T21:13:21Z")
A bit off-topic, but because I don’t have anything to ask and you guys will clean these topics every now and then, I don’t care.
Automatic titles in PMs with AI are now in the right language. Not a biggie, but its psychological value is big. Thanks!
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [October 22, 2024, 2:38pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/10 "2024-10-22T14:38:50Z")
is there any way to add the Bot users to a group? I basically want to add an avatar flair to those users, but when adding them to a group, they don’t show up
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [October 22, 2024, 2:43pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/11 "2024-10-22T14:43:34Z")
They don’t show up, but are still there. You can be sure by trying add an AI person second time. Or you see needed group on settings of those pseudo users.
---
### Author:  [@MachineScholar](https://meta.discourse.org/u/MachineScholar)
#### Post date: [November 21, 2024, 7:12pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/12 "2024-11-21T19:12:25Z")
Which part of the Discourse AI repo should I check out if I want to precisely know how the AI bot’s tools work?
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [November 22, 2024, 1:20am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/13 "2024-11-22T01:20:34Z")
Tool, Playground, Bot are all good areas to start with.
See this for example: [Understanding Tools in Discourse AI System - AI Conversation - Discourse Meta](https://meta.discourse.org/discourse-ai/ai-bot/shared-ai-conversations/-Wx0xNU15Ed-17XvodBUPw)
---
### Author:  [@MachineScholar](https://meta.discourse.org/u/MachineScholar)
#### Post date: [November 22, 2024, 9:48am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/14 "2024-11-22T09:48:48Z")
Precisely the answer I was looking for — thank you kind sir! For anyone it may pertain to: I recommend reading through [the code in this repo](https://github.com/discourse/discourse-ai/tree/main/lib/ai_bot/tools) to be able better steer your prompts for your persona’s tools.
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [July 29, 2025, 5:33am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/16 "2025-07-29T05:33:14Z")
A post was split to a new topic: [Engineering a persona to lean on chat history](https://meta.discourse.org/t/engineering-a-persona-to-lean-on-chat-history/376342)
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 15, 2025, 1:18pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/17 "2025-08-15T13:18:38Z")
I am currently trying to fetch all posts from a topic via the “Read” tool, but it only provides a maximum of 100 posts to the LLM model. I already set “Max posts” to 999 in persona settings, but the issue persists.
Could there be any server-side API request limitation causing the issue?
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 22, 2025, 9:33am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/18 "2025-08-22T09:33:24Z")
@sam any idea on this one what could be the cause for the 100 post limit that I am encountering?
---
### Author:  [@MachineScholar](https://meta.discourse.org/u/MachineScholar)
#### Post date: [August 22, 2025, 7:13pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/19 "2025-08-22T19:13:57Z")
I haven’t checked the codebase, but I suspect it may be a hard limit set in the code itself. May I ask what it is that you’re trying to achieve with this? That is a key factor here.
And perhaps it may be best to use the Forum Researcher persona?
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 22, 2025, 8:09pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/20 "2025-08-22T20:09:47Z")
We have “journal/log” category which often contain several hundred posts where the topic owner reports about his project progress over a span of 4-5 months.
My goal is to fetch all posts within that topic, filter them by author = topic owner and create a summary.
We considered using the researcher persona, but cuttently it doesn’t support vision. We also want to process users’ images.
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [August 22, 2025, 10:56pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/21 "2025-08-22T22:56:09Z")
Oh you got to use forum researcher for this, it’s an exact use case for the persona
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 23, 2025, 10:50am UTC](https://meta.discourse.org/t/ai-bot-agents/306099/22 "2025-08-23T10:50:11Z")
> [@Forum Researcher AI Agent guide](https://meta.discourse.org/t/forum-researcher-ai-agent-guide/368942/1):
>
> Currently, there is no option to send images to the research LLM. This will be considered in future versions.
@sam I would love to, but currently it doesn’t support images. Is that something on the roadmap or not a priority at the moment?
---
### Author:  [@sam](https://meta.discourse.org/u/sam)
#### Post date: [August 23, 2025, 10:20pm UTC](https://meta.discourse.org/t/ai-bot-agents/306099/23 "2025-08-23T22:20:24Z")
Sure I can add that , not too big of a change
[Next page](https://meta.discourse.org/t/ai-bot-agents/306099.md?page=2)